ghcr.io/opendevin/opendevin:2501-merge
Agent Canvas
面向编码智能体与自动化流程的自托管开发者控制中心。
可在本地、远程及云端后端运行 OpenHands、Claude Code、Codex、Gemini、Pi、OpenCode,或任何兼容 ACP 协议的智能体。
[快速入门] | [文档] | [自托管部署] | [ACP 智能体] | [自动化流程] | [Slack]
OpenHands Agent Canvas 可将你的编码智能体转化为自托管、永久在线的工程团队。这是一款开发者控制中心,支持发起对话、自动化日常任务,例如生成可发布至 Slack 的报告,或是自动将 GitHub 问题拆解为待办任务。
默认情况下它在本地机器上运行,同时可对接多个“智能体后端”,例如在 Docker 容器、虚拟机,或企业内部基础设施中运行智能体。你也可以选择在 OpenHands Cloud 或 OpenHands 企业级基础设施中运行智能体。
Agent Canvas 开箱即可运行开源的 OpenHands 智能体,同时支持接入 Claude Code、Codex、Gemini CLI、Pi、OpenCode 等第三方智能体。
| 特性 | 说明 |
|---|---|
| 自定义自托管部署 | 在本地、Docker、虚拟机,或任何可运行智能体服务后端的位置部署智能体 |
| 多后端无缝切换 | 在不中断工作流的前提下,切换本地、远程及云端智能体 |
| 创建自动化流程 | 构建集成 Slack、GitHub、Linear 等服务的自动化工作流,支持按计划触发或响应 webhook 事件 |
| 对接现有工具链 | 将自动化流程与 Slack、GitHub、Notion 等第三方服务连通,实现工作流自动化 |
| 接入自有模型 | 支持接入任意大语言模型 |
| 兼容任意智能体 | 支持 OpenHands、Claude Code、Codex、Gemini、Pi、OpenCode,或所有符合智能体-客户端协议(ACP)的智能体 |
如有疑问或反馈,请提交 GitHub issue,或加入 Slack 上的 #proj-agent-canvas 频道。
快速入门
你可以在任意设备上安装 OpenHands 来运行智能体,包括个人笔记本、Mac Mini 等专用设备,或是云端服务器。
在云端服务器上运行 OpenHands 是能力最强的部署方式。即便你的笔记本处于关机状态,智能体也能持续运行,同时更便于通过 Slack、GitHub、Datadog 等第三方服务触发智能体。相关细节请参考 SELF_HOSTING.md,尤其是安全加固相关的内容。
需要特别说明的是,你可以在多个不同环境中运行后端,并且通过同一个 Agent Canvas 前端在不同后端之间切换。例如,你可以和团队共享一个智能体服务器,用于运行代码审查和依赖更新类智能体,同时在自己的笔记本上运行个人专属智能体。
选项 1:无沙箱运行
[!WARNING] 该模式会将智能体服务直接运行在你安装程序的机器上,智能体将获得你文件系统的完全访问权限!
前置依赖:https://nodejs.org/ 24 或更高版本,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 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.37.0 # x-release-please-version
Windows(PowerShell / Windows Terminal):对应操作命令请参考 README.windows.md。
[!NOTE] 当智能体服务约 30 秒未响应
/alive健康检查时,容器入口点会以退出码 1 终止容器,确保崩溃或挂起问题可以被直观感知,不会出现持续返回 502 错误的无响应容器。 如需实现自动恢复,请替换--rm参数为--restart unless-stopped,或在 Docker Compose 中配置restart: unless-stopped。
智能体将有权访问 PROJECTS_PATH 下的所有项目。
选项 3:使用多个 Docker 沙箱运行
每个新会话都在独立的 Docker 容器中运行,拥有独立的智能体服务与工具集。该模式适合同时运行多个智能体的场景。Canvas 与外层智能体服务运行在宿主机上,负责将会话请求路由到各个容器中。
前置依赖:Node.js 24 或更高版本,uv,以及运行中的 Docker Desktop(macOS)或 Docker Engine/Desktop(Linux)。启动 Canvas 的用户需要具备执行 docker 命令的权限。
macOS / Linux 平台执行命令:
npm install -g @openhands/agent-canvas
OH_CONVERSATION_RUNTIME=docker agent-canvas
打开 http://localhost:8000 即可创建新会话。现有本地会话不会自动迁移。每个容器都会挂载对应会话的工作目录与持久化状态,因此工作区文件与会话历史在容器替换后依然可以保留。使用同一宿主机工作目录的会话会共享这些文件,请选择独立目录或工作树来避免编辑冲突。
该设置仅隔离会话执行过程,不会将整个 Canvas 或自动化服务放入沙箱。Windows 平台相关说明请参考 README.windows.md。
选项 4:从源码构建运行
[!WARNING] 该模式会将智能体服务直接运行在你安装程序的机器上,智能体将获得你文件系统的完全访问权限!
前置依赖:https://nodejs.org/ 24 或更高版本,npm 11.12.1(仓库锁定版本),uv(用于通过 uvx 运行智能体服务)。
解析依赖前请先执行 npm --version 检查 npm 版本。发布时长7天的过滤规则(npm install --min-release-age=7)要求 npm 版本 >= 11.10,旧版本不会强制执行该规则。请使用 npm ci 复现仓库中已提交的锁定文件。该 npm 版本要求仅适用于贡献者的依赖解析流程,不适用于已发布的 Canvas 包安装场景。
git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm ci
npm run dev
本地(npx / npm run dev)的监听器默认仅绑定回环地址(127.0.0.1),自动注入的会话密钥无法被网络中的其他设备访问。如需监听所有网卡接口,请传入 --host 0.0.0.0 参数(或设置环境变量 OH_BIND_HOST);此时系统将不再自动注入会话密钥,UI 会显示与 --public 模式一致的 API 密钥输入界面。
Docker 容器内的服务默认监听所有容器网卡接口以保证端口发布功能正常,但默认不会将会话密钥注入 HTML 页面。上方快速入门示例通过将宿主机端口发布到仅 127.0.0.1 的方式,显式启用了会话密钥注入。如果你将 Docker 端口发布到局域网或公网接口,请删除 AGENT_CANVAS_ALLOW_LAN_SESSION_KEY 环境变量,在 UI 中手动输入 API 密钥。请将 LOCAL_BACKEND_API_KEY 设置为高安全性密钥值,或通过命令 docker exec sh -c 'cat "$STATE_DIR/api-key.txt"' 获取自动生成的密钥值。面向公网的部署请遵循自托管部署指南的要求。
架构
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搭配使用,你可以通过自动化服务配置按计划触发或响应事件的智能体任务。
仓库边界说明
Agent Canvas 属于多仓库 OpenHands 系统的一部分,代码变更需提交至对应功能归属的仓库:
| 仓库地址 | 职责范围 |
|---|---|
| https://github.com/OpenHands/OpenHands | Agent Canvas 前端、面向用户的控制中心、后端选择模块与本地技术栈编排逻辑 |
| https://github.com/OpenHands/software-agent-sdk | Python SDK、Agent Server、智能体、工具、会话、工作区、事件,以及官方服务 API 定义 |
| https://github.com/OpenHands/typescript-client | 兼容浏览器的 Agent Server API TypeScript 客户端 |
| https://github.com/OpenHands/automation | 自动化流程定义、调度器、webhook 处理、运行历史记录与任务分发逻辑 |
Agent Server API 由 SDK 实现,通过 TypeScript 客户端供 Agent Canvas 调用。自动化服务负责决定任务的执行时机,将会话调度到 Agent Server/SDK,由后者决定任务的具体执行逻辑。贡献者专属的代码边界说明与自定义代码审查指南请参考 AGENTS.md。
更多文档资源
- 文档索引
- 架构概览
- 开发指南,包括在宿主应用中嵌入 Canvas 组件(在导入组件的同时仅需加载一次
@openhands/agent-canvas/styles.css) - 自托管部署指南
用户好评
来自真实用户的反馈,见证轩辕镜像的优质服务