OpenHands Agent Canvas自托管编码 Agent 控制中心的安装、运行与架构解析【免费下载链接】OpenHands OpenHands: AI-Driven Development项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHandsOpenHands Agent Canvas 是一个自托管的开发者控制中心用于在同一界面上启动、切换和自动化多个编码 AgentOpenHands、Claude Code、Codex、Gemini 等支持本地、Docker 沙箱与云端后端的灵活部署。本文基于仓库根目录 README.md 展开覆盖三种安装方式的完整命令、CLI 参数与环境变量、Docker 镜像的内部服务路由并结合源码给出端口、版本与调用链的实现证据。读完后可独立完成从笔记本快速试用到 VM 上长期运行的完整部署。定位把编码 Agent 变成常驻工程团队Agent Canvas 的核心价值在于把分散的编码 Agent 收敛到一个自托管的控制中心开箱即运行开源的 OpenHands Agent也可驱动任意第三方 AgentClaude Code、Codex、Gemini CLI 等任何兼容 ACP 协议的 Agent默认在本地机器上运行但可连接多个「Agent 后端」agent backend例如把 Agent 放进 Docker 容器、虚拟机或公司自有基础设施中执行支持创建自动化automations例如定时生成报告并发布到 Slack或把 GitHub Issue 自动拆解为任务支持「自带模型」bring your own model与跨后端切换本地、远程、云后端可在同一前端间无缝切换。这一能力在 package.json 中也有体现npm 包名为openhands/agent-canvas当前版本 1.16.0同时暴露了agent-canvas可执行入口bin/agent-canvas.mjs、独立应用构建产物以及 browser、conversation、files、settings、sidebar、terminal、i18n 等库式入口说明它既可作为独立应用自托管也可作为组件嵌入其他宿主应用对应 docs/architecture.md 中的「Runtime modes / Packaging」部分。快速开始三种安装方式README 给出三种等价的部署路径分别对应不同安全边界。选择的核心判据是是否允许 Agent 直接访问宿主机文件系统。方式一无沙箱直跑npm 全局安装注意该模式让 agent-server 直接运行在安装目标机器上Agent 将获得对文件系统的完全访问权限仅在可信环境使用。前置条件Node.js 22.12.x 或更高版本package.json 中engines.node要求22.12.0以及uv用于通过uvx拉取 Python 侧的 agent-server。npm install -g openhands/agent-canvas agent-canvasagent-canvas命令默认启动完整本地栈。如果希望把各部分拆开单独运行agent-canvas --frontend-only # 仅静态前端 ingress 代理 agent-canvas --backend-only # 仅 agent server automation backend ingress 代理方式二Docker 沙箱推荐用于个人机器前置条件DockermacOS/Windows 用 Docker DesktopLinux 用 Docker Engine/Docker Desktop一个作为PROJECTS_PATH的宿主机目录存放希望 Agent 访问的项目文件夹需在启动容器前创建。macOS / Linuxexport 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.16.0WindowsPowerShell等价命令见 README.windows.md要点是docker pull后使用Join-Path构造路径并以反引号续行执行同样的docker run。启动后 Agent 可访问PROJECTS_PATH下的任意项目。这里的两个卷挂载与 Dockerfile 完全对应docker/Dockerfile 声明了VOLUME [/home/openhands/.openhands, /projects]并注释说明前者持久化「设置、密钥、会话、自动化数据库」后者是「Agent 可读写用户代码」镜像预创建了/home/openhands/.openhands/agent-canvas/conversations、bash_events、automation等子目录并 chown 给openhands用户因此宿主机挂载点建议是空目录或已存在的用户目录。方式三从源码运行同样是「agent-server 直跑」模式Agent 对宿主机文件系统有完全访问权限。前置条件Node.js 22.12.x、npm、uv用于通过uvx运行 agent server。git clone https://github.com/OpenHands/OpenHands.git cd OpenHands npm install npm run dev访问入口与后端管理启动完成后npm / 源码启动方式访问http://localhost:8000Docker 镜像访问http://localhost:8000/canvas镜像构建时通过VITE_BASE_PATH/canvas把前端烘到子路径下见 docker/Dockerfile。额外后端可以直接在 UI 中添加。README 强调的一点是「多后端」可以把同一个 Agent Server 共享给团队做代码评审和依赖更新同时保留笔记本上的个人 Agent在同一 Agent Canvas 前端之间切换而不中断上下文。CLI 参数与环境变量来自源码的完整说明上面只列了 README 出现的两个拆分参数。完整的参数面可从 CLI 入口 bin/agent-canvas.mjs 的--help输出处确认该文件是agent-canvas命令的入口默认以「生产等价模式」运行通过uvx拉起 agent-server 与 automation backend并服务预构建的静态前端即npm run dev的产物化等价物。参数参数作用-p, --port portingress 代理端口默认 8000--public启用 public 模式API key 不再注入前端用户首次打开 UI 需手动粘贴LOCAL_BACKEND_API_KEY要求设置该环境变量--frontend-only仅启动 ingress 后的静态前端--backend-only仅启动 agent-server automation backend与--frontend-only、--public互斥入口代码中有显式校验并报错退出-v, --version输出版本号--info输出默认栈版本、兼容下限与各服务端口-h, --help帮助信息环境变量变量说明LOCAL_BACKEND_API_KEY服务端 API key。非 public 模式下可省略自动生成并在重启间持久化public 模式下必填OH_SECRET_KEY用于加密设置的密钥OH_AGENT_SERVER_GIT_REFagent-server 的 Git 引用OH_AGENT_SERVER_LOCAL_PATH本地 software-agent-sdk checkout 路径用于开发优先级最高会从本地源码重建 agent-server 并以 editable 方式安装 SDK 组件OH_AGENT_SERVER_VERSION指定 agent-server 的 PyPI 版本帮助文本还明确了一点常被问到的问题LLM 配置通过 Web UI 的设置页完成而不是环境变量。从入口实现看agent-canvas最终调用 scripts/dev-with-automation.mjs 的main()传入staticMode: true与构建目录build/该脚本头部的注释也完整画出了 ingress 的路由拓扑/api/automation/*路由到 Automation Backend:18001/api/*与/sockets路由到 Agent Server:18000其余路径路由到 Vite 开发服务器或静态服务。默认版本与端口所有 npm 与 Docker 安装路径共享的「单一事实来源」是 config/defaults.jsonagent-canvas --info读取的就是它版本钉定agent-server1.44.0、agent-canvas1.16.0、automation1.9.0agent-server 兼容下限1.28.0端口ingress8000、agent-server18000、automation18001、内置编辑器vscode8001路径状态子目录agent-canvas/、会话目录、bash 事件目录、automation 数据库automation/automations.db、Canvas 基路径/canvas、编辑器基路径/vscode。此外该文件还包含一个值得注意的约束agent-client-protocol被临时钉在0.11acp 0.11.0 重排了prompt()参数会破坏 SDK 的 ACP 客户端这解释了本地启动脚本为什么需要对 uvx 安装命令做约束处理从源码结构看约束由 scripts/dev-safe.mjs 消费。架构Agent Canvas、Agent Server 与 Automation ServerREADME 的 Architecture 部分给出了三层结构docs/architecture.md 进一步明确了系统边界Agent Canvas本仓库React TypeScript 前端直接对接 OpenHands Agent Server。它负责渲染会话、终端、浏览器、文件、设置与自动化 UI管理前端状态并把 UI 操作翻译成 Agent Server API 调用它不负责执行 Agent 动作、提供沙箱隔离、托管 LLM 凭证也不在没有 automation 后端时运行定时/事件触发的自动化。OpenHands Agent Server一个「在单机上运行多个 Agent」的 REST API。每个 Agent Server 监听单一 host/portAgent Canvas 可同时连接多个 Agent Server 并在 UI 中切换。Agent Server 可以跑在任何地方笔记本谨慎、专用机器Mac Mini 等、云上虚拟机、OpenHands Cloud。Automation Server可选配套负责「什么时候跑」——按调度或事件webhook把会话派发给 Agent Server/SDK 执行Agent Canvas 前端中的自动化功能即对接它。关于仓库分工README 的「Repository boundaries」表格明确了多仓库边界变更应提交到拥有该行为的仓库仓库职责OpenHands/OpenHands本仓库Agent Canvas 前端、用户控制中心、后端选择、本地栈编排OpenHands/software-agent-sdkPython SDK、Agent Server、Agent、工具、会话、工作区、事件与规范服务端 APIOpenHands/typescript-client浏览器可用的 Agent Server API TypeScript 客户端OpenHands/automation自动化定义、调度、webhook、运行历史与派发本仓库前端最重要的源码区域见 docs/architecture.mdsrc/api/Agent Server、云、设置、git、skills、automations、backend registry 的服务适配器、src/components/会话、聊天、浏览器、文件、设置、后端、自动化等路由与功能 UI、src/hooks/React Query 与状态 hooks、src/stores/Zustand 状态、src/mocks/MSW 处理器、以及bin/与scripts/CLI 与开发栈启动器。单端口 ingressDocker 镜像内部路由Docker 镜像把三个服务合并进一个镜像docker/Dockerfile 头部注释Agent Server 基于上游 SDK 镜像ghcr.io/openhands/agent-serverAutomation 通过 pip 安装openhands-automation钉定版本前端为预构建静态产物由 Node 静态服务器提供。入口docker/entrypoint.sh启动全部服务与一个 ingress 代理统一在 8000 端口暴露路由规则为/api/automation/* → automation backend (:18001) /api/*, /sockets → agent server (:18000) /* (default) → 静态前端 SPA fallback这也是为什么容器只EXPOSE 8000一个端口而README中的docker run只需-p 8000:8000。ACP Agent接入 Claude Code、Codex、GeminiREADME 能力表中「Use with any agent」对应的实现细节在 docs/ACP_AGENTS.mdAgent Canvas 并不直接调用 LLM而是由 Agent Server 以子进程方式拉起 ACP Agent 的 CLIstdio 上的 JSON-RPC逐轮转发消息。外部 Agent 自管 LLM、工具与执行Agent Canvas 只记录「跑哪个 Agent」并渲染返回内容。内置支持的提供方与默认命令提供方默认命令Claude Codenpx -y agentclientprotocol/claude-agent-acpCodexnpx -y agentclientprotocol/codex-acpGemini CLInpx -y google/gemini-cli --acp认证上有两类方式订阅登录provider 自有 CLI 在本地存的登录态如 macOS Keychain、~/.codex/auth.json、~/.gemini/oauth_creds.json或 API keyANTHROPIC_API_KEY/OPENAI_API_KEY/GEMINI_API_KEY。关键点登录态优先于 API key——在 Agent Server 与用户同一台机器本地/自托管后端时通常无需配置任何 key而在干净的云端沙箱中则必须提供 API key。Agent 选择按后端backend维度存储切换后端即可能切换 Agent。提供方清单来自 SDK 注册表并镜像进openhands/typescript-clientCanvas 侧仅在 src/constants/acp-providers.ts 补充 UI 元数据。自托管与安全加固README 指出「最强大的运行方式是部署在云服务器上」——Agent 可以持续运行并方便地被 Slack、GitHub、Datadog 等第三方服务触发。完整操作与加固细节在 docs/SELF_HOSTING.md要点准备一台常开的 Linux/macOS 主机云 VM 或 Mac Mini、NUC 等专用硬件先加固再启动默认只允许 SSH且限源 IPingress:8000、agent-server:18000、automation:18001、静态服务:3001全部绑定127.0.0.1禁止对外可达生成密钥并 public 模式启动openssl rand -base64 32生成 keyexport LOCAL_BACKEND_API_KEYkey后npx openhands/agent-canvas --public。public 模式下 API key 不注入前端用户需在 UI 首次加载时粘贴每个/api/*调用都必须携带匹配的X-Session-API-Key头可选nginx Lets Encrypt 提供 TLS只开放 80/443可选在本地 Agent Canvas 中把该远程添加为后端实现「本地前端 云端 Agent」组合。SELF_HOSTING 文档还记录了一个值得注意的安全边界内置编辑器OpenVSCode通过路径前缀默认/vscode复用 Canvas 的浏览器源路径前缀只做路由不做隔离编辑器侧的脚本可读 Canvas 的localStorage其中保存了该浏览器内所有已注册后端的 SESSION API key——这正是「单一端口部署」的代价公网暴露前应知悉。docs/architecture.md 的 Security posture 一节亦呼应此点本地运行会让 Agent 访问用户工作区因此推荐笔记本场景使用 Docker 沙箱模式自托管部署应叠加常规服务器加固、认证、HTTPS、防火墙与谨慎的工作区限定。运行时模式与开发命令docs/architecture.md 以表格形式列出了package.jsonscripts 对应的运行模式与 package.json 中的定义一致模式用途npm run dev在宿主机直接启动完整本地栈uvx拉起 agent-server 与 automation backend、Vite 开发服务器、ingress 代理。Agent 拥有宿主机文件系统访问权仅用于可信环境npm run dev:minimal仅 agent-server Vite 开发服务器不含 automation backendnpm run dev:static同dev但服务前端生产构建而非 Vite 开发服务器npm run dev:mock前端对接 MSW mock用于 UI 开发与测试npm run build构建独立应用npm run build:lib构建用于嵌入的库式入口配套的质量门CInpm run linttypecheck ESLint Prettier、npm test单元/组件测试、npm run build与npm run build:lib双构建验证、npm pack --dry-run打包校验。npm 包通过 GitHub Actions 的 trusted publishing 与 provenance 发布postinstall脚本还会在全局安装后打印启动提示agent-canvas默认http://localhost:8000。延伸阅读围绕 README 的更多文档均可在当前仓库内查阅docs/README.md文档索引docs/architecture.md系统边界、运行时模式与质量门docs/DEVELOPMENT.md开发指南docs/SELF_HOSTING.mdVM 自托管与安全加固docs/ACP_AGENTS.md接入外部 ACP Agentdocs/TESTING_MATRIX.md跨安装器、操作系统与 Agent 的发布冒烟测试矩阵AGENTS.md贡献者视角的仓库边界与评审规范。【免费下载链接】OpenHands OpenHands: AI-Driven Development项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考