如何 3 分钟本地部署 OpenHands Agent Canvas：AI 编程代理的可视化控制中心-编程实验室

如何 3 分钟本地部署 OpenHands Agent Canvas：AI 编程代理的可视化控制中心

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

OpenHands（Agent Canvas）是一个可自托管的 AI 编程代理控制中心：你在浏览器里用自然语言指挥 OpenHands、Claude Code、Codex 等编码代理，让它读写文件、跑命令、开 PR，并把重复性工作排成定时或事件触发的自动化。适合想在自己电脑、Docker 或服务器上跑编码代理、又不想手写脚本串联 LLM 的开发者。

先搞清楚它是什么，再决定装在哪

Agent Canvas 本身不直接执行代码，它是一个前端控制台 + 本地编排器，真正干活的是后端的 Agent Server。这个分离设计带来一个关键好处：同一套界面可以切换多个后端——笔记本上跑个人代理，团队共享一台服务器上的代理做代码审查，互不干扰。

它解决的核心问题有三类：

对话式干活：新建会话，描述任务，代理自动执行命令、改文件、看结果
自动化：按时间表或 webhook 事件触发任务，比如 PR 打开时自动审查、每晚做安全扫描
扩展能力：给代理装技能（Skills）、MCP 服务器和插件，按需增强

Agent Canvas 的自动化仪表盘：每个任务的触发源、最近运行状态和成功率一目了然

选一条安装路线：npm、Docker 还是源码

当前发布版本为 1.15.0。三条路线的差异如下，按需取一条即可：

路线	隔离性	前置要求	适合谁
npm 全局安装	无沙箱，代理直接访问本机文件系统	Node.js ≥ 22.12、`uv`	最快上手，信任本机环境
Docker 沙箱	有，代理只看到挂载的目录	Docker Desktop 或 Docker Engine	想要隔离、生产更稳妥
从源码构建	无沙箱	Node.js ≥ 22.12、`npm`、`uv`	要改前端或跟进开发版

两条提醒：npm 和源码路线下代理对主机有完全访问权限，官方 README 里明确打了警告，建议先在小项目目录上试；Docker 路线则要求你先建好项目目录PROJECTS_PATH，代理只能看到挂载进去的文件夹。

3 步跑通本地部署

第 1 步：安装并启动。最省事的是 npm 路线，两条命令：

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

agent-canvas默认拉起完整本地栈（Agent Server、自动化后端和前端）。如果你要前后端分离跑，可以用agent-canvas --frontend-only或--backend-only分别启动。

选 Docker 的话，一条docker run即可（镜像自带全部服务）：

export PROJECTS_PATH="$HOME/projects" mkdir -p "$PROJECTS_PATH" 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

第 2 步：打开界面。npm/源码路线访问http://localhost:8000，Docker 路线访问http://localhost:8000/canvas。

第 3 步：配置 LLM。左侧"Getting started"引导清单会提示你先添加 LLM API Key，这是跑通对话的前置条件。支持自带模型（BYO model），在设置里建一个 LLM Profile 填入密钥即可。

✅成功标志：界面左下角出现 "Local" 后端徽标且状态点为绿色，"Getting started" 中前几项打勾。看到这些，说明本地栈已经就绪。

第一次对话：让代理干一件小事

点击 "New Chat"，选一个会话，直接输入任务，比如"给这个项目补一个 README，列出安装步骤"。代理会自主决定执行哪些命令、编辑哪些文件，你在事件流里能看到每一步的输入输出和文件 diff。

跑通第一个任务后，建议顺手做两件事：

在Customize → Skills里浏览技能库（59 个开箱即用的技能，按分类筛选、逐个启用），技能只对新会话生效
在Customize → MCP Servers / Plugins里接入你日常工具

Customize 面板下的 Skills 页面：按分类筛选并启用/禁用技能，改动只影响新会话

从对话到自动化：给代理排上定时任务

这是 Agent Canvas 和普通聊天式编码工具的分水岭。进入Automate菜单，你可以：

Add Automation：写一段 Prompt 描述任务，再指定触发方式——按时间表（如每晚 03:30）、按事件（如pull_request_openedwebhook），或两者加过滤条件
Import automation / Templates：导入现成的自动化模板
Dashboard：看所有任务的运行次数、成功率、平均耗时，失败的任务会标红提醒

一个典型配置是"PR Review on Open"：仓库有新 PR 时自动触发代码审查，把结论以行内评论发回，LLM Profile 指定用哪个模型执行。

自动化详情页：Prompt、触发事件、过滤条件和 LLM Profile 都在一个页面里管理

想暴露给团队或公网使用时，参考自托管指南 docs/SELF_HOSTING.md：核心是用LOCAL_BACKEND_API_KEY开启 public 模式，所有 API 调用必须携带密钥头，UI 首次访问时也要粘贴密钥才能操作。

常见部署问题排查

端口 8000 被占用：ingress 代理默认监听 127.0.0.1:8000，先用lsof -i :8000排查占用
Docker 容器里看不到项目：确认PROJECTS_PATH目录在docker run之前就已存在，且挂载路径拼写一致
会话一直连不上：前端连不上 Agent Server 时，检查终端日志里 18000 端口是否真正起来；uv未安装会导致 Agent Server 启动失败
Windows 用户：README 提供了 PowerShell 版本的命令，见 README.windows.md

架构细节可看 docs/architecture.md，多仓库分工（SDK、TypeScript 客户端、自动化服务各归各仓）在 docs/DEVELOPMENT.md 里有说明。