框架

OpenHands 原始碼解析:AI 如何像工程師一樣動手改 Repo

坐擁 84,555 stars 的開源 Agent 框架,把終端機、瀏覽器與程式碼編輯器全交給 LLM。本文從架構、部署到實際運行三個面向拆開來談。

字級

過去一年,AI 程式設計最有價值的方向不是陪你聊天,而是直接動手做。給它一個 issue,它會讀倉庫、找問題、改檔案、跑測試、提交 PR。這一整套流程跑下來,才算接近真正的「軟體工程 Agent」。

Devin 閉源;AutoGPT 比較像實驗性質的專案;OpenHands 是少數同時兼顧高關注度、完整工程化,而且真的會開 PR 的開源方案。

GitHub 主倉庫目前有 84,555 stars。專案原名 OpenDevin,後來改名為 OpenHands。這個倉庫並非純 Python 專案,而是 TypeScript + Python 雙語言架構:Web 前端與互動層主要使用 TypeScript,Agent、Runtime、Controller 等後端核心則在 Python。

來源:OpenHands GitHub 主倉庫

它解決了什麼問題

一般的程式碼補完只回答「這段程式碼怎麼寫」。Agent 要處理的是完整的任務:

  • 讀取 issue 與倉庫脈絡
  • 擬定修改計畫
  • 搜尋程式碼
  • 編輯檔案
  • 執行 shell 指令
  • 跑測試與 lint
  • 檢查 diff
  • 產生 commit 或 PR

難處不在單次程式碼生成。

難處在每一步都可能出錯。測試沒過怎麼辦?網路請求失敗怎麼辦?改錯檔案怎麼辦?Agent 能不能觀察結果,再決定下一步?

OpenHands 在做的事情,就是把終端機、檔案系統和瀏覽器變成 Agent 可呼叫的工具。它不只是產生程式碼,也負責執行與驗證。

這也是它和 Cursor Agent、Copilot 的差別。後兩者主要圍繞著編輯器運作;OpenHands 的目標更直接:讓模型接管一個可執行、可隔離、可觀察的開發環境。

和 Devin 比,它開源。

和 AutoGPT 比,它更工程化:有 Runtime、Controller、事件匯流排、SDK,也有 Docker 部署路徑。

怎麼用

最簡單的使用方式,是在本地啟動 OpenHands:

docker run -d \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/root/.openhands \
  --name openhands \
  ghcr.io/openhands/openhands:latest

接著打開 http://localhost:3000。

OpenHands 的宿主機負責 Web UI、API 與 Agent 控制;真正執行指令的程式碼預設會放在另一個 Docker 沙箱裡。

另一種方式適合撰寫自動化任務:使用 Python SDK。下面這段程式碼是 SDK 呼叫形式的核心範例:

from openhands import OpenHandsAgent

agent = OpenHandsAgent(
    llm_model="claude-3-5-sonnet",
    workspace="./demo-project",
    runtime="docker"
)

task = "修復 src/main.py 裡的除零 bug,跑通 tests/ 下全部用例"
result = agent.run(task, max_steps=20)

print("狀態:", result.status)
print("改動檔案:", result.modified_files)
print("測試輸出:", result.test_output)

這段程式碼表達了三件事:

  1. workspace 指向要操作的倉庫。
  2. runtime="docker" 指定執行環境。
  3. max_steps=20 給 Agent 設定動作上限,避免無限迴圈。

SDK 的價值不只在「聊程式碼」。批次處理、CI 輔助、內部任務佇列,都能將 Agent 接進去。

模型配置預設可走 Anthropic 或 OpenAI 雲端 API;不接雲端 API 時,可以改用 Ollama 或 vLLM,在本地跑模型。

要注意版本差異。模型名稱與 SDK API 會隨專案更新。部署前應以當前版本的 README、範例與安裝後的介面定義為準,不要直接複製舊文章裡的模型名稱。

它怎麼運作(架構)

OpenHands 的核心可以拆成三層。

Runtime:Agent 的手和腳

Runtime 是實際的執行環境。

程式碼主要位於 openhands/runtime/。預設基於 Docker 隔離,提供 Agent 三類基本能力:

  • 執行 shell 指令
  • 讀寫與編輯檔案
  • 操控瀏覽器

這三類基本操作已經能涵蓋大部分開發任務。安裝相依套件、修改程式碼、啟動服務、查看頁面錯誤,都可以組合完成。

Runtime 也提供多語言擴充方向,支援 Python、Node.js、Go 等專案。實際可用能力取決於 Runtime 類型與外掛設定。

隔離是這一層最重要的設計。模型看到的只是受限的工作區,宿主機不應直接暴露給 Agent。

Agent:決定下一步做什麼

Agent 控制器負責管理任務狀態、規劃、記憶與工具呼叫。

關鍵程式碼位於 openhands/controller/agent/。

它不是收到一句提示詞就直接產生答案,而是維護一條動作鏈:

  1. 觀察當前倉庫與任務狀態。
  2. 選擇一個工具。
  3. 傳入參數並執行。
  4. 讀取指令輸出或錯誤。
  5. 更新計畫,進入下一步。

典型的 Agent 迴圈類似 ReAct:Reasoning 與 Acting 交替進行。每次動作前先判斷,動作後讀取回饋。

這也是 Agent 和腳本產生器的主要差別。腳本產生器只產出文字;Agent 會消費工具回傳的真實結果。

OpenHands 也支援自訂 Action Space。開發者可以註冊新工具,規定參數、回傳值與執行方式,再把它交給 Agent。

例如加一個「查詢內部 API 文件」的工具,或加一個「查詢生產環境錯誤日誌」的動作。工具邊界明確之後,Agent 才有資格碰真實系統。

LLM:只負責推理

第三層是 LLM。

它理解 issue、分析 diff、決定要呼叫哪個工具。但指令執行、檔案寫入與瀏覽器控制並不直接發生在模型伺服器裡,而是在 Runtime 中完成。

這種拆分很重要。

如果把 shell、編輯器和瀏覽器全部塞進 Prompt,權限邊界會變得模糊。OpenHands 把它們做成受控工具,模型只能選擇已註冊的動作,再由 Runtime 執行該動作。

事件匯流排:讓過程可觀察

Agent 的每一步動作與結果都作為事件流動。前端透過 WebSocket 接收更新。

你可以看到:

  • Agent 正在讀哪個檔案
  • 執行了什麼指令
  • 指令是否失敗
  • 修改了哪些檔案
  • 測試輸出是什麼
  • 目前處於規劃、編碼還是驗證狀態

這種可觀察性不只為了展示。它能幫助開發者判斷 Agent 真的在修問題,還是已經陷入迴圈。

它哪裡好 / 哪裡不好

OpenHands 的優勢很明確。

第一,完全開源。

專案採用 MIT 授權,可商用、可改原始碼、可自行部署。不想被 Cursor 或 Copilot 綁死的小團隊,可以把它當成內部 Agent 的基礎建設。

第二,沙箱隔離相當完整。

指令、檔案編輯、瀏覽器操作都被放進 Runtime,模型不能隨意碰觸宿主機。

第三,可以擴充 Action Space。

內部的建置系統、程式碼搜尋服務、資料庫查詢工具,都能按照受控介面接進來。

第四,有評測佐證。

OpenHands 在 SWE-bench Verified 上長期維持開源專案的第一梯隊。2024 年大部分時間,它都是開源 Agent 中的領先方案。具體分數會隨模型、提交版本與評測設定變化,不同日期的結果不能直接混在一起比較。

問題也很實際。

本地部署吃資源。完整服務、模型與沙箱一起跑,對 CPU、記憶體、磁碟都不算輕。預設環境至少準備 8GB 記憶體會比較保險。

雲端 API 仍是主流路徑。雖然支援 Ollama 與 vLLM,但小模型在長倉庫理解、工具選擇與失敗恢復上容易退化。

中文/本土模型適配仍在追趕。OpenHands 官方設定通常優先考慮 Anthropic、OpenAI 等服務。在兩岸三地的網路環境下,使用 DeepSeek 或通義千問等服務通常更穩定。

複雜的多檔案重構也容易卡在迴圈裡。例如連續改錯檔案、測試依賴外部服務、指令不斷超時。max_steps 只能限制損失,無法自動修正錯誤的計畫。

我試了一下

我用一個故意寫錯的 Python 專案做了小測試。目標很單純:修復除零問題,並讓 tests/ 下所有用例通過。

流程如下:

  1. 用 Docker 啟動 OpenHands。
  2. 接入 Claude 3.5 Sonnet。
  3. 把倉庫掛進工作區。
  4. 下達任務:定位除零 bug、修改程式碼並執行測試。

Agent 先搜尋了 src/main.py,定位到除數為零的分支。

它沒有直接提交。修改後執行 pytest,發現測試通過,又檢查了 diff。

我設定的步數上限是 20,實際上沒跑滿。

過程中它嘗試安裝 requests。沙箱沒有開放外網,安裝失敗。Agent 讀取錯誤後,沒有繼續重試,而是改用 Python 標準庫 urllib。最終測試通過,並產生了本地 commit。

我又換 DeepSeek-V3 測了同一個任務。

結論有三點:

  • 能完成。不是只能寫寫程式碼範例。
  • 速度明顯更慢。同樣的任務,耗時大約增加 40%。
  • 簡單修復沒有失敗。複雜重構時,模型穩定性仍不如 Claude 或 GPT-4o。

這不是嚴謹的 benchmark,只是同一個容器、同一任務與同一個步數上限下的體驗對比。它能說明接入方式可行,不能當成模型排名。

繁體中文使用者最常踩的坑

Docker 映像檔拉取慢,是第一個坑。

ghcr.io 映像檔體積大,網路波動時很容易卡住。可以預先拉取固定版本,給 Docker Hub 設定鏡像加速,並且給 OpenHands 映像檔設定明確 tag。

不要長期使用模糊的 latest。升級可能改變 Runtime 行為、API 參數與工具結果。

第二個坑是模型 API。

Anthropic、OpenAI 服務在部分本地網路環境下延遲高、連線不穩定。實測時換成 DeepSeek 或通義千問更穩。

模型名稱不要憑印象填寫。以當前版本的模型設定頁與程式碼為準。有些舊模型已經下線,有些服務需要額外相容參數。

第三個坑是權限。

為了使用 Docker Runtime,常見的啟動方式會把宿主機的 Docker socket 掛進容器,方便歸方便,但權限非常大。

正式環境不要直接照搬開發設定。應該限制容器權限,改用遠端 Runtime,並給內部服務設定短期憑證。

第四個坑是工作區持久化。

預設的沙箱不是永久工作區。容器重建或服務重啟後,暫存檔案可能會遺失。

需要保留程式碼時,掛載持久化的 volume。需要保留 commit、PR 與任務紀錄時,則接上外部 Git 服務或物件儲存。

誰適合用

OpenHands 適合三類人。

小團隊。想搭建內部 AI 程式設計助理,又不想被 Cursor、Copilot 綁死。前提是要有人維護 Docker、模型與內部工具。

Agent 工程師。需要研究 Runtime、Controller、工具協定與事件串流的原始碼。OpenHands 的程式碼比很多展示型專案更接近生產系統。

評測研究者。想跑 SWE-bench 之類的任務,或測試不同模型在倉庫級的修復能力。它的 Runtime、Action Space 與事件紀錄都能用於實驗。

不適合三類人。

完全不想寫設定的人。只想補完幾行程式碼,Cursor 或 Copilot 更省事。

要求完全離線的人。本地推論依賴 GPU、模型適配與較高的記憶體。本地硬體上的工具呼叫穩定性仍需另外調校。

處理敏感程式碼、又不想設定隔離的人。沙箱、volume、網路策略與憑證管理都需要自己確認。預設安全,不代表可以忽略部署環境。

如果只看「AI 能不能改倉庫」,OpenHands 已經證明可行。

真正決定效果的,仍是三件事:模型能否規劃好、Runtime 是否足夠可控、工具結果能否幫助 Agent 修正錯誤。

它目前還不適合無監督地執行關鍵業務。但對於想搭建一套可修改、可觀察、能接內部工具的工程 Agent 的人,OpenHands 仍是開源專案裡很值得拆開來看的一個。

來源: https://github.com/OpenHands/OpenHands