如何在VPS上安全自托管OpenHands

OpenHands 的作用，以及首先需要了解的一项风险

OpenHands 的前身是 OpenDevin，是一个自主软件工程代理。您用自然语言向它描述任务后，它会规划工作、编写代码、运行命令、读取输出，并不断迭代，直到任务完成。您可以通过 Docker 将它运行在自己的服务器上，并为其指定一个语言模型。在 VPS 上，它可以在您离开期间作为编码代理运行。

有一点会影响整个部署方案。OpenHands 不只是建议代码，还会运行代码。为此，其控制器容器会将主机的 Docker socket 挂载到 /var/run/docker.sock，以便为每项任务创建沙箱容器。任何能够访问 Docker socket 的进程都可以启动一个新容器，并将整个主机文件系统挂载到该容器中。这意味着访问该 socket 实际上等同于获得这台机器的 root 权限。因此，应将运行 OpenHands 的主机视为会执行不受信任代码的服务器，因为它确实会执行此类代码。下面的每项加固措施都基于这一事实。

需要的条件

您需要一台运行 Ubuntu 24.04 的 VPS，并安装近期版本的 Docker Engine，内存至少为 4 GB。此外，您还需要语言模型的 API key（OpenAI、Anthropic 或 Google），或者使用由同一台 VPS 上的 Ollama 提供的本地模型。OpenHands 支持数十种模型后端，您可以自行选择。如果您以前从未配置过容器，VPS 上的 Docker 基础知识涵盖了本指南所需的基础内容。

使用 Docker 安装

OpenHands 提供两个镜像：用于运行应用的应用镜像，以及用于运行每个任务沙箱、由应用拉取的 agent-server 镜像。请按以下方式运行，并将标签替换为项目文档中的当前标签：

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

有两个细节可以避免长时间排查问题。应用镜像和 agent-server 镜像使用不同的版本号，这是有意设计的，因此不要尝试让两者保持一致：请使用文档中与应用版本配套的 agent-server 标签。还要注意使用 -p 127.0.0.1:3000:3000，而不是 -p 3000:3000。这一处修改决定了 Web UI 是仅供您访问，还是整个互联网都可以访问；下一节将介绍后者。

不要将 Web UI 暴露到公网

OpenHands 在端口 3000 上提供界面。该界面驱动一个可以运行代码的代理，因此将其发布到互联网，相当于为任何发现它的人提供一条进入命令执行进程的远程路径。像上面的运行命令一样，将它绑定到回环地址，然后通过 SSH 隧道从笔记本电脑访问：

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

然后在您自己的计算机上打开 http://127.0.0.1:3000。流量通过现有的 SSH 会话传输，不会有新的服务监听公网。并非每个代理都需要端口：同一 VPS 上的 Claude Code 会话通过终端相互通信，因此您始终只需暴露 SSH。对于托管的每个代理仪表板，都应采用相同的回环地址加隧道方式；通过隧道访问 open-kritt 的扫描 UI也是如此，只是使用端口 5173。若需要更持久的配置，则改为将其置于 VPN 后面。无论采用哪种方式，都应在服务器前配置默认拒绝的防火墙，避免意外暴露服务。还要注意，仅覆盖 IPv4 的防火墙会使同一端口继续通过 IPv6 开放，这就是经常被忽略的IPv6 防火墙缺口。

隔离模型密钥和仓库凭据

OpenHands 需要用于模型的 API 密钥，通常还需要用于克隆和推送仓库的令牌。这两类凭据都可能产生费用，并且可以代表您执行操作，因此应像密码一样处理。将它们保存在只有正确账户可以读取的环境文件中。不要将它们写入运行命令，否则会出现在 shell 历史记录和进程列表中。也不要将它们保存在 git 仓库中的文件里。如果您将原始凭据保存在自托管密码管理器中，也应加固该服务器，因为密码库的薄弱点通常是管理员令牌和备份文件，而不是加密后的条目；Vaultwarden 加固流程会详细说明这一点。

在可丢弃的主机上运行

由于控制器必须持有 Docker socket，您无法将 OpenHands 与其宿主机完全隔离。可靠的缓解措施是通过部署位置实现隔离：将 OpenHands 运行在专用 VPS 上，不要运行在同时承载数据库或网站的服务器上。开始前先创建快照。不要信任已经运行代理生成代码一周的主机，而应从该快照重新构建。廉价、可丢弃且仅用于单一用途的 VPS 最适合作为它的运行环境。这里，部署位置是 OpenHands 真正提供的唯一控制手段。因此，如果您还希望控制代理在暂停并请求确认前可以执行多少操作，请参阅 Claude Code 的权限模式，了解在无人监控的服务器上如何使用第二个控制手段。

加固周边服务器

其余工作属于标准的服务器安全维护。由于这里运行的工作负载风险更高，这些措施比平时更重要。创建非特权管理用户，不要直接使用 root 操作，并参阅以非特权用户运行服务。将 SSH 修改为仅允许密钥认证。然后执行下面的检查清单，并将其保存在便于再次查看的位置。

如果您希望了解各组件的作用，而不只是执行这些操作，请参阅在 VPS 上构建自己的 AI agent；如果需要更少代码的平台，自行托管 Dify更适合作为入门方案。

FAQ

在服务器上运行 OpenHands 是否安全？

可以，但必须谨慎。与普通 Web 应用相比，风险更高，因为它会编写并运行代码，而且其控制器持有宿主机的 Docker socket；这实际上相当于拥有该机器上的 root 权限。应将其运行在专用且可随时销毁的 VPS 上，主机上不要存放其他重要数据。将其 Web UI 仅绑定到 loopback，并通过 SSH 隧道或 VPN 访问。隔离其密钥并加固主机。不要将它与重要服务部署在同一台服务器上。

OpenHands 为什么需要 Docker socket？

OpenHands 会在全新的沙箱容器中运行每个任务，并通过将 /var/run/docker.sock 挂载到其控制器中，请求宿主机 Docker daemon 创建这些容器。这样，控制器容器就能控制宿主机上的 Docker。这种权限很强，风险也很高，因此必须将该宿主机视为运行不受信任代码的主机。

OpenHands 能否使用本地模型，而不是付费 API？

可以。OpenHands 支持由 Ollama 或 vLLM 提供服务的本地模型，因此可以完全自行托管，不产生按 token 计费，也不会有数据离开服务器。你需要一台内存足够、能够运行高性能编码模型的机器。具体配置要求与 Ollama 指南中介绍的容量规划问题相同。

我应该在主服务器上运行 OpenHands 吗？

不应该。由于它会运行代理编写的代码并持有 Docker socket，应将其部署在独立的单用途 VPS 上，并确保你愿意随时重装该 VPS。将它与数据库、网站或其他服务部署在同一台服务器上，意味着代理的错误操作或自身缺陷可能触及原本不应访问的资源。