ghcr.io/all-hands-ai/openhands:e5f4920

面向编码代理与自动化的自托管开发者控制中心

在本地、远程和云后端运行 OpenHands、Claude Code、Codex、Gemini 或任何 ACP 兼容代理。

快速入门 | 文档 | 自托管 | ACP 代理 | 自动化 | Slack

OpenHands Agent Canvas 将您的编码代理转变为自托管、始终在线的工程团队。它是一个开发者控制中心，用于发起对话和自动化日常任务——例如生成发布到 Slack 的报告，或自动将 GitHub 问题分解为任务。

默认情况下，它在您的本地机器上运行，但可以连接到多个“代理后端”，例如在 Docker 容器、虚拟机或公司基础设施中运行代理。您还可以选择在 OpenHands Cloud 或 OpenHands Enterprise 基础设施上运行代理。

Agent Canvas 开箱即运行开源的 OpenHands 代理，也可使用任何第三方代理，如 Claude Code 和 Codex。

如有问题或反馈，请提交 GitHub issue 或加入 Slack 中的 #proj-agent-canvas 频道。

[!NOTE]

OpenHands Agent 和 Agent Server 的源代码位于 https://github.com/OpenHands/software-agent-sdk%E3%80%82

Agent Canvas 的源代码位于 https://github.com/OpenHands/agent-canvas%E3%80%82

快速入门

您可以在任何机器上安装 OpenHands 以运行代理：笔记本电脑、Mac Mini 等专用计算机，或云服务器。

在云服务器上运行 OpenHands 是最强大的方式。这使您的代理即使在笔记本电脑关闭时也能继续运行，并更容易通过 Slack、GitHub 和 Datadog 等第三方服务触发代理。详情请参见 SELF_HOSTING.md，尤其是安全强化相关内容。

值得注意的是，您可以在多个不同环境中运行后端，并从同一个 Agent Canvas 前端切换。例如，您可以与团队共享一个 Agent Server 用于代码审查和依赖更新代理，同时在个人笔记本电脑上运行个人代理。

选项 1：无沙箱模式

[!WARNING] 此方式直接在您安装的机器上运行 agent-server——代理将拥有对您文件系统的完全访问权限！

前提条件：Node.js 22.12.x 或更高版本、uv

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

默认情况下，agent-canvas 命令启动完整的本地堆栈。您也可以拆分运行各个组件：

agent-canvas --frontend-only # 仅启动静态前端 + 入口服务
agent-canvas --backend-only # 仅启动代理服务器 + 自动化后端 + 入口服务

选项 2：Docker 沙箱模式

前提条件：

• Docker：macOS/Windows 上的 Docker Desktop，或 Linux 上的 Docker Engine/Docker Desktop。
• 用于 PROJECTS_PATH 的主机目录，包含您希望代理访问的项目文件夹。启动容器前请创建此目录。

macOS / Linux：

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

docker run -it --rm \
-p 8000:8000 \
-v "$HOME/.openhands:/home/openhands/.openhands" \
-v "${PROJECTS_PATH}:/projects" \
ghcr.io/openhands/agent-canvas:1.0.0-rc.11

Windows（PowerShell / Windows 终端）： 请参见 https://github.com/OpenHands/agent-canvas/blob/main/README.windows.md 获取等效命令。

代理将能够访问 PROJECTS_PATH 下的所有项目。

选项 3：从源代码运行

[!WARNING] 此方式直接在您安装的机器上运行 agent-server——代理将拥有对您文件系统的完全访问权限！

前提条件：Node.js 22.12.x 或更高版本、npm、uv（用于通过 uvx 运行代理服务器）

git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install
npm run dev

---

通过 http://localhost:8000 访问 UI。您可以直接从 UI 添加其他后端。

架构

Agent Canvas 由 https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server/openhands/agent_server 提供支持，这是一个用于在单台机器上运行多个代理的 REST API。每个 Agent Server 运行在单个主机/端口上；Agent Canvas 可以连接到多个 Agent Server 并轻松切换。

您可以在任何地方运行 Agent Server：

• 直接在笔记本电脑上（请谨慎操作！）
• 在 Mac Mini 等专用机器上
• 在云虚拟机上
• 在 OpenHands Cloud（我们的商业产品）中

Agent Server 通常与 https://github.com/OpenHands/automation 配合使用，后者允许您设置按计划运行或响应事件的代理。

更多文档

• 文档索引
• 架构概述
• 开发指南
• 自托管指南