OpenHands 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

OpenHands 是一个以 TypeScript 为主要语言、采用 MIT 许可证的开源项目。根据仓库 README，当前资料展示的产品界面名称为 Agent Canvas，它定位为面向编码代理（coding agent）和自动化任务的自托管开发者控制中心。

项目提供本地运行、Docker 沙箱运行和从源码运行三种启动路径，并允许在同一个前端界面中连接本地、远程及云端代理后端。仓库元信息显示，项目有 84,210 个 Star 和 10,932 个 Fork，默认分支为 main；这些数值属于所给 GitHub 仓库资料中的快照，不代表实时统计。

• 项目描述：AI-Driven Development。
• 当前 README 展示的产品名：Agent Canvas。
• 主要语言：TypeScript。
• 许可证元信息：MIT。
• npm 包：@openhands/agent-canvas，资料中的版本为 1.13.0。
• 默认本地访问地址：http://localhost:8000；Docker 镜像的 README 示例使用 http://localhost:8000/canvas。

“OpenHands Agent Canvas turns your coding agents into a self-hosted, always-on engineering team.”
来源：README

定位与目标用户

本项目解决的不是单一代码补全问题，而是编码代理的运行、切换和任务编排问题。用户可以从可视化界面发起对话，也可以配置自动化流程，把 GitHub、Slack、Linear、Notion 等服务纳入任务链路；具体可用连接器和触发器应以当前文档及界面配置为准。

目标用户需要能够接受代理访问代码目录、执行开发任务，并且愿意承担模型调用、运行环境和凭据管理责任。README 明确提供了本地机器、专用计算机和云端服务器三类部署位置，但没有在所给资料中提供团队规模、并发限制、服务等级协议（SLA）或资源容量指标。

• 需要在个人计算机或服务器上运行编码代理的开发者。
• 需要同时接入 OpenHands、Claude Code、Codex、Gemini 或其他 Agent-Client Protocol（ACP）兼容代理的团队。
• 需要把代码审查、依赖更新、报告生成等重复任务交给自动化流程处理的工程团队。
• 需要保留自托管边界，并自行决定代理运行在本机、Docker、虚拟机或企业基础设施中的组织。

核心功能

核心能力可以归纳为“代理接入、后端切换、自动化编排和模型配置”四个层面。每一层都依赖 Agent Canvas 前端与代理服务端之间的连接，不能仅凭安装前端静态文件获得完整的代理执行能力。

多代理接入

Agent Canvas 内置 OpenHands agent，并可接入 Claude Code、Codex、Gemini 以及符合 ACP 的第三方代理。其工作方式是由前端选择代理后端并建立会话，代理后端负责实际执行编码任务；资料没有提供 ACP 消息格式、认证字段或完整接口签名，因此不应根据本文自行推导接入协议细节。

这类设计适合已经存在多个代理运行环境的团队：界面负责统一入口，具体执行位置由后端配置决定。代理能够访问哪些代码、执行哪些命令，取决于对应后端的权限和隔离配置，而不是仅由前端名称决定。

多后端切换

README 将后端分为本地、远程和云端等运行位置，并说明可以在同一个 Agent Canvas 前端中切换。输入是后端地址或后端配置，输出是可选的代理运行目标；会话是否跨后端保留、不同后端之间的状态同步规则，所给资料没有明确说明。

官方示例提到，团队可以共享一个用于代码审查和依赖更新的 Agent Server，同时让个人代理运行在本机。这个场景要求管理员分别确认项目挂载、网络可达性、凭据范围和任务数据的存储位置。

自动化工作流

自动化功能用于按计划运行任务，或在 webhook 事件到达时触发流程。README 给出的示例包括生成报告并发布到 Slack，以及把 GitHub issue 自动拆分为任务；自动化可以与 Slack、GitHub、Linear、Notion 等第三方服务连接。

从机制上看，流程至少包含触发器、代理任务和外部服务动作三个阶段：触发器提供事件或时间条件，代理执行分析或代码任务，动作把结果发送到目标服务。资料没有给出调度器实现、重试策略、并发模型和 webhook 签名校验方式，因此生产部署前必须依据官方自动化文档进行核验。

自带模型选择

README 提供“Bring your own model”能力，说明项目可以使用任意大语言模型（LLM）。模型选择属于 LLM profile 配置范围，输入是模型及其连接设置，输出是代理会话中的模型调用；所给资料没有列出供应商名称、API 地址字段、密钥变量或费用控制选项。

因此，本文不提供未经资料验证的模型配置样例。涉及 API 密钥时，应使用本地环境变量或官方支持的密钥配置方式，不应把真实凭据写入仓库、截图或自动化日志。

系统架构与关键模块

架构的明确边界是：Agent Canvas 负责开发者控制中心和界面，OpenHands Agent Server 负责代理服务端能力，自动化后端负责工作流相关处理。README 还说明，Agent Canvas 由 OpenHands Agent Server 驱动；所给 README 在 Architecture 标题后的内容被截断，因此更底层的模块关系不在本文擅自补充。

• Agent Canvas 前端：提供对话入口、后端选择、自动化配置和代理交互界面。
• Ingress：启动命令的输出说明中包含静态前端、代理服务端、自动化后端与 ingress 的组合运行方式。
• OpenHands Agent Server：README 指定的代理服务端依赖，负责承接 Agent Canvas 发起的代理运行请求。
• 自动化后端：由完整启动命令拉起，用于处理自动化任务相关运行链路。
• 代理后端：可以位于本机、Docker 容器、虚拟机、企业基础设施或 OpenHands Cloud、OpenHands Enterprise 基础设施中。

从 package.json 可以确认，前端使用 React 19、React Router 7、Vite 8、TypeScript 6、Zustand 5、TanStack Query 5 和 Socket.IO Client 4 等依赖。依赖清单能够说明实现所采用的技术组件，但不能据此推断服务端协议、性能指标或部署拓扑。

三种本地运行模式

无沙箱模式和源码模式会直接在安装机器上运行 agent-server，README 对这两种模式都给出了文件系统权限警告。Docker 模式通过容器和主机目录挂载让代理访问项目目录，运行边界与挂载范围由 Docker 参数决定。

npm 启动器默认拉起完整本地栈，也支持拆分为仅前端或仅后端。拆分模式适合需要独立调试前端、服务端或 ingress 的开发环境，但资料没有说明各进程的独立端口分配。

依赖与运行环境

最小运行环境由 Node.js 和 uv 构成；Docker 路径还要求 Docker 与项目目录。package.json 将 Node.js 引擎约束为 >=22.12.0，README 的前置条件写法为 Node.js 22.12.x 或更高版本。

package.json 还声明包管理器为 npm@10.5.0，Volta 配置中的 Node.js 版本为 22.12.0。这两个字段属于项目包配置，不等同于所有平台上的强制安装方式；Windows 的 Docker 命令应参照仓库中的 README.windows.md，该文件内容未随本次资料提供。

快速开始：最小可运行示例

本节采用 README 明确给出的 npm 本地路径，完成安装、运行和验证三个步骤。该模式没有沙箱，代理服务端直接运行在本机，因此只应在已确认目录权限和任务内容的本地环境中测试。

步骤一：安装

npm install -g @openhands/agent-canvas

该命令安装 package.json 中声明的可执行命令 agent-canvas。README 规定需要 Node.js 22.12.x 或更高版本以及 uv；资料没有提供 uv 的安装命令，因此此处不补写安装步骤。

步骤二：运行

agent-canvas

默认启动完整本地栈。若只需要静态前端和 ingress，可以使用 agent-canvas --frontend-only；若需要启动代理服务端、自动化后端和 ingress，可以使用 agent-canvas --backend-only。这两个参数来自 README，不能据此推断前后端会使用不同的公开端口。

步骤三：验证

curl -I http://localhost:8000

npm 和源码启动器的 UI 地址是 http://localhost:8000。如果浏览器访问失败，应先检查命令是否仍在运行、8000 端口是否被其他进程占用，以及 Node.js 与 uv 是否满足 README 的前置条件。

Docker 沙箱示例

Docker 方式适合把代理限制在指定的项目目录内。下面的命令只挂载用户明确创建的项目路径和 OpenHands 配置目录，镜像标签及端口映射均来自 README。

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.13.0

代理在该示例中能够访问 PROJECTS_PATH 下的项目。镜像版本 1.13.0 是所给 README 示例中的值；发布时若仓库已更新，应以最新 README 的镜像标签为准。

配置说明

资料中没有提供独立的 .env.example、Docker Compose 文件或完整的 Agent Canvas 配置样例，因此无法列出未出现的环境变量和模型字段。下面的表格只整理 package.json 和 README 中明确出现的配置项，字段默认值以资料中的声明为准。

README 没有给出模型 API 密钥、远程后端地址、Slack 凭据或 webhook 配置字段。对于这些未提供的项目，官方仓库未提供该信息，建议以最新 README 和官方文档为准。

进阶用法

进阶用法的重点不是增加命令数量，而是根据任务边界选择运行位置和代理类型。README 支持从 UI 添加额外后端，因此可以先启动一个本地栈，再在界面中配置其他代理服务端。

拆分前后端

agent-canvas --frontend-only
agent-canvas --backend-only

前者启动静态前端和 ingress，后者启动 agent server、自动化后端和 ingress。资料没有说明两者分开启动时需要填写哪些连接参数，所以不应在缺少官方配置样例的情况下补充环境变量。

从源码开发

git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm install
npm run dev

源码开发路径使用 package.json 中的 dev 脚本，该脚本实际调用 scripts/dev-with-automation.mjs。package.json 还列出 dev:static、dev:extra-backend、dev:minimal、dev:frontend 和 dev:mock 等脚本；这些脚本的具体参数和服务边界，官方仓库未提供该信息，建议以当前源码和 README 为准。

构建与质量检查

package.json 提供 npm run build、npm run lint、npm run typecheck 和 npm test 等工程命令。测试脚本会先运行 make-i18n，再执行 Vitest；端到端测试使用 Playwright，说明项目把类型检查、静态检查、单元测试和端到端测试纳入开发流程。

• npm run build：调用 build:app 构建应用。
• npm run lint：执行类型检查、ESLint 和 Prettier 检查。
• npm run typecheck：先执行 React Router 类型生成，再运行 TypeScript 检查。
• npm test：生成国际化资源后运行 Vitest。
• npm run test:e2e：使用 Playwright 执行端到端测试。

可观测性与运维

所给资料能够确认项目包含 Winston 和 Winston Daily Rotate File 依赖，也包含 PostHog JavaScript 依赖，但没有提供日志字段、日志级别、文件路径、指标名称、追踪协议或数据保留策略。因此，不能把依赖存在直接解释为已经提供完整的可观测性方案。

自托管运维至少需要核对进程状态、8000 端口、项目目录挂载、后端连通性和自动化触发结果。云端服务器部署的价值在 README 中被描述为：笔记本关闭后代理仍可继续运行，并更容易从 Slack、GitHub、Datadog 等第三方服务触发；这属于部署场景说明，不构成可用性承诺。

运维检查清单

1. 确认 Node.js 版本满足 >=22.12.0，并确认 uv 可被启动器调用。
2. 确认 http://localhost:8000 能够访问；Docker 模式同时检查 /canvas 路径。
3. 确认 Docker 模式的 PROJECTS_PATH 已创建，并且只包含允许代理访问的项目。
4. 确认远程或云端后端的访问凭据没有写入 Git 仓库和公开日志。
5. 确认自动化任务的触发来源、执行结果和外部服务写入范围。

资料未提供健康检查接口、备份策略、升级回滚流程和高可用部署配置。对于这些运维能力，官方仓库未提供该信息，建议以最新自托管文档为准。

安全与合规边界

本项目涉及编码代理执行命令和访问代码目录，安全边界取决于运行模式与挂载权限。README 明确警告：无沙箱和源码模式会让 agent-server 直接运行在安装机器上，代理将拥有对该机器文件系统的完整访问权限。

Docker 示例通过挂载 PROJECTS_PATH 到容器内的 /projects 限制示例中的项目范围，但这不等于对所有运行行为作出安全保证。Docker 权限、宿主机目录权限、网络访问、镜像来源和容器运行参数仍需由部署方审查。

授权与隐私要求

• 只在拥有明确授权的本地项目、测试仓库和企业基础设施中运行代理。
• 不要把生产密钥、个人身份信息、客户数据或未授权仓库挂载给代理。
• 对 Slack、GitHub、Linear、Notion 等外部服务使用最小权限凭据，并单独确认写入和读取范围。
• 在共享 Agent Server 前，明确团队成员可访问的项目、会话和自动化结果。
• 对云端或企业后端核验数据处理地点、日志保留、模型供应商和组织内部合规要求。

资料没有提供威胁模型、漏洞披露政策、审计报告、数据保留期限、密钥轮换机制或企业合规认证。本文不提供未授权目标的攻击教程、绕过检测技巧或凭据获取方法；安全评估应限定在授权环境内。

许可证与商用条款

仓库元信息和 package.json 均标记为 MIT，所给项目资料也明确列出许可证为 MIT。MIT 许可证通常允许复制、修改、合并、发布、分发、再许可和销售软件副本，但本段的具体法律义务仍应以仓库中的 LICENSE 文件全文为准。

本次资料没有提供 LICENSE 文件正文，因此无法逐字核对版权声明、许可声明和免责声明条款。分发修改版或二进制版本时，应保留仓库要求保留的版权与许可文本，并同时遵守依赖项各自的许可证；商业部署前应由组织的法务或合规人员审阅。

• 许可证标识：MIT。
• 能否商用：根据 MIT 标识，允许商业使用；具体条件以仓库 LICENSE 为准。
• 版权与分发：应保留适用的版权声明、许可声明和免责声明，具体以仓库 LICENSE 为准。
• 第三方依赖：package.json 列出大量运行时和开发依赖，依赖项许可不能仅依据本项目 MIT 标识推断。

局限性与已知限制

当前资料适合确认项目定位、启动方式和前端依赖，但不足以形成完整的生产架构说明。README 的 Architecture 部分在所给内容中被截断，服务端内部模块、数据流和状态持久化规则没有完整展示。

• 没有提供性能基准、吞吐量、并发上限、任务耗时或资源推荐。
• 没有提供 SLA、官方支持周期或企业版服务承诺。
• 没有提供完整模型供应商配置、API 密钥字段和远程后端认证字段。
• 没有提供自动化重试、失败恢复、幂等性和 webhook 签名验证细节。
• 无沙箱和源码模式具有完整文件系统访问风险，不能直接视为隔离部署。
• Docker 方式的安全效果受挂载目录和宿主机权限影响，README 未给出完整加固参数。
• Windows 等平台的等价命令在单独的 README.windows.md 中，但该文件内容未提供。

根据本文作者的经验判断，如果任务包含高敏感代码、强隔离要求或严格审计要求，部署方应先完成权限、网络、凭据和数据流评估，再决定采用本地、Docker、虚拟机、企业基础设施或云端后端。这个判断不是项目官方性能或安全承诺。

适合谁

当组织需要统一管理多个编码代理，并且能够自行管理运行环境与权限时，Agent Canvas 的设计与需求较为匹配。以下信号可用于判断是否适合采用。

• 团队已有本地、Docker、虚拟机或企业内部代理服务端，需要在一个界面中切换。
• 团队有明确的代码审查、依赖更新、issue 拆分或报告发布流程，且任务可以通过计划或 webhook 触发。
• 组织能够提供 Node.js 22.12.x 或更高版本、uv、Docker 或可用服务器环境。
• 团队能够划分项目目录和第三方服务凭据的权限，并接受自行负责自托管安全加固。
• 团队希望使用 OpenHands 之外的 Claude Code、Codex、Gemini 或 ACP 兼容代理。

不适合谁

如果使用者无法接受代理访问代码和执行开发操作，或者需要资料中未声明的企业级保证，就不应仅凭 Star 数或项目描述作出部署决定。以下信号表示需要谨慎选择替代路径或先补足验证。

• 环境禁止代理直接访问本机文件系统，而团队又不能提供 Docker、虚拟机或其他隔离边界。
• 组织要求已确认的 SLA、并发容量、合规认证或数据驻留承诺，但当前资料没有这些声明。
• 团队需要现成的完整模型、凭据、审计和 webhook 配置文档，而仓库资料未提供对应字段。
• 任务面向未经授权的第三方系统，或需要绕过安全检测、访问控制和平台限制。
• 团队只需要一个静态代码编辑器，不需要代理后端、自动化触发器或多后端管理能力。

在场景 A 中，如果目标是自托管多个编码代理并编排开发任务，可以评估 OpenHands；在场景 B 中，如果目标只是编辑代码或需要资料未声明的托管保证，应选择组织已验证的其他工具或服务。资料没有指定具体替代产品，因此本文不作产品横向排名。

常见问题与排查（FAQ / Troubleshooting）

排查顺序应先确认版本和启动方式，再检查访问地址、目录挂载及后端配置。下面的问题均限定在 README 和 package.json 已提供的信息范围内。

Q1：安装后找不到 agent-canvas 命令怎么办

先确认使用了全局安装命令 npm install -g @openhands/agent-canvas，并确认 npm 全局可执行目录已加入当前用户的 PATH。项目通过 package.json 的 bin.agent-canvas 将命令映射到 bin/agent-canvas.mjs；具体 PATH 配置方法未在资料中提供。

Q2：为什么浏览器无法访问 8000 端口

确认启动命令仍在前台运行，并检查访问地址是否为 http://localhost:8000。Docker 模式还需要确认命令包含 -p 8000:8000；若端口已被占用，资料没有提供替代端口参数，不能直接假定启动器支持任意端口映射。

Q3：无沙箱模式有什么风险

README 的警告是：agent-server 直接运行在安装机器上，代理拥有完整文件系统访问权限。测试时应使用专门的工作目录和非敏感项目；如需限制访问范围，应评估 Docker 沙箱或其他隔离后端。

Q4：Docker 容器能访问哪些项目

README 示例将主机的 PROJECTS_PATH 挂载到容器的 /projects，并说明代理能够访问该目录下的项目。实际可访问范围还受到宿主机目录权限、容器权限及其他运行参数影响。

Q5：Docker 模式打开哪个地址

README 对 npm 和源码启动器给出的地址是 http://localhost:8000，对 Docker 镜像给出的地址是 http://localhost:8000/canvas。若实际版本行为与示例不同，应以当前仓库 README 和启动日志为准。

Q6：如何配置 API 密钥

所给资料只说明支持自带模型，没有提供具体密钥字段、环境变量或命令行参数。请不要把真实密钥替换到公开示例中；官方仓库未提供该信息，建议以最新官方文档的 LLM profiles 配置章节为准。

Q7：如何连接 Claude Code、Codex 或 Gemini

README 明确列出这些代理，并提供 ACP agents 文档入口，但当前资料没有给出安装、认证和启动参数。应按照官方 ACP agents 文档配置，而不是根据代理名称自行拼接命令。

Q8：源码修改后如何检查

可以依次运行 npm run typecheck、npm run lint 和 npm test。这些命令分别对应类型检查、代码质量检查和 Vitest 测试；端到端场景可使用 package.json 中的 npm run test:e2e。

项目地址与资源

以下链接均来自项目元信息或 README 中出现的官方站点，适合用于获取源码、产品文档、自托管说明和社区入口。

• OpenHands GitHub 仓库
• OpenHands 官网
• OpenHands 官方文档
• Agent Canvas 后端文档
• ACP 代理文档
• 预构建自动化文档
• 虚拟机后端设置文档
• LLM profiles 配置文档
• OpenHands Incubator Program
• OpenHands Slack 社区