OpenHands 功能總覽:自託管的 AI 開發代理控制中心

3 分鐘閱讀時長

發布時間:

OpenHands 功能總覽:自託管的 AI 開發代理控制中心

OpenHands Logo

Agent Canvas 自動化介面預覽

OpenHands(github.com/OpenHands/OpenHands)是 GitHub 上最受關注的開源 AI 開發代理專案之一。專案現以 Agent Canvas 為核心——一個「自託管的開發者控制中心」,用來統一管理與運行各種编码 AI 代理(OpenHands 自身、Claude Code、Codex、Gemini CLI 等),並讓代理依排程或事件自動執行日常任務。

基本資訊

項目內容
Stars~89,800 ⭐
Forks~11,900
LicenseMIT
主要語言TypeScript(前端)+ Python(Agent Server/SDK)
現行版本Agent Canvas 1.24.0(2026-09-25 發布,發版節奏約每週)
專案狀態Beta
官網openhands.dev
文件docs.openhands.dev
建立時間2024-03

核心定位

The self-hosted developer control center for coding agents and automations.

Agent Canvas 把你的编码代理變成一個「自託管、永遠在線的工程團隊」。它是一個開發者控制中心:

  • 啟動與代理的對話、管理對話
  • 自動化日常任務——例如自動產生報告發佈到 Slack、自動把 GitHub issue 拆解成任務
  • 預設在本機運行,也能連到 Docker、VM、雲端等多種「代理後端」
  • 可選擇跑在 OpenHands Cloud / Enterprise(商業服務)上

核心功能

1. 多代理統一介面(ACP Agents)

透過 Agent Client Protocol(ACP)——一個以 stdio JSON-RPC 溝通编码代理的標準協議——Agent Canvas 不只跑自家 OpenHands 代理,還能驅動任何第三方代理:

代理預設啟動命令訂閱登入(自動偵測)API Key
Claude Codenpx -y @agentclientprotocol/claude-agent-acpClaude Pro/Max 登入(macOS Keychain 或 ~/.claude/.credentials.json)ANTHROPIC_API_KEY
Codexnpx -y @zed-industries/codex-acpChatGPT 登入(codex login,快取於 ~/.codex/auth.json)OPENAI_API_KEY
Gemini CLInpx -y @google/gemini-cli --acpGoogle 登入(快取於 ~/.gemini/oauth_creds.json)GEMINI_API_KEY
自訂 ACP server自訂命令—自訂環境變數

運作方式:Agent Server 把代理自己的 CLI 當成子程序啟動並轉發每一輪對話;外部代理管理自己的 LLM、工具與執行,Canvas 只負責送訊息與渲染結果。若本機已登入該代理的 CLI,會自動沿用登入,通常不需要 API Key(訂閱登入優先於 API Key)。

2. 多後端切換(Backends)

任何 Canvas 前端可連任何 Agent Server 後端,UI 裡的 backend switcher 可新增/編輯/移除後端(名稱、host URL、API Key)。

  • Local:本機直接跑(agent-canvas 自動建立本地後端)
  • Remote:同機獨立程序、自託管 VM/容器、團隊共用伺服器
  • Cloud / Enterprise:OpenHands 託管的沙箱與組織服務
  • 支援 VM、Docker、Kubernetes (Helm)、Modal 等自託管後端服務

Settings、LLM 設定、MCP servers、automations 都依「作用中後端」分域——切換後端會一起切換這些設定。

3. 自動化(Automations)

Automation Server 讓代理依排程或事件(webhook)執行。內建 4 種預置自動化:

自動化功能
Issue to Pull Request自動實作 issue tracker 的 issue 並建立 PR
GitHub PR Review Assistant自動審查 PR 並以留言回覆意見
GitHub Repository Monitor監控 repo 事件並觸發代理動作
Slack Channel Monitor聆聽 Slack 頻道,訊息符合模式時觸發代理
  • 建立方式:從對話中請 OpenHands「幫你建立自動化」,或從 Automations 檢視的推薦流程
  • 部分目錄項目附 script bundle(確定性腳本包:polling、去重、固定 API 呼叫),代理只負責需要判斷的部分
  • 一個自動化可同時監控多個 repo
  • 可整合 Slack、GitHub、Linear、Notion、Datadog 等第三方服務
  • 自動化可指定 LLM profile 與 agent profile;與 Git 同步自動化設定

4. LLM Profiles(多模型設定檔)

  • Bring your own model:支援任何 LiteLLM 支援的模型(Anthropic、OpenAI、Mistral、OpenHands provider 等已驗證)
  • 每帳號最多 10 個 profile,可命名、編輯、設為預設、刪除
  • 對話中即時切換模型:chat 輸入框的 profile selector,或 /model 斜線指令(/model 列出、/model <name> 切換),不失去上下文
  • 常見玩法:強模型規劃 → 低成本模型實作
  • 讓代理自己選模型:OpenHands profile 開啟「Let the agent switch LLM profiles」後,代理取得 SwitchLLMTool,會在對話時間軸顯示 Switch LLM profile 事件與理由
  • 本地 LLM profile 儲存前會先對後端驗證(無效 key / 模型不存在會擋下)

5. Agent Profiles(代理設定檔)

  • Agent Profile 決定「哪個代理跑對話」;LLM Profile 決定「OpenHands 代理用哪個模型」——兩層分開管理
  • 對話開始前可選 agent profile;開始後不能換
  • Secret scope:可設定 profile 能存取哪些 secrets(All / None / Selected),由 Agent Server 執行管制
  • MCP server scoping:profile 可限定只使用部分 MCP servers 的工具

6. Critic(成功機率評估)

Critic 是额外的評估層:審查代理的工作並預測任務成功機率,結果以「成功likelihood 分數 + 問題標籤」顯示在對話時間軸。可設定低分時代理自動改進。OpenHands 託管的 critic 目前免費(用 OpenHands Provider LLM Key 認證)。僅適用於 OpenHands 代理對話。

7. 對話與工作區管理

  • 對話 UI:聊天、終端機、瀏覽器、檔案、設定、自動化檢視
  • 每個對話可跑在獨立 Docker 容器(OH_CONVERSATION_RUNTIME=docker),容器替換後工作區檔案與對話歷史保留
  • 支援手機/平板存取

8. MCP 與 Plugins

  • 支援 Model Context Protocol(MCP)servers,自動化安裝與管理
  • Plugins / Agent Plugins Packages 擴展代理能力

9. 記憶壓縮(Memory Condensation)

Memory condenser 在長對話中摘要歷史、只保留最重要的資訊,降低延遲與 token 消耗,可設定觸發摘要的事件數。

系統架構

Agent Canvas 架構圖

Agent Canvas 是多倉庫系統的一環:

倉庫職責
OpenHands/OpenHandsAgent Canvas 前端、使用者控制中心、後端選擇、本地堆疊編排
OpenHands/software-agent-sdkPython SDK、Agent Server、agents、tools、conversations、workspaces、events、正式 server API
OpenHands/typescript-client瀏覽器相容的 TypeScript client(Agent Server API)
OpenHands/automation自動化定義、排程、webhooks、執行歷史、派遣
  • Agent Server:單機單 port 的 REST API,可跑多個代理;Canvas 可連多個 Agent Server 並切換
  • Automation Server:排程/事件觸發,決定何時跑,派遣對話到 Agent Server
  • Ingress:把前端、Agent Server、自動化流量路由到同一個本地 origin
  • 前端是 React + TypeScript(src/api、src/components、Zustand stores、i18n)

安裝方式

前置:Node.js 24+、uv

選項 1:無沙箱(直接裝在本機,代理有完整檔案系統存取權)

npm install -g @openhands/agent-canvas
agent-canvas

可拆分執行:agent-canvas --frontend-only / --backend-only。UI 在 http://localhost:8000。本地監聽預設僅 loopback(127.0.0.1);--host 0.0.0.0 需走 API key 畫面。

選項 2:Docker 沙箱

export PROJECTS_PATH="$HOME/projects"
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
  -v "$HOME/.openhands:/home/openhands/.openhands" \
  -v "${PROJECTS_PATH}:/projects" \
  ghcr.io/openhands/agent-canvas:1.24.0

代理只能存取 PROJECTS_PATH 下的專案。UI 在 http://localhost:8000/canvas。

選項 3:多 Docker 沙箱(並行多代理)

npm install -g @openhands/agent-canvas
OH_CONVERSATION_RUNTIME=docker agent-canvas

每個新對話一個容器,各自有 Agent Server 與工具;Canvas 在 host 路由對話請求。

選項 4:從來源

git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands && npm install && npm run dev

自託管(server / 雲端 VM)

最強大的跑法是跑在雲端 server:筆電關機代理仍繼續運行,且方便被 Slack、GitHub、Datadog 等第三方服務觸發。詳見 docs/SELF_HOSTING.md(含安全加固)。也可以跑多台後端——例如與團隊共用一台做 code review 與依賴更新的 Agent Server,自己的代理跑在筆電上,同一個 Canvas 前端切換。

安全性

  • 無沙箱模式代理有完整檔案系統存取權——README 明確警告,建議筆電使用 Docker 沙箱模式
  • 本地監聽預設 loopback only,避免 session key 被網路其他機器取得
  • 公開/LAN 曝露時不注入 session key,改用 API key 進入畫面;建議設 LOCAL_BACKEND_API_KEY 強值
  • 自託管建議一般 server 加固:認證、HTTPS、防火牆、謹慎的工作區範圍
  • Secrets 集中管理(Settings → Secrets),profile 可做 secret scope 限定

與其他代理工具比較

面向OpenHands Agent CanvasClaude Code / Codex CLIOpenClaw 類
定位自託管控制中心 + 自動化平台單一代理 CLI個人助理 gateway
支援代理自家 + 任何 ACP 代理(Claude/Codex/Gemini/自訂)僅自家各家 LLM
後端本機/Docker/VM/K8s/Modal/雲端,可切換本機本機
自動化排程 + webhook 事件、預置 4 種、Git 同步無排程
模型管理10 個 LLM profile、對話中切換、代理自選固定可切換
品質評估Critic 成功機率評分無無
部署npm 一行 / Docker / 自託管CLI 安裝CLI 安裝
LicenseMIT專有開源

總結

OpenHands 從 2024 年的「開源 coding agent」演化成 2026 年的代理控制中心平台:把 OpenHands、Claude Code、Codex、Gemini 等代理收進同一個自託管 UI,加上多後端切換、排程/事件自動化、多模型 profile 管理、Critic 品質評估與 Docker 沙箱隔離。適合想把 AI 工程團隊「永遠在線」跑在自己伺服器、並讓代理自動處理 issue→PR、PR review、Slack 監控等日常工作的開發者與團隊。

參考連結