想把 OpenHands 放在 VPS 上，让 coding agent 在远端处理代码，打开浏览器就能查看会话？先看清版本：网上很多 docker run ... openhands:latest -p 3000:3000 教程针对的是 旧版 Local GUI。OpenHands 现在把新的浏览器工作台称为 Agent Canvas；本文按官方当前的 VM 自托管文档部署它，使用 SSH 隧道访问，不直接向公网开放后台。
本文适合一人使用、独立 Ubuntu VPS、模型通过云端 API 提供的场景。Agent Canvas 的后端能执行命令、读写 VPS 文件并使用保存在后端的密钥；在这条安装路线中，它直接运行在主机上，不是 Docker 沙箱。请给它一台不放生产密钥和生产数据的开发机。需要容器边界时，先看官方的 Docker 安装路线。
官方给单人 VM 的起点是 2 vCPU、4 GB 内存，示例系统为 Ubuntu 24.04 LTS。这个配置只覆盖 Agent Canvas 本身和轻量任务；构建大型仓库、跑测试或同时运行数据库，需要按项目峰值加内存与磁盘。本文使用云端模型，不要求 VPS 有 GPU。按 官方要求，还需 Node.js 24 或以上、npm、uv、Git 和 curl。
先从自己的电脑验证 SSH，再在 VPS 检查资源：
ssh [email protected]
free -h
df -h "$HOME"
uname -m
这里的 IP 是示例地址，请换成你的 VPS 公网 IP。云防火墙只允许你的 IP 或 VPN 网段访问 SSH；8000 端口保持关闭。如已在同一台 VPS 部署其他服务，先确认磁盘空间、端口和用户权限不会互相影响。更稳妥的做法是给 agent 单独准备开发 VPS。
下面的命令在 VPS 的普通 SSH 用户下执行；该用户需要有 sudo 权限用于安装系统依赖和全局 npm 包，平时运行 agent-canvas 不使用 sudo。官方 Ubuntu 示例使用 NodeSource 安装 Node.js 24：
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg git tmux openssl
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"
sudo npm install -g @openhands/agent-canvas
node --version
uv --version
agent-canvas --version
执行远程安装脚本前，可以先打开链接检查脚本来源；有现成的 Node.js 24 和 uv 时直接跳过相应安装步骤。node --version 至少应为 24。官方 排障页指出，agent-canvas: command not found 往往是 npm 全局安装目录不在 PATH；先用 npm list -g --depth 0、npm prefix -g 检查，不要反复重装。
远程部署要使用 --public 模式和强 LOCAL_BACKEND_API_KEY。这个参数的意思是浏览器必须输入密钥，不等于建议开放公网端口。下列命令在 VPS 生成一次密钥并写入只有当前用户可读的文件：
umask 077
printf 'export LOCAL_BACKEND_API_KEY=%s\n' "$(openssl rand -hex 32)" > "$HOME/.agent-canvas.env"
chmod 600 "$HOME/.agent-canvas.env"
把密钥保存在密码管理器里，别提交到 Git、贴到聊天记录或工单。需要查看时，在私密 SSH 终端运行 cat ~/.agent-canvas.env。接着启动 tmux：
tmux new -s canvas
source "$HOME/.agent-canvas.env"
agent-canvas --public
等终端显示服务已经启动，再按 Ctrl-b，然后按 d 退出 tmux 会话。SSH 断开后进程仍可继续；重连后用 tmux attach -t canvas 查看日志。tmux 不负责开机自启，VPS 重启后需要重新启动会话。用 ss -ltnp | grep ':8000' 检查监听地址，并确认云防火墙没有放行 8000。若意外监听所有网卡，更要依靠云防火墙限制入口。
在自己的电脑另开终端，保持下面的命令运行：
ssh -N -L 8000:127.0.0.1:8000 [email protected]
随后在本地浏览器打开 http://127.0.0.1:8000，输入刚才的 LOCAL_BACKEND_API_KEY。这是经 SSH 加密的本地访问路径；浏览器地址中的 127.0.0.1 指你的电脑。如果本地 8000 已被占用，将命令左侧改为 18000:127.0.0.1:8000，浏览器对应打开 http://127.0.0.1:18000。只有 SSH 隧道保持连接，网页才能访问远端服务。
为什么仍要设置密钥？它保护后端 API，避免仅凭端口访问就取得执行权限。为什么不直接把 8000 放到公网？官方明确指出，后端能访问主机文件、网络和机密；如果以后需要多人或公网访问，应按 官方安全清单再加 HTTPS、身份访问控制和网络限制，不能只靠一个裸露的端口。
Agent Canvas 工作台本身不包含云端模型额度。在 Settings > LLM 中选择 Basic：选一个你实际有权限使用的模型提供方与模型，填入对应 API Key，保存配置后新建会话，先让 agent 读取测试仓库的 README 并列出计划。模型名称、权限和计费以提供方控制台为准；建议给 API Key 设置预算上限和用量提醒。官方 模型配置指南也提供 OpenAI 兼容服务和 LiteLLM 代理的 Advanced 路线。
这里有两个容易误会的地方：
- 你在笔记本上登录过的 Codex、Claude Code 或 Gemini CLI，不会自动把登录状态带到 VPS 后端。要在 Agent Canvas 里使用这些 ACP agent，应按 官方 ACP 文档在后端所在机器配置认证。
- Agent 运行在 VPS，能访问的文件由后端账号和工作区权限决定。先在测试仓库里跑只读任务，确认路径、Git 分支和模型费用，再允许它修改代码。站内的 VS Code Remote SSH 连接 VPS 教程适合同时用编辑器检查远端改动。
升级前先在 tmux 中停止进程，记录当前版本，并备份实际使用的项目仓库与 OpenHands 状态目录。官方说明设置、密钥和会话等持久数据通常保存在 ~/.openhands；确认目录存在后再执行备份：
agent-canvas --version
ls -ld "$HOME/.openhands" "$HOME/.agent-canvas.env"
umask 077
mkdir -p "$HOME/backups"
tar -C "$HOME" -czf "$HOME/backups/agent-canvas-$(date +%F).tgz" .openhands .agent-canvas.env
备份包含访问密钥，需保存在受控位置；Git 仓库仍应各自提交和备份。确认备份可读后，在 tmux 中按 Ctrl+C 停止旧进程，再按 官方更新说明执行 sudo npm install -g @openhands/agent-canvas@latest，用原来的密钥文件重新启动并验证会话。不要因升级重生成 LOCAL_BACKEND_API_KEY。
| 现象 | 优先检查 | 处理方向 |
|---|---|---|
agent-canvas 找不到 | npm list -g --depth 0、npm prefix -g | 检查全局 npm 的 bin 是否在 PATH |
启动提示缺 uv / uvx | uv --version、echo "$PATH" | 重新加载 ~/.local/bin/env，再启动进程 |
| 本地网页打不开 | VPS 上 ss -ltnp、本地 SSH 隧道终端 | 确认服务运行且隧道未断；本地端口冲突就换左侧端口 |
| 网页能打开但后端断开 | 后端地址与 LOCAL_BACKEND_API_KEY | 核对密钥和正在运行的后端，不要将本地地址写成 VPS 公网 IP |
| 会话刚开始就报模型错误 | Settings > LLM 的提供方、模型 ID、API Key | 核对模型权限、账户余额和 VPS 到模型服务的出站网络 |
| VPS 变慢或磁盘满 | free -h、df -h、项目构建产物 | 减少并发任务，先确认大文件来源，再决定扩容或清理 |
如果你只是想在远端终端跑一个 coding agent，已有的 Codex CLI VPS 教程更轻量。Agent Canvas 更适合需要浏览器工作台和持续远端后端的场景；选它之前，先确定这台 VPS 的文件访问边界与密钥管理方式。