如何在 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 上，該主機不要存放其他重要資料，也不要使用同時執行資料庫或網站的伺服器。開始前先建立 snapshot，之後從該 snapshot 重建環境，不要繼續信任已執行 agent 撰寫程式碼一週的主機。便宜、可拋棄且只執行單一用途的 VPS，才適合用來執行它。

不過，部署位置並不是唯一可調整的設定。OpenHands 也能控制 agent 在停止並要求確認前可以執行多少操作。截至 2026-10-11，其 CLI 文件列出 3 種確認模式：預設的純 openhands 會一律要求確認；openhands --always-approve 會自動核准每個操作，但文件標示為「謹慎使用」；openhands --llm-approve 則將決定交給以 LLM 為基礎的安全分析器。SDK 也提供相同的確認原則選擇：AlwaysConfirm、NeverConfirm 和 ConfirmRisky。ConfirmRisky 只會針對具風險的操作要求確認，並且需要安全分析器。Docker sandbox 文件另外提供更多設定。SANDBOX_VOLUMES 用來設定要掛載到 sandbox 的內容；任何以可讀寫方式掛載到 /workspace 的內容，都可能被 agent 修改，因此只能掛載工作所需的內容。AGENT_SERVER_USE_HOST_NETWORK=true 會讓 sandbox 使用 host-network 模式，並透過 8000 等固定埠運作；除非確實需要，否則應保持停用。在無人監看的伺服器上，應保留核准流程，不要自動核准所有操作；Claude Code 的權限模式可用來比較第二個控制項在無人值守主機上的運作方式。

強化伺服器安全性

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

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

FAQ

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

妥善防護後可以，但風險高於一般 Web 應用程式，因為它會寫入並執行程式碼，而且其控制器持有主機的 Docker socket，實際上等同於在該機器上擁有 root 權限。請在專用且可拋棄的 VPS 上執行，不要在其中存放其他重要資料；將其 Web UI 綁定於 loopback，並透過 SSH tunnel 或 VPN 存取；隔離其金鑰，並強化該主機的安全設定。不要讓它與重要服務共用主機。

OpenHands 為何需要 Docker socket？

OpenHands 會在全新的 sandbox container 中執行每項工作，並要求主機 Docker daemon 建立這些 container，方法是將 /var/run/docker.sock 掛載至其控制器。這會讓控制器 container 能夠控制主機上的 Docker，權限很高且風險很大，因此必須將該主機視為會執行不受信任程式碼的主機。

OpenHands 可以使用本機模型，而不是付費 API 嗎？

可以。OpenHands 支援由 Ollama 或 vLLM 提供的本機模型，因此您可以完全自行代管，不必支付逐 token 費用，資料也不會離開伺服器。您需要一台記憶體足以執行高效能程式碼模型的機器；這是 Ollama 指南所涵蓋的相同規模評估問題。

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

不應該。由於它會執行代理程式撰寫的程式碼，並持有 Docker socket，請將它放在獨立、僅供單一用途使用，且您願意重新建置的 VPS 上。若讓它與資料庫、網站或其他服務共用主機，代理程式的錯誤或其中的 bug 可能會接觸到原本不應接觸的資源。