用途
OpenHands 是面向编码智能体与自动化的自托管开发者控制中心。其 Agent Canvas 可将编码智能体变为自托管、常驻的工程团队。
主要能力
- 可运行 OpenHands，也可使用第三方智能体，如 Claude Code、Codex、Gemini CLI、Pi、OpenCode，或任何兼容 ACP 的智能体。
- 支持在本地、远程和云端后端之间切换：可在 Docker 容器、虚拟机或公司基础设施中运行智能体。
- 可选用 OpenHands Cloud 或 OpenHands Enterprise 基础设施运行智能体。
- 用于发起对话和自动化日常任务，例如生成报告并发布到 Slack，或自动将 GitHub 问题分解为任务。
- 支持通过 Slack、GitHub、Datadog 等第三方服务触发智能体。
- 可在同一 Agent Canvas 前端连接多个 Agent Server 并在其间切换。例如团队共用一台 Agent Server 做代码审查和依赖更新，个人智能体在本机运行。
- 可搭配 Automation Server，按计划或响应事件运行智能体。
- Agent Canvas 基于 OpenHands Agent Server（一个用于在单台机器上运行多个智能体的 REST API），每个 Agent Server 运行在单个主机/端口上。
使用方式
提供四种安装/运行方式：
选项 1：无沙箱
在安装所在机器上直接运行 agent-server，智能体将拥有完整文件系统访问权限。
前置条件：Node.js 24 或更高版本，uv。
默认命令 agent-canvas 启动完整本地栈，也可拆分运行各部分。
选项 2：使用 Docker 沙箱 前置条件：Docker（macOS/Windows 使用 Docker Desktop，Linux 使用 Docker Engine/Docker Desktop）；一个用于 PROJECTS_PATH 的主机目录，其中包含智能体需要访问的项目文件夹，需在启动容器前创建。 智能体可访问 PROJECTS_PATH 下的任何项目。Windows 等效命令见 README.windows.md。
选项 3：使用多个 Docker 沙箱 每个新对话在其自己的 Docker 容器中运行，拥有自己的 Agent Server 和工具，适合并发运行多个智能体。Canvas 和外层 Agent Server 在主机上运行，并将对话请求路由到容器。 前置条件：Node.js 24 或更高版本，uv，以及运行中的 Docker Desktop（macOS）或 Docker Engine/Desktop（Linux）。启动 Canvas 的用户必须能运行 docker 命令。 访问 http://localhost:8000 并开始新对话。现有本地对话不会被转换。每个容器挂载其对话的工作区和持久化状态，因此工作区文件和对话历史在容器替换后仍保留。使用相同主机工作区的对话仍共享这些文件；为避免编辑冲突，请选择不同目录或工作树。此设置隔离对话执行，不会将整个 Canvas 或自动化服务移入沙箱。Windows 见 README.windows.md。
选项 4：从源码运行 前置条件：Node.js 24 或更高版本，npm，uv（用于通过 uvx 运行 agent server）。 对于 npm/源码启动器，访问 UI 的 http://localhost:8000；对于 Docker 镜像，访问 http://localhost:8000/canvas。可直接在 UI 中添加其他后端。
网络与安全说明
本地（npx / npm run dev）监听仅绑定回环地址（127.0.0.1），因此自动注入的会话密钥无法从网络中的其他机器访问。要监听所有接口，传入 --host 0.0.0.0（或设置 OH_BIND_HOST），此时不会注入会话密钥，UI 使用与 --public 相同的 API 密钥输入界面。
Docker 监听所有容器接口以便端口发布，但默认不会将会话密钥注入 HTML。上述快速开始显式启用了注入，同时仅将主机端口发布到 127.0.0.1。如果在 LAN 或公网接口上发布 Docker，请省略 AGENT_CANVAS_ALLOW_LAN_SESSION_KEY 并在 UI 中输入 API 密钥。请将 LOCAL_BACKEND_API_KEY 设为强值，或通过 docker exec <container> sh -c 'cat "$STATE_DIR/api-key.txt"' 获取生成值。面向互联网的安装请遵循自托管指南（SELF_HOSTING.md），尤其是安全加固部分。
适用场景
- 在本机笔记本、专用机器（如 Mac Mini）或云服务器上运行智能体。
- 在云服务器上运行可获得最强能力：即使笔记本关机，智能体仍可继续运行，且更容易通过 Slack、GitHub、Datadog 等第三方服务触发智能体。
- 团队共享 Agent Server 执行代码审查和依赖更新；个人智能体在本机运行。
- 并发运行多个智能体（多 Docker 沙箱模式）。
限制与边界
- 无沙箱模式（选项 1）下智能体拥有完整文件系统访问权限。
- 多 Docker 沙箱模式仅隔离对话执行，不会将整个 Canvas 或自动化服务移入沙箱。
- 使用相同主机工作区的对话共享文件，需选择不同目录或工作树以避免编辑冲突。
- 本地启动器默认仅监听回环地址；改为监听所有接口时不再注入会话密钥。
- Agent Server API 由 SDK 实现，并由 Agent Canvas 通过 TypeScript 客户端消费；自动化服务决定何时运行工作并将对话分派给 Agent Server/SDK。
更多文档
仓库提供文档索引、架构概览、开发指南和自托管指南。如有问题或反馈，可在 GitHub 提交 issue 或加入 Slack 的 #proj-agent-canvas 频道。
