企业官网建设流程全解析

OpenHands Agent Canvas 快速上手：本地部署 AI 编码代理与自动化控制中心

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

OpenHands Agent Canvas 是面向开发者的自托管 AI 控制中心：在浏览器里运行 OpenHands、Claude Code、Codex 等编码代理，并把重复任务交给定时或事件触发的自动化。适合想把 AI 编程助手跑在自己机器或内网服务器上、要求代码和数据不出本地的开发者。

先判断它适不适合你的场景

• 适合：在笔记本、专用小主机（如 Mac Mini）或云虚拟机上运行编码代理，工作区完全由你控制。
• 适合：多后端切换——同一套界面里既能连本机 agent server，也能连团队共用的远程或云后端。
• 适合：把重复工作自动化，例如定时生成报告、按 webhook 触发任务，并对接 Slack、GitHub 等工具。
• 不适合：期望开箱即用、零运维的体验。你需要准备 Node.js 或 Docker 环境，且 agent 对运行机器拥有完整文件系统和命令执行权限，不要直接指向存有生产凭据的机器。

这是自动化仪表盘：每个自动化的运行次数、成功率和平均耗时都直接展示，也是你判断自动化是否健康运行的入口。

运行前检查

• Node.js 22.12 及以上版本和 npm（走 npm 安装路径时需要）
• uv：agent server 通过 uvx 启动，提前装好可避免首次启动失败
• Docker Desktop 或 Docker Engine（走容器路径时需要）
• 一个存放项目代码的目录，Docker 路径下作为 PROJECTS_PATH 挂载
• 稳定的外网连接：首次启动要拉取前端包、agent server 依赖和容器镜像
• 一个 LLM API Key：页面能打开不等于能对话，开始第一个会话前需要在设置里配置模型密钥

资源方面，内存 2GB 起步、建议 4GB 以上；磁盘预留 5GB 左右给依赖、镜像和会话记录。

最小部署路径

方式一：npm 全局安装（最快，无沙箱）

全局安装后启动完整本地栈（前端 + agent server + 自动化后端 + 入口代理）：

npm install -g @openhands/agent-canvas

agent-canvas

注意：此模式下 agent server 直接跑在你的机器上，可以读写你的文件系统。只想拆开跑时，可加--frontend-only或--backend-only参数。

方式二：Docker 容器（推荐，带沙箱）

先创建项目目录和状态目录，再启动镜像，容器内的 agent 只能访问你挂载进去的目录：

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

Windows 用户在 PowerShell 下的等效命令见仓库根目录的 README.windows.md。

方式三：从源码运行

适合需要改动前端本身的用户：

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

关键配置说明

日常只需要关心这几项，其余保持默认即可：

• PORT：入口代理端口，默认 8000。端口冲突时修改该值，或调整 Docker 的 -p 映射。
• PROJECTS_PATH（Docker 专用）：agent 可见的项目目录。目录没创建或没挂进去，agent 就读不到你的代码。
• LOCAL_BACKEND_API_KEY：对外暴露时必填。用openssl rand -base64 32生成一次并妥善保管；配合--public模式，任何打开界面的人都必须先输入这个 key 才能使用。
• OH_AGENT_SERVER_VERSION / OH_AGENT_SERVER_GIT_REF：固定 agent server 的版本或 git 引用，避免后端行为随"最新版"漂移。

源码方式下可在项目目录创建 .env 文件（参考 .env.sample），常用项包括 VITE_BACKEND_BASE_URL、VITE_WORKING_DIR、VITE_FRONTEND_PORT，完整变量说明见 docs/DEVELOPMENT.md。

验证是否跑起来了

1. 打开 http://localhost:8000（Docker 镜像为 http://localhost:8000/canvas），看到 Agent Canvas 主界面即表示入口正常。
2. 按左侧 Getting started 清单添加 LLM API key，这是对话功能的前置条件。
3. 新建一个会话，让 agent 在工作区里创建一个 hello.py 并运行，看到生成的文件出现在文件面板里，说明代理、工作区和执行链路全部打通。

会话跑通后，进入 Customize 的 Skills 页可以看到全部可用技能，按状态和分类筛选后启用即可。

高频问题

端口 8000 被占用：设置环境变量 PORT 改用其他端口，或 Docker 下调整 -p 映射（例如 -p 8080:8000），访问地址同步修改。

首次启动卡在拉取依赖：npm 和 PyPI 都需要外网，检查代理配置；uv 未安装也会在此阶段失败，先装 uv 再重试。

容器里看不到本机项目：确认 PROJECTS_PATH 目录已创建，且 -v 挂载使用的是宿主机绝对路径。

对外部署后页面返回 502：说明 127.0.0.1:8000 上的进程没在运行，检查启动进程状态；防火墙只放行 80/443，agent server（18000）和自动化后端（18001）对公网保持关闭。

如何接入远程机器：在界面 Manage backends 中新增后端，填写主机名、URL 和 LOCAL_BACKEND_API_KEY，状态显示 Connected 后即可在同一界面里切换本地与远程。

跑通之后做什么

1. 阅读 docs/SELF_HOSTING.md，把 Canvas 迁到一台常开的虚拟机：配好防火墙、API key 和 systemd 服务，关机后任务也能继续跑。
2. 创建第一个自动化：从 Automate 页面新建定时任务，回到 Dashboard 确认出现运行记录。
3. 梳理 Skills 与 MCP Servers：关闭用不到的技能，接入你团队的 MCP 服务，保持 agent 上下文精简。

更多资料在 docs/ 目录：系统边界和运行模式见 docs/architecture.md，接入 Claude Code、Codex、Gemini 等 ACP 代理见 docs/ACP_AGENTS.md，各安装器与操作系统的测试覆盖见 docs/TESTING_MATRIX.md。

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