企业官网建设流程全解析

OpenHands Agent Canvas：从零跑通 AI 编码助手的完整实操指南

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

OpenHands Agent Canvas 是一个自托管的 AI 编码智能体控制中心，把 OpenHands、Claude Code、Codex 等编码智能体接入同一个 Web 界面，让你在一处管理对话、后端和定时自动化。本文带你从环境检查走到第一次让智能体替你跑代码。

为什么需要编码智能体的统一入口

现在的编码智能体各带各的 CLI：每开一个任务就要开新终端、粘贴同样的提示词，关掉窗口上下文全丢。更麻烦的是，智能体只能跑在你手边这台机器上，合上笔记本任务就停了。

OpenHands 给出的解法叫 Agent Canvas，即它的自托管前端：一台机器上跑 Agent Server，多个智能体、多个后端、定时自动化全部通过浏览器操作。适合想把自己的智能体任务常驻到服务器上、或用统一入口管理多个编码智能体的人。

架构一句话：浏览器通过 REST API 说话，Agent Server 在运行时里执行对话与工具，细节可看docs/architecture.md。

图 1：首次启动后，左侧面板显示 Getting started 待办清单，Customize 下的 Skills 页用于给智能体添加能力

最短路径上手：三种启动方式怎么选

环境要求很简单：

• Node.js 22.12 以上（Docker 方式只需要 Docker Desktop 或 Docker Engine）
• 4GB 以上空闲内存、5GB 以上磁盘（首次启动要拉取一批依赖）
• 本地运行方式另需uv来启动 agent server

从源码运行

# 获取代码 git clone https://gitcode.com/GitHub_Trending/ope/OpenHands cd OpenHands # 安装前端依赖 npm install # 启动完整本地栈：agent server + 自动化后端 + 前端 npm run dev

选它是因为npm run dev一次拉起整套栈，前端热更新，试功能最方便。

成功的样子：终端里 Vite 就绪、agent server 监听在127.0.0.1:18000，浏览器打开http://localhost:8000出现主界面。左下角的 Getting started 清单会引导你依次做三件事：添加 LLM API key、开始第一次对话、安排一个定时任务。

⚠️ 本地方式下智能体对整台机器的文件系统有读写权，也能执行 shell 命令。敏感机器请改用 Docker 方式。

用 Docker 起沙箱

export PROJECTS_PATH="$HOME/projects" # 存放项目代码的目录 mkdir -p "$PROJECTS_PATH" "$HOME/.openhands" # 智能体只能看到挂载目录，状态持久化到 ~/.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

访问http://localhost:8000/canvas。智能体只能看到PROJECTS_PATH下的目录，日常使用更稳妥。

全局一键安装

npm install -g @openhands/agent-canvas agent-canvas # 启动完整本地栈

三种方式的区别：

VM 方式还要处理防火墙与密钥访问，见docs/SELF_HOSTING.md。

跑起来之后：三个高频用法

让智能体写代码并执行

在聊天框输入：“创建一个 bash 脚本，输出 Hello World 并运行它”。智能体先写出hello_world.sh，再执行它，并把运行输出回传到对话里。你只需核对三处：

• 命令以“已执行”的块呈现，而不是单纯贴一段代码建议
• 终端输出里包含预期结果
• 工作区文件列表里出现了生成的脚本

让它处理你自己的项目

新建一个指向项目目录的会话（Docker 方式下即PROJECTS_PATH里的某个目录），输入“给 utils 模块补充单元测试”。智能体会读代码、改文件、在沙箱里跑测试，你可以随时切回去看改动 diff。

建一个定时自动化

进入 Automate 区域，Templates 里有现成模板，也可以点 Add Automation 自己写。

图 2：仪表盘展示每个自动化的运行次数、近期成功率和平均耗时

比如 “PR Review on Open” 在新 PR 打开时自动做代码评审，“Nightly Security Pass” 每天凌晨扫描漏洞。想立刻看效果，点 “Run now” 手动触发一次即可。

图 3：Templates 页提供开箱即用的自动化模板，可复制修改后启用

智能体行为不对时按顺序查：LLM key 是否配置、会话是否指向了正确的目录、侧边栏后端状态是否为 Healthy。

避坑与调优

8000 端口被占用—— 原因：别的进程占用了默认 ingress 端口。解法：用PORT环境变量改口，例如PORT=8080 npm run dev，再访问新端口。

首次启动为什么这么慢—— 原因：第一次npm run dev时uvx会从 PyPI 下载 agent server 及其 Python 依赖，前端还要装 JS 依赖。解法：等它跑完即可，之后启动走缓存，快得多。

npm install 报版本错误—— 原因：package.json要求 Node 22.12 以上，你当前的 Node 偏旧。解法：先升级 Node 再装依赖。

要开放到局域网或公网怎么办—— 直接把 agent server 暴露出去，任何能连上的人都能读写你的文件。解法：部署到带防火墙的 VM，用openssl rand -base64 32生成密钥并导出LOCAL_BACKEND_API_KEY，再以--public启动，UI 首次加载会要求输入密钥才能操作。

智能体表现不够聪明或太贵—— 在 Customize 里切换 LLM profile：复杂重构换强模型，批量小脚本用便宜模型；再配合 Skills 开关控制智能体加载的能力集。

现在你手里有一个跑起来的 Agent Canvas，智能体可以读写你工作区的代码并按你的指令执行命令。下一步，试着把一件重复性工作——比如生成每日构建报告——做成定时自动化，或者直接指向一个团队共享目录试试。

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