OpenHands：自托管 AI 软件工程 Agent 控制中心（Agent Canvas）｜部署与使用全指南

项目仓库： https://github.com/All-Hands-AI/OpenHands（主仓 `OpenHands/OpenHands`）

开源协议：MIT（© 2025 OpenHands contributors） · 交付形态：Agent Canvas 控制中心（Web UI + Agent Server + Automation Server） · 内置开源 OpenHands Agent，兼容 Claude Code、Codex、Gemini CLI、Pi、OpenCode 等 ACP 协议 Agent · 默认端口 8000 · 官方文档：docs.openhands.dev

非官方声明：OpenHands 是开源社区项目，与 Anthropic、OpenAI、Google 等模型厂商及 Claude Code、Codex、Gemini CLI 等第三方 Agent 不存在隶属、授权或合作关系；文章中出现的名称仅用于说明兼容目标。第三方 Agent 的订阅登录、API Key 与服务条款由对应厂商约束，OpenHands Cloud 与 OpenHands Enterprise 为官方商业产品，使用前须确认授权与合规边界。

1 项目简介

OpenHands 当前开源交付物为 Agent Canvas：一个自托管的开发者控制中心，用于发起对话、编排自动化任务，把编码 Agent 组织成“常驻工程团队”。它默认运行在本机，也可以连接多个 Agent 后端（本地进程、Docker 容器、远程 VM、公司基础设施或 OpenHands Cloud）；开箱即用地运行开源 OpenHands Agent，同时支持接入 Claude Code、Codex、Gemini CLI、Pi、OpenCode 等第三方 Agent 以及任意 ACP（Agent Client Protocol）兼容 Agent。

项目历史：OpenHands 前身名为 OpenDevin，后更名为 OpenHands；本文以当前仓库 README 与文档中的 Agent Canvas 形态为准，历史架构与旧版运行时的说明以官方归档文档为准。

1.1 核心信息一览

1.2 适用场景

• 在本机或专用 Mac Mini / NUC / 云 VM 上跑一个常驻 Agent 团队，关机不影响远程服务器上的任务继续运行。
• 同时管理多个后端：团队共享的代码评审 / 依赖更新 Agent 跑在远程服务器，个人 Agent 跑在笔记本，在同一前端里切换。
• 把日常工作做成自动化：定时生成报告推送到 Slack、监听 GitHub Issue 自动拆解任务、按 Webhook 触发代码评审。
• 团队统一使用 OpenHands 开源 Agent，或按需混用 Claude Code、Codex、Gemini CLI、OpenCode 等 ACP Agent。
• 开发者基于 software-agent-sdk 二次开发自定义 Agent、工具与工作流。

1.3 能力边界（官方口径）

• 官方 README 自述定位为 “The self-hosted developer control center for coding agents and automations”；本地、远程、云端后端使用同一套 Canvas Web UI，不存在本地 / 自托管 / 云端分别构建的独立版本。
• Agent Server 是运行在单机上的多 Agent REST API；每个 Agent Server 绑定一个主机 / 端口，Canvas 可连接多个 Agent Server 并在其间切换。Automation Server 负责调度与事件触发，把对话分派给 Agent Server / SDK。
• 无沙箱直跑模式下，Agent 直接运行在宿主机上，拥有完整文件系统、环境变量与网络访问权限；Docker 沙箱模式只隔离单会话执行，不隔离整个 Canvas 与自动化服务。
• OpenHands Cloud 与 OpenHands Enterprise 属于官方商业服务；第三方 Agent 的订阅登录与 API Key 由对应产品管理，Canvas 本身不提供模型与凭据。

2 功能特性

2.1 多后端切换

• 后端类型：本地（local）、远程（remote）、云端（cloud）；在 UI 的 Manage backends → Add a backend 中填写主机地址与 Session API Key 即可接入远程 Agent Server。
• 切换后端不丢失当前对话焦点；团队可共享一台远程 Agent Server 跑代码评审与依赖更新，个人 Agent 留在本机。

2.2 多 Agent 与 ACP 兼容

• 开箱运行开源 OpenHands Agent；可接入 Claude Code、Codex、Gemini CLI、Pi、OpenCode 等第三方 Agent，以及任意 ACP 兼容 Agent。
• 第三方 Agent 支持订阅登录（OAuth）或 API Key 两种认证方式；已登录订阅态优先于环境变量中的 Key，切换模型在会话内的模型选择器完成。

2.3 自动化任务（Automations）

• 按 cron 定时运行，或响应 Slack、GitHub、Linear、Notion 等 Webhook 事件触发；内置代码评审、PR 摘要、安全扫描、文档同步等预构建工作流模板。
• 自动化定义、调度、Webhook、运行历史与分派逻辑由独立的 OpenHands/automation 仓库维护。

2.4 自带模型配置

• 在 LLM 设置中维护模型配置文件（LLM profiles），接入任意兼容模型；Canvas 不内置模型清单，模型列表由当前 Agent 自行上报。

2.5 内置编辑器与工作区

• Canvas 内嵌 OpenVSCode 编辑器，通过路径前缀挂在代理端口下，保持单端口部署；每个会话拥有独立工作区，可查看文件、终端输出与 Agent 动作记录。

2.6 多仓库体系

3 官方界面预览

3.1 自动化任务面板

下图为官方 README 中的 Agent Canvas 界面：左侧为对话与自动化导航，右侧展示活跃 / 停用的自动化任务、运行方式（仓库、cron 计划、策略标签）与预构建工作流模板。

3.2 部署架构示意

下图为官方 README 架构图：用户笔记本上的 Agent Canvas 可连接本机虚拟机内的 Agent Server，也可连接 OpenHands Cloud 上的多 Agent Server、集成中心与自动化服务。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Node.js 24 或更高版本：npm 全局安装、源码开发与多会话沙箱模式均需要。
• uv：Agent Server 通过 uvx 运行时启动；安装命令 curl -LsSf https://astral.sh/uv/install.sh | sh，macOS 可用 brew install uv。
• Docker：仅在使用 Docker 沙箱模式时需要；macOS / Windows 用 Docker Desktop，Linux 用 Docker Engine 或 Docker Desktop。
• Git：克隆源码与管理项目仓库时需要。

5.2 服务器配置建议（官方自托管口径）

5.3 端口清单

对外暴露时，3001、18000、18001 必须只绑定回环地址，由防火墙保证不被外部直接访问。

5.4 关键环境变量

6 方式一：Docker 沙箱部署（推荐服务端使用）

6.1 单会话 Docker 沙箱（macOS / Linux）

前置准备：Docker Desktop / Docker Engine 已运行；先创建存放项目的宿主机目录。

export PROJECTS_PATH="$HOME/projects"
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

docker pull ghcr.io/openhands/agent-canvas:1.33.0

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
  -v "$HOME/.openhands:/home/openhands/.openhands" \
  -v "${PROJECTS_PATH}:/projects" \
  ghcr.io/openhands/agent-canvas:1.33.0

浏览器访问 http://localhost:8000/canvas；Agent 只能访问 PROJECTS_PATH 目录下的项目。

Windows PowerShell 等价命令见仓库 README.windows.md：

docker pull ghcr.io/openhands/agent-canvas:1.33.0
$env:PROJECTS_PATH = Join-Path $HOME "projects"
New-Item -ItemType Directory -Force -Path $env:PROJECTS_PATH, (Join-Path $env:USERPROFILE ".openhands") | Out-Null

docker run -it --rm `
  -p 127.0.0.1:8000:8000 `
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true `
  -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" `
  -v "$($env:PROJECTS_PATH):/projects" `
  ghcr.io/openhands/agent-canvas:1.33.0

6.2 多会话 Docker 沙箱（并发 Agent）

每个新会话运行在独立容器中，拥有独立 Agent Server 与工具；Canvas 与外层 Agent Server 跑在宿主机，负责把会话请求路由到各容器。

前置准备：Node.js 24+、uv、正在运行的 Docker；启动 Canvas 的用户能够执行 docker 命令。

npm install -g @openhands/agent-canvas
OH_CONVERSATION_RUNTIME=docker agent-canvas

访问 http://localhost:8000 新建会话；已有本地会话不会自动转换为容器模式。每个容器挂载自己的工作区与持久状态，工作区文件与会话历史在容器重建后保留；共享同一宿主机工作区的会话仍会互相看到文件改动，需要并行修改时请使用独立目录或 Git worktree。

Windows 限制：该运行时使用 POSIX 用户 / 组 ID，原生 Windows 宿主不受支持；请在 WSL 2 Linux 发行版中运行，并启用 Docker Desktop 的 WSL 集成。

6.3 局域网 / 公网暴露注意事项

• 快速启动命令把端口发布到 127.0.0.1，并显式开启会话 Key 注入；如果把端口发布到局域网或公网接口，不要设置 AGENT_CANVAS_ALLOW_LAN_SESSION_KEY，改为设置强 LOCAL_BACKEND_API_KEY，在 UI 中输入该 Key 登录。
• 容器内生成的 Key 可通过以下命令查看：

docker exec <container> sh -c 'cat "$STATE_DIR/api-key.txt"'

7 方式二：npm 全局安装、源码运行与 VM 长期自托管

7.1 无沙箱本地直跑（本机开发）

警告：该模式下 Agent Server 直接运行在本机，Agent 拥有完整文件系统访问权限，请勿在存放敏感凭据的生产环境直接使用。

前置准备：Node.js 24+、uv。

npm install -g @openhands/agent-canvas
agent-canvas

默认启动完整本地栈；也可以拆分运行：

agent-canvas --frontend-only   # 仅静态前端 + Ingress
agent-canvas --backend-only    # 仅 Agent Server + Automation 后端 + Ingress

访问 http://localhost:8000。本地（npx / npm run dev）启动器只绑定回环地址 127.0.0.1，自动注入的会话 Key 不会被网络上其他机器访问到；需要监听全部接口时加 --host 0.0.0.0（或设置 OH_BIND_HOST），此时不再自动注入会话 Key，UI 与 --public 一样要求输入 API Key。

7.2 从源码运行（开发者）

前置准备：Node.js 24+、npm 11.12.1（仓库锁定版本）、uv。

git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm ci
npm run dev

• 先执行 npm --version 核对版本；七天发布年龄过滤（npm install --min-release-age=7）要求 npm ≥ 11.10，旧版本不会强制生效；使用 npm ci 回放已提交的 lockfile。
• 上述 npm 版本要求仅针对贡献者依赖解析，不影响已发布 Canvas 包的安装。
• 其他开发脚本：npm run dev:minimal、npm run dev:static、npm run dev:mock、npm run build、npm run build:lib，具体参数以仓库 docs/DEVELOPMENT.md 为准。

7.3 VM 长期自托管（systemd + nginx）

7.3.1 系统加固（先于首次启动完成）

默认姿态：除 SSH（仅允许自己的 IP / VPN CIDR）外，公网入站全部拒绝；8000、18000、18001、3001 不得对外可达，网络防火墙是“绑定出错也不会暴露”的兜底保障。

7.3.2 安装依赖并以公共模式启动

apt-get update
apt-get install -y curl git
# Node.js 24.x：使用 nvm、asdf 或 NodeSource 任选其一
curl -LsSf https://astral.sh/uv/install.sh | sh

export LOCAL_BACKEND_API_KEY=$(openssl rand -base64 32)   # 生成一次，妥善保存
npx @openhands/agent-canvas --public

--public 开启公共模式：API Key 不内置进前端，首次打开 UI 需粘贴 LOCAL_BACKEND_API_KEY；/api/* 每次请求都要携带匹配的 X-Session-API-Key 头。

7.3.3 systemd 常驻（长期部署推荐）

创建 /etc/systemd/system/agent-canvas.service：

[Unit]
Description=Agent Canvas
After=network.target

[Service]
Environment=LOCAL_BACKEND_API_KEY=<your-key>
ExecStart=npx @openhands/agent-canvas --public
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now agent-canvas

快速方案可用 tmux：

export LOCAL_BACKEND_API_KEY=<your-saved-key>
tmux new-session -d -s canvas 'npx @openhands/agent-canvas --public'
# 重新接入：tmux attach -t canvas

7.3.4 nginx + Let's Encrypt 反代

域名 A 记录指向 VM 公网 IPv4；防火墙放行 80（HTTP-01 校验）与 443（HTTPS，建议仍限制来源 IP / VPN）。

apt-get install -y nginx certbot python3-certbot-nginx

站点配置 /etc/nginx/sites-available/canvas.example.com：

server {
    listen 80;
    listen [::]:80;
    server_name canvas.example.com;

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket / SSE 支持：Agent 实时事件必需
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

ln -sf /etc/nginx/sites-available/canvas.example.com \
       /etc/nginx/sites-enabled/canvas.example.com
nginx -t && systemctl reload nginx

certbot --nginx -d canvas.example.com \
    --non-interactive --agree-tos \
    --email you@example.com \
    --redirect

验证：curl -I https://canvas.example.com/ 返回 200（显示 API Key 登录页），curl -I http://canvas.example.com/ 返回 301 跳转 HTTPS。

7.3.5 接入远程后端

本机 Canvas 中打开 Manage backends → Add a backend：填写易记名称、远程地址（域名或 http://localhost:8000 SSH 隧道）与 LOCAL_BACKEND_API_KEY；保存后状态显示 Connected，即可在后端切换器中选择远程机器对话。

8 配置项说明

8.1 启动参数

8.2 后端连接

• 本地后端：默认随 agent-canvas 启动；远程后端在 UI 中按主机地址 + Session API Key 添加；云端后端需要 OpenHands Cloud 授权，接入方式以官方文档为准。
• 远程 Agent Server 通过 X-Session-API-Key 头鉴权；连接前确认网络可达、端口未被防火墙拦截。

8.3 ACP Agent 认证

• 支持订阅登录（OAuth 自动探测）与 API Key 两种方式；已登录订阅态优先于环境变量中的 Key：登录状态存在时，环境变量 Key 不会被使用。
• 凭据通过 Agent Server 导出到 ACP 子进程的环境变量传递；Secrets 面板中保存的密钥名必须与子进程读取的环境变量名一致，Key 才能真正送达。
• 切换 Agent 或模型在会话内模型选择器完成；本地后端由已保存凭据上报可用模型，Canvas 自身不维护模型清单。

8.4 模型与自动化集成

• LLM profiles 在设置页维护，可接入任意模型；第三方 Agent 的模型能力由其自身决定。
• 自动化任务可绑定仓库、cron 计划、策略标签与 MCP 工具；Slack、GitHub、Linear、Notion 等集成凭据在对应连接器 / Secrets 配置中填写，具体字段以官方预构建自动化文档为准。

9 常用运维命令

# ---- 安装与启动 ----
npm install -g @openhands/agent-canvas
agent-canvas
npx @openhands/agent-canvas --public
agent-canvas --frontend-only
agent-canvas --backend-only

# ---- systemd 常驻 ----
sudo systemctl status agent-canvas
sudo systemctl restart agent-canvas
sudo systemctl stop agent-canvas
journalctl -u agent-canvas -f

# ---- nginx 与证书 ----
nginx -t
sudo systemctl reload nginx
sudo certbot renew --dry-run

# ---- Docker 沙箱 ----
docker ps
docker exec <container> sh -c 'cat "$STATE_DIR/api-key.txt"'
docker logs <container>

# ---- 源码开发 ----
npm ci
npm run dev
npm run dev:minimal
npm run build

10 常见故障排查

10.1 502 Bad Gateway

反向代理返回 502 说明 127.0.0.1:8000 上的应用已停止；检查 npx / systemd 进程是否存活，查看 journalctl -u agent-canvas -f 或容器日志中的启动报错。

10.2 外部无法访问 UI

• 本地模式默认只绑定 127.0.0.1，局域网访问需要 --host 0.0.0.0 或 OH_BIND_HOST=0.0.0.0，同时改用 --public + 强 LOCAL_BACKEND_API_KEY。
• 检查云厂商安全组 / 网络防火墙：3001、18000、18001 不应对外放行；8000 只允许 nginx 本机回环访问。

10.3 会话 Key 与登录异常

• 回环模式自动注入会话 Key；切换到 --host 0.0.0.0 或 --public 后注入关闭，必须在 UI 输入 LOCAL_BACKEND_API_KEY。
• Docker 公网发布时不要设置 AGENT_CANVAS_ALLOW_LAN_SESSION_KEY；Key 泄露后重新生成 LOCAL_BACKEND_API_KEY 并重启服务。

10.4 多会话 Docker 模式启动失败

• 确认启动用户可执行 docker 命令；Windows 必须在 WSL 2 内运行并启用 Docker Desktop WSL 集成。
• 已有本地会话不会自动进入容器模式；需要容器隔离的会话请新建。

10.5 源码安装依赖失败

核对 npm --version 是否为 11.12.1 锁定版本附近；使用 npm ci 回放 lockfile；uv 未安装会导致 Agent Server uvx 运行时启动失败，先完成 uv 安装。

10.6 编辑器同源安全提示

官方已知问题 #16492：内嵌 OpenVSCode 与 Canvas 共享浏览器同源，路径前缀只做路由隔离而非安全隔离；该来源上运行的脚本（包括编辑器内容经扩展或被污染资产触发的脚本）可读取 Canvas localStorage 中保存的所有后端 Session Key。公网部署时不要在同一浏览器中混用不可信编辑器扩展，并跟踪该 Issue 的修复进展。

10.7 开发模式跨域

前端开发模式连接独立 Agent Server 时，用 VITE_BACKEND_BASE_URL=http://localhost:8010 npm run dev:frontend 指定后端地址；Agent Server 容器化部署时的 CORS 与端口映射以 docs/ACP_AGENTS.md 说明为准。

11 风险与合规说明

以下条款整理自官方 README、docs/SELF_HOSTING.md、MIT 许可证与官方文档口径；如与官方原文不一致，以仓库 LICENSE、README、docs/ 目录与 docs.openhands.dev 为准。

11.1 开源协议

Agent Canvas 与 SDK 开源代码采用 MIT 许可证，允许自由使用、修改与再分发；OpenHands Cloud、OpenHands Enterprise 为官方商业产品，接入需取得相应授权。第三方 Agent、模型与集成服务各自遵循其许可与服务条款。

11.2 Agent 权限与主机安全

• 无沙箱模式下 Agent 直接运行在宿主机，可读写文件系统、执行 Shell 命令并访问网络；任何能连接 Agent Server 的人都能获得同等能力。官方自托管指南要求把 VM 当作存放生产凭据的机器对待，先完成防火墙与 API Key 加固再暴露到公网。
• Docker 沙箱只隔离单会话执行环境，不隔离 Canvas 与自动化服务本身；自动化任务与 Webhook 上线前应限制来源、校验输入并配置访问控制。

11.3 凭据与代码隐私

• LOCAL_BACKEND_API_KEY、第三方 Agent 订阅态、模型 API Key 与会话历史均保存在本机或自托管后端；不要把 Key 写进代码仓库、截图或公开 Issue。
• 代码、文件路径、终端输出会按所选模型发送到对应服务；接入云端模型前确认项目代码允许外发，敏感仓库优先使用本地模型与离线后端。

11.4 商业使用与免责

MIT 许可证不限制商业场景使用，但混用第三方 Agent、模型与集成组件时须同时满足各自许可与条款。项目按现状（AS-IS）提供，不对 Agent 输出正确性、工具执行结果、服务可用性与数据隔离作担保；使用者自行承担代码质量、凭据泄露、服务中断与业务损失风险。如认为仓库内特定文件侵犯合法权益，请通过 GitHub Issues 提交说明，不要在公开 Issue 中提交 API Key、Token 或敏感代码。