当前位置：首页 > news >正文

三步自建AI编码代理控制台：OpenHands Agent Canvas 实操指南

news 2026/8/29 8:22:21

三步自建AI编码代理控制台：OpenHands Agent Canvas 实操指南

【免费下载链接】OpenHands🙌 OpenHands: AI-Driven Development项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands

你已经有一个会写代码的 AI 编程助手，但每次开工都要手动开终端、贴上下文、盯着结果，它没法过夜运行，不能被事件触发，更难跟同事共享。OpenHands Agent Canvas 是一个自托管的编码代理控制中心：同一个界面里开对话、切换代理、部署定时和 webhook 触发的自动化。

🎯 先说结论：它能替你干什么

一条命令起完整本地栈：前端、Agent Server、自动化后端全部拉起，浏览器打开即用。
代理不绑定：自带 OpenHands 开箱可跑，也能换成 Claude Code、Codex、Gemini CLI 等任意 ACP 兼容代理。
做之前：每个代理各开一个终端手动跑，只能人肉盯结果；做之后：对话、定时任务、事件触发集中在同一面板，合上笔记本它继续跑。

🚀 从零跑起来

环境要求检查清单

Node.js ≥ 22.12 和uv（仅 npm 安装、源码方式需要）
Docker Desktop 或 Docker Engine（Docker 沙箱方式需要）
一个已建好、可供代理访问的项目目录
本机 8000 端口未被占用

方式一：npm 全局安装

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

第一条命令装agent-canvas命令行工具，第二条直接启动完整本地栈。注意这种方式让 Agent Server 直接跑在主机上，代理对文件系统有完整权限，只适合可信机器。

方式二：Docker 沙箱（日常使用推荐）

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

这一步只把PROJECTS_PATH挂进容器，代理只能看到里面的项目；.openhands目录放配置和凭据。

方式三：从源码部署

git clone https://gitcode.com/GitHub_Trending/ope/OpenHands cd OpenHands npm install npm run dev

前三行拿代码、装依赖，npm run dev一并拉起 Agent Server、前端开发服务器和 ingress 代理。

启动后浏览器打开http://localhost:8000，Docker 模式下是http://localhost:8000/canvas。界面里可以直接添加更多后端，接入远程或云端的 Agent Server；服务器部署与安全加固细节见 docs/ 里的 SELF_HOSTING.md。

🧪 跟它做一个真实任务：给新 PR 自动做代码审查

你下指令。打开 Templates 页点进 "GitHub Code Review Agent"，它内置了验证过的审查提示词、实现草案和连接 GitHub 需要的 MCP；也可以直接开一段对话说："盯着 frontend-app 仓库，新 PR 出现时读一下 diff，把审查意见留在评论里，改动涉及数据库 schema 的单独标出来。"

它执行什么。GitHub webhook 到达后，自动化后端拉起一段新对话，代理拉取完整 PR 和仓库上下文，逐块检查改动，把结论写回 PR 评论区。

你得到什么。PR 上留下一条结构化审查评论；自动化仪表盘里能看到这个任务的运行次数、近期成功率和平均耗时，失败会被标记为需要关注。

🧩 让它更好用的三个习惯

把沙箱模式当默认。本地模式下代理对主机文件系统有完整权限，笔记本或共用机器上就走 Docker 方式，只挂载必要的项目目录，代理就碰不到机器上的其他东西。

先选模板再自己写自动化。模板库里的每个模板打包了提示词、实现草案和所需 MCP，选中后拉起一段预填好的对话，你只需补细节。适合 PR 审查、仓库监控、Slack 摘要这类常见任务。

用技能约束代理行为。Customize 页可以按触发器或分类搜索、安装技能，禁用的技能不会进入代理上下文。适合统一团队规范，比如审查评论的写法、安全扫描的检查项。

⚠️ 新手最容易踩的坑

现象：启动后界面里没有可用后端。原因：Node 版本低于 22.12 或缺uv，Agent Server 没起来。解法：node -v检查版本，装好 uv，或直接改走 Docker 方式。
现象：本地模式下代理动了项目外的文件。原因：无沙箱时 Agent Server 直接跑在主机上，文件系统全量可见。解法：改用 Docker 沙箱重建，只挂PROJECTS_PATH，把可访问范围锁死。
现象：配了 API key，ACP 代理仍提示认证失败。原因：提供商 CLI 的订阅登录优先于 API key，机器上已登录时 key 字段被忽略。解法：先用codex login status这类命令确认 CLI 登录状态，确定要用 key 就先清掉已有登录。
现象：端口 8000 被占用。原因：npm 安装实例和 Docker 实例默认都占 8000。解法：改-p端口映射，或停掉其中一个实例。