OpenHands 部署教程：如何快速搭起自托管 AI 编码智能体控制台
【免费下载链接】OpenHands🙌 OpenHands: AI-Driven Development项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands
OpenHands Agent Canvas 是一个自托管的 AI 编码智能体控制台，让 OpenHands、Claude Code 等编码智能体跑在你自己的机器上，用浏览器下发任务并实时查看代码改动。这次 OpenHands 部署只需两条命令，耗时约 5 分钟。
这是部署完成后你看到的主界面：左侧 Conversations 列出全部历史会话，Automate 入口负责自动化任务，底栏的 Local 表示当前连接的是本机智能体服务器。
跑起来之后你得到什么
- 一个浏览器控制台：新建会话、对话流、文件面板和终端全在界面里，智能体每执行一条命令、改一个文件都能实时看到
- 多智能体接入：默认内置 OpenHands 智能体，也可接入 Claude Code、Codex 等遵循 ACP 协议的智能体，在同一界面切换
- 自动化任务：按时间调度或事件触发运行智能体，例如 PR 一打开就自动做代码审查
- 后端可换：默认跑在本机，之后可把 Docker 容器或虚拟机上的智能体服务器加进来，前端不用重装
OpenHands 部署的环境要求
| 项目 | 最低 | 推荐 |
|---|---|---|
| Node.js | 22.12（npm 与源码方式必需） | 22.x 最新版 |
| uv | npm 与源码方式必需（智能体服务器经 uvx 启动） | 最新稳定版 |
| Docker | 仅沙箱方式必需 | Docker Desktop 或 Docker Engine |
| 内存 | 2 GB | 4 GB |
| 网络 | 能访问 npm registry 与 PyPI | 额外能访问 ghcr.io（拉取沙箱镜像） |
开始之前先验证前两项，避免装到一半才发现缺东西：
node -v # 期望输出 v22.12.x 或更高 uv --version # 期望输出版本号，没有就先安装 uvnode 低于 22.12 时 npm 会因 engines 约束直接安装失败；uv 缺失则要到启动阶段才报"找不到 uvx"，所以提前确认。
三条路径把 OpenHands 跑起来
路径一：本机直跑，最快。适合先试水、且能接受智能体直接操作你系统文件的情况。
npm install -g @openhands/agent-canvas agent-canvas为什么是两条命令：npm 装的是发布版 CLI，agent-canvas会一次性拉起前端、智能体服务器和自动化后端。预期结果：终端滚动出启动日志，浏览器打开http://localhost:8000即见主界面。注意：这条路径的智能体以你的系统权限执行命令，别让它指向重要目录。
路径二：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.14.0为什么先 export 再 docker run：容器只挂载 PROJECTS_PATH 指向的目录，变量必须在启动前设好，且该目录需先存在。预期结果：首次拉镜像要几分钟，起来后访问http://localhost:8000/canvas，比路径一多了 /canvas 路径。
路径三：源码启动，可改。想改前端代码或跟最新特性时用。
git clone https://gitcode.com/GitHub_Trending/ope/OpenHands cd OpenHands npm install npm run dev预期结果：同样落在 http://localhost:8000，保存前端文件后界面热更新。
验证效果：给它一个最小任务
点左侧 New Chat 新建会话，选一个本地项目（比如刚克隆的 OpenHands 仓库），发一句："列出当前目录的文件，并解释 package.json 里每个 script 的用途。"这个任务只读不写，一次验证命令执行、文件读取、回复生成三段链路。
完成后看两处：对话区里智能体返回的脚本解释，确认它真的读了文件；左侧会话列表里的这条记录，确认会话持久化生效。
想继续体验自动化，点左侧 Automate → Templates。
Templates 页预置了一批可一键启动的自动化，重点看每张卡片底部的 "MCPs to connect before launch" 标签——启动前要先连上对应的 GitHub 或 Slack 凭据。
点进任一自动化（如 PR Review on Open）可看到完整配置：顶部 Prompt 是任务指令，中间 Trigger 为 Event、Event Type 为 pull_request_opened，说明它由 PR 事件触发，右上 Run now 可手动跑一次验证。
界面背后其实是三个进程
你访问的 8000 端口只是入口代理：页面请求转给静态前端，/api 与 /sockets 转给 18000 的智能体服务器和 18001 的自动化后端。和你有关的是底栏的 Local——它标记当前连接的是哪台智能体服务器，以后接入远程后端，只是给同一前端多加一个可切换选项。
卡住的时候：三个最常见的坑
打开 8000 端口一直加载不出来现象：命令执行完了，浏览器却在转圈。 原因：首次启动时 uvx 要现装智能体服务器包，网络慢时界面要等几分钟才就绪。 解决：回终端看日志是否在下载依赖，别急着杀进程，等下载完成再刷新。
启动报端口占用现象：日志出现 EADDRINUSE。 原因：8000 端口已被别的程序占用。 解决：入口端口由 PORT 环境变量控制，换个端口重启即可：
PORT=8080 agent-canvas重启后访问 http://localhost:8080 即可。
Docker 方式下找不到项目现象：智能体说访问不到你的代码目录。 原因：export PROJECTS_PATH 写在了 docker run 之后，实际挂载的是空路径。 解决：先 export 并 mkdir，再运行 docker run；官方要求该目录在启动容器前就已存在。
下一步该做什么
到这里，一个跑在本机的 OpenHands 智能体控制台已经就位，后续玩法都从这个界面长出来。接下来选一个你熟悉的小仓库，新建会话让它**"解释这个项目并指出一处可优化的代码"**，然后在 Files 面板核对它实际读过的文件。需要长期自托管或暴露到内网时，防火墙与 API key 的做法见 docs/SELF_HOSTING.md。
【免费下载链接】OpenHands🙌 OpenHands: AI-Driven Development项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
