如何在 VPS 上部署 OpenHands AI 代理

什麼是 OpenHands，以及首要理解的風險

OpenHands（前身為 OpenDevin）是一個自動化軟體工程代理程式。您只需以自然語言下達任務，它便會規劃工作、編寫程式碼、執行指令、讀取輸出，並持續迭代直到任務完成。您可以在自己的伺服器上透過 Docker 執行它，並連接至語言模型。在 VPS 上，它會成為一個能在您離線時持續運作的程式設計代理。

有一項事實應主導您的整體架構規劃。OpenHands 不僅僅是建議程式碼，它還會實際執行程式碼。為了達成此目的，其控制器容器會掛載主機的 Docker socket 於 /var/run/docker.sock，以便為每個任務產生沙盒容器。任何能與該 Docker socket 通訊的程式，都能啟動一個掛載您整個主機檔案系統的新容器，這意味著存取該 socket 等同於擁有機器的 root 權限。因此，請將 OpenHands 所在的機器視為一台執行不受信任程式碼的伺服器，因為這正是它的運作方式。以下所有的強化措施皆基於此前提。

所需準備

您需要一台執行 Ubuntu 24.04 並安裝最新版 Docker Engine 的 VPS，記憶體至少 4 GB，以及一組語言模型（OpenAI、Anthropic 或 Google）的 API 金鑰，或是透過 同一台 VPS 上的 Ollama 提供的本地模型。OpenHands 支援數十種模型後端，您可以自行選擇。如果您從未設定過容器，VPS 上的 Docker 基礎 一文涵蓋了本指南所需的先備知識。

使用 Docker 安裝

OpenHands 提供兩種映像檔：您執行的應用程式映像檔，以及用於執行各項任務沙盒的代理伺服器（agent-server）映像檔。請依照下列方式執行，並替換為專案文件中對應的當前標籤（tag）：

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands \
  docker.openhands.dev/openhands/openhands:1.8

有兩個細節能避免您浪費時間除錯。應用程式映像檔與代理伺服器映像檔刻意使用不同的版本號，請勿嘗試將其統一：請使用文件中與您的應用程式版本配對的代理伺服器標籤。此外，請注意 -p 127.0.0.1:3000:3000 與 -p 3000:3000 的差異。這一個參數的變更，決定了 Web UI 是僅限您本人存取，還是開放給整個網際網路存取，後者將於下一節說明。

將 Web UI 限制在非公開網路

OpenHands 會在 3000 埠提供介面。由於該介面可控制執行程式碼的代理程式，若將其公開至網際網路，任何發現該位址的人都能遠端存取可執行指令的處理程序。請如上述執行指令般將其綁定至 loopback 位址，並透過 SSH tunnel 從您的筆記型電腦進行連線：

ssh -L 3000:127.0.0.1:3000 you@your-vps

接著在您的本機開啟 http://127.0.0.1:3000。流量會透過現有的 SSH 連線傳輸，且公開網路上不會有任何新增的監聽埠。並非所有代理程式都需要開啟埠：在同一台 VPS 上執行的 Claude Code 工作階段會透過終端機進行通訊，因此您唯一需要暴露的只有 SSH 本身。這種「綁定 loopback 並透過 tunnel 連線」的習慣，應應用於您託管的每一個代理程式儀表板；透過 tunnel 存取 open-kritt 的掃描 UI 方式相同，僅需將埠改為 5173。若需更永久的設定，請將其置於 VPN 後方。無論採取何種方式，請務必在伺服器前方部署預設拒絕（default-deny）的防火牆，以防意外暴露服務；同時請記住，僅涵蓋 IPv4 的防火牆會導致相同的埠在 IPv6 上保持開放，這就是許多人常忽略的 IPv6 防火牆漏洞。

隔離模型金鑰與儲存庫憑證

OpenHands 需要 API 金鑰來存取模型，通常也需要 Token 來複製與推送程式碼至儲存庫。這兩者皆具備金錢支出與代表您執行操作的權限，請務必視同密碼妥善保管。請將其存放在僅有特定帳號可讀取的環境變數檔案中，切勿直接寫入執行指令，以免洩漏至 shell 歷史紀錄與處理程序清單，亦不可存放在 git 儲存庫內的任何檔案中。若您將原始憑證存放在自架的密碼管理員中，請同時強化該伺服器的安全性；因為保險庫的弱點通常在於管理員 Token 與備份檔案，而非加密項目本身，詳情請參閱 Vaultwarden 加固指南。

在可拋棄的機器上執行

由於 controller 必須持有 Docker socket，因此無法將 OpenHands 與其宿主機完全隔離。最誠實的緩解方式是透過部署位置進行隔離：請將 OpenHands 執行在專用的 VPS 上，該機器不應存放任何其他重要資料，切勿將其與執行資料庫或網站的伺服器共用。開始前請先建立快照，並在需要時從該快照還原，不要信任一台已經執行過代理程式所撰寫程式碼長達一週的機器。一台廉價、可拋棄且具備單一用途的 VPS 是最適合的環境。部署位置是 OpenHands 目前唯一能提供的隔離手段；若您希望進一步控制代理程式在停止詢問前可執行的操作權限，Claude Code 的權限模式 展示了在無人監控的伺服器上，該如何運用這第二道防線。

強化伺服器安全性

其餘步驟屬於標準的伺服器維護規範，由於此工作負載的風險高於一般應用，這些規範顯得格外重要。請建立一個無特權的系統管理員帳號，避免直接以 root 身分操作，詳情請參閱 以無特權使用者身分執行服務。將 SSH 設定為僅限金鑰驗證。接著執行下方的檢查清單，並將其存放在容易查閱的位置。

若想深入理解各元件的運作機制而非僅是執行指令，請參閱 在 VPS 上建構自己的 AI 代理；若偏好低程式碼平台，自架 Dify 是較為平緩的入門途徑。

FAQ

在伺服器上執行 OpenHands 安全嗎？

若謹慎處理則相對安全，但由於它會編寫並執行程式碼，且其控制器持有主機的 Docker socket（這等同於擁有機器的 root 權限），因此風險高於一般網頁應用程式。請將其部署在專用且可隨時捨棄的 VPS 上，且該機器不應存放其他重要資料。請透過 SSH tunnel 或 VPN 將其 Web UI 限制在 loopback 介面上，隔離其金鑰並強化系統安全性。切勿將其與重要服務部署在同一台機器上。

為什麼 OpenHands 需要 Docker socket？

OpenHands 會在獨立的沙盒容器中執行各項任務，並透過將 /var/run/docker.sock 掛載至控制器來要求主機的 Docker daemon 建立這些容器。這賦予了控制器容器對主機 Docker 的控制權，此權限極大且具風險，因此必須將主機視為執行不受信任程式碼的環境。

OpenHands 可以使用本地模型而非付費 API 嗎？

可以。OpenHands 支援由 Ollama 或 vLLM 提供的本地模型，因此您可以完全自架，無需支付 Token 費用，資料也不會離開您的伺服器。您需要一台記憶體足以執行高效能程式碼模型的機器，硬體需求與 Ollama 指南中所述的規格相同。

我應該在主伺服器上執行 OpenHands 嗎？

不應該。由於它會執行由代理程式（agent）編寫的程式碼並持有 Docker socket，請將其保留在獨立、單一用途且您隨時願意重灌的 VPS 上。若將其與資料庫、網站或其他服務共存，一旦代理程式發生錯誤或軟體本身存在漏洞，可能會波及不該觸及的資源。