OpenHands：自托管编码代理控制中心

项目简介

OpenHands Agent Canvas 是一个自托管的开发者控制中心，把编码代理变成一支常驻的工程团队。它用于发起与代理的对话，以及自动化日常任务，例如生成报告并发布到 Slack、把 GitHub issue 自动拆解成任务。

它默认运行在你自己的机器上，也可以连接多个「代理后端」：在 Docker 容器、虚拟机或公司内部基础设施中运行代理；也可以选择运行在 OpenHands Cloud 或 OpenHands Enterprise 上。Agent Canvas 开箱即用地运行开源 OpenHands 代理，同时也支持 Claude Code、Codex、Gemini CLI、Pi、OpenCode 等第三方代理。

主要功能

• 自托管：在本地、Docker、VM 或任何可运行 agent server 后端的地方运行代理。
• 切换后端：在本地、远程和云端代理之间自由切换。
• 创建自动化：搭建与 Slack、GitHub、Linear 等集成的自动化与工作流，可按计划运行或由 webhook 事件触发。
• 连接常用工具：把自动化与 Slack、GitHub、Notion 等第三方服务打通。
• 自带模型：可配合任意 LLM 使用。
• 兼容多种代理：支持 OpenHands、Claude Code、Codex、Gemini、Pi、OpenCode 以及任何实现 Agent-Client Protocol（ACP）的代理。

安装与使用

方式一：不使用沙箱

前置条件：Node.js 24 或更高版本、uv。

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

agent-canvas 默认启动完整的本地栈，也可以拆分运行：

agent-canvas --frontend-only  # 仅静态前端 + ingress
agent-canvas --backend-only   # 仅 agent server + 自动化后端 + ingress

方式二：使用 Docker 沙箱

前置条件：Docker（macOS/Windows 用 Docker Desktop，Linux 用 Docker Engine/Desktop）；需要一个宿主机目录作为 PROJECTS_PATH，存放希望代理访问的项目文件夹，并在启动容器前创建好。

macOS / Linux：

export PROJECTS_PATH="$HOME/projects"  # 包含项目文件夹的目录
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

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.34.0

Windows 的等效命令见 README.windows.md。代理将可以访问 PROJECTS_PATH 下的任何项目。

方式三：多个 Docker 沙箱

每个新对话在自己的 Docker 容器中运行，拥有独立的 Agent Server 和工具，适合并发运行多个代理。

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

打开 http://localhost:8000 并新建对话。已有本地对话不会被转换；每个容器会挂载该对话的工作区和持久化状态，因此工作区文件和对话历史在容器替换后仍然保留。使用同一宿主机工作区的对话会共享这些文件，建议选择不同目录或 worktree 以免编辑冲突。该设置只隔离对话执行，并不会把整个 Canvas 或自动化服务放进沙箱。

方式四：从源码运行

前置条件：Node.js 24 或更高版本、npm 11.12.1（仓库锁定版本）、uv。

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

通过 npm 或源码启动时访问 http://localhost:8000；Docker 镜像访问 http://localhost:8000/canvas。可以在 UI 中直接添加更多后端。

注意事项

• 不使用沙箱的方式会直接在你安装的机器上运行 agent-server，代理拥有对文件系统的完全访问权限。
• 本地（npx / npm run dev）监听只绑定回环地址 127.0.0.1，自动注入的 session key 不会被网络中的其他机器访问。若需监听所有网卡，可传入 --host 0.0.0.0（或设置 OH_BIND_HOST），此时不会注入 session key，UI 会使用与 --public 相同的 API key 输入界面。
• Docker 会监听容器的所有网卡以便端口发布，但默认不向 HTML 注入 session key。上面的 quickstart 在只把宿主端口发布到 127.0.0.1 的前提下显式开启了注入；若把 Docker 发布到局域网或公网接口，请去掉 AGENT_CANVAS_ALLOW_LAN_SESSION_KEY 并在 UI 中输入 API key，同时把 LOCAL_BACKEND_API_KEY 设为强值，或用 docker exec <container> sh -c 'cat "$STATE_DIR/api-key.txt"' 获取生成的值。面向互联网的部署请参考 SELF_HOSTING.md。

---

本作品整理自 GitHub 开源项目 OpenHands/OpenHands，原作者 @OpenHands，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。