OpenHands Agent Canvas 部署指南：三步自托管 AI 编码代理，快速上手

OpenHands Agent Canvas 部署指南三步自托管 AI 编码代理快速上手【免费下载链接】OpenHands OpenHands: AI-Driven Development项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands你手边已经装了几个 AI 编码代理可每次都要手动开对话、盯着它跑想定时出个报告还得保证电脑不关机。OpenHands Agent Canvas 解决的就是这个问题把代理搬到你自己的机器或服务器上自托管在同一个界面里发起对话、切换后端、按计划触发任务。下面带你从装到跑通第一遍。OpenHands Agent Canvas 是什么Agent Canvas 是一个自托管的开发者控制台control center用来管理和运行编码代理。它开箱即用地运行开源的 OpenHands agent也能接入 Claude Code、Codex、Gemini 等任何符合 Agent-Client ProtocolACP协议的第三方代理。界面是 React TypeScript 前端真正干活的是一台台 Agent ServerREST API 服务定时和事件触发的工作则由 Automation Server 负责。模块划分和边界可以在docs/architecture.md里看到完整说明。核心能力就三件事多后端接入本地、Docker、虚拟机、云端连上多个 Agent Server 后在同一个界面里随时切换自动化任务按时间表或 webhook 事件触发代理干活可对接 Slack、GitHub、Linear 等工具自带任意模型通过 LLM profile 配置你手头任何一家 LLM 提供商OpenHands 怎么装安装与启动时间线前置依赖只有两样Node.js 22.12 和uv跑 Agent Server 用的运行时缺一个后面都会卡住。① 装包约 1 分钟npm install -g openhands/agent-canvas # 全局安装含前端与本地栈编排脚本② 启动约 1-2 分钟agent-canvas # 一条命令拉起 agent server、自动化后端和前端代理监听 8000 端口③ 访问浏览器打开http://localhost:8000即可。如果你不想让代理直接拿到宿主机的文件系统权限就改用官方 Docker 镜像挂载好项目目录后运行ghcr.io/openhands/agent-canvas注意此时访问路径是http://localhost:8000/canvas。Windows 用户对照README.windows.md里的等价命令操作。控制台跑通第一个任务打开页面后左下角的 Getting started 清单直接告诉你接下来做什么跟着走完就算上手了Add LLM API key在 Customize 里加一个 LLM profile填上模型名和 API key。没有 key代理有嘴没脑子Start your first chat点 New Chat输入写一个 bash 脚本打印 Hello World 并运行它看系统做什么代理会生成脚本、在终端里执行、把输出流式贴回对话里在哪确认成功对话面板的终端输出里出现Hello World左侧本地后端旁的绿点表示连接正常这条链路就算全通了排错方向只有一条界面能打开但代理不响应十有八九是 LLM API key 没配或者 Agent Server 没起来——回启动终端看 uvx 那一行有没有报错。常见坑位与一句话解法现象原因一句话解法agent-canvas: command not foundnpm 全局 bin 不在 PATH 里重装一次并用npm config get prefix确认 bin 目录已加入 PATH启动卡在 agent server 一步没装uvuvx 找不到先按uv官方说明装好再启动别跳过浏览器访问 404跑的是 Docker 镜像却访问了根路径换http://localhost:8000/canvas代理找不到你的项目Docker 模式没挂项目目录把项目目录挂到容器的/projects下重启端口被占用报错8000 端口已有服务端口和版本统一由config/defaults.json定义改这里或停掉占用方进阶调优参数值不值得动参数默认值什么时候才需要调端口前端 8000 / Agent Server 18000 / Automation 18001要跑多套实例并存或对外挂域名时LLM profile无默认自建想按项目切换不同模型、不同提供商时--publicLOCAL_BACKEND_API_KEY关闭部署到服务器、允许网络访问时必须开启沙箱无代理可读写宿主机文件系统机器多人共用时一律换 Docker 镜像跑按使用场景给两条建议个人开发本地 npm 方式跑最省事担心代理改错文件就用 Docker 沙箱模式把PROJECTS_PATH指向你真正想让它碰的目录团队生产放一台常开 VM 上生成LOCAL_BACKEND_API_KEY并加--public启动防火墙只开 443详细加固流程在docs/SELF_HOSTING.md里写得很细以上就是全部代理跑在你自己的机器上对话、终端、文件和自动化收进一个界面不再依赖第三方云。下一步建议很具体去 Automate 的 Templates 页挑一个现成模板比如每天汇总仓库新提交把它变成真正跑起来的第一个定时任务——从那刻起 Agent Canvas 才算从玩具变成了工位 【免费下载链接】OpenHands OpenHands: AI-Driven Development项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考