机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

OpenHands Agent Canvas 将你的编码代理变成一个自托管、全天候运行的工程团队。它是一个开发者控制中心，用于启动对话和自动化日常任务——比如生成报告并发布到 Slack，或自动将 GitHub 问题分解为任务。

默认情况下，它在你的本地机器上运行，但可以连接到多个“代理后端”，例如在 Docker 容器、虚拟机或公司基础设施中运行代理。你也可以选择将代理运行在 OpenHands 云或 OpenHands 企业基础设施上。

Agent Canvas 开箱即用运行开源的 OpenHands 代理，但也可以使用任何第三方代理，如 Claude Code 和 Codex。

如果您有任何问题或反馈，请在 GitHub 上提交 issue 或加入 Slack 中的 #proj-agent-canvas 频道。

快速上手

您可以在任何设备上安装 OpenHands 以运行代理：在笔记本电脑上，在像 Mac Mini 这样的专用电脑上，或者在云服务器上。

运行 OpenHands 的最强大方式是在云服务器上。这允许您的代理即使在笔记本电脑关闭时也能继续运行，并且使通过第三方服务（如 Slack、GitHub 和 Datadog）触发代理变得更容易。有关详细信息，请参阅 SELF_HOSTING.md，特别是关于安全加固的部分。

值得注意的是，您可以在_多种不同环境_中运行后台服务，并且可以从同一个 Agent Canvas 前端在它们之间切换。例如，您可以与团队共享一个用于代码审查和依赖更新的代理服务器，然后让您的个人代理在笔记本电脑上运行。

选项 1：无沙箱

[!警告]
这会直接在您安装的设备上运行 agent-server——代理将可以完全访问您的文件系统！

先决条件：Node.js 22.12.x 或更高版本， uv

npm install -g @openhands/agent-canvas
agent-canvas

agent-canvas 命令默认启动完整的本地堆栈。你也可以在想要单独运行部分时拆分它：

agent-canvas --frontend-only  # static frontend + ingress only
agent-canvas --backend-only   # agent server + automation backend + ingress only

选项 2：使用 Docker 沙箱

先决条件：

• Docker：macOS/Windows 上的 Docker Desktop，或 Linux 上的 Docker Engine/Docker Desktop。
• 用于 PROJECTS_PATH 的主机目录，包含您希望代理访问的项目文件夹。在启动容器之前创建它。

macOS / Linux：

export PROJECTS_PATH="$HOME/projects"  # directory containing your project folders
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.20.0 # x-release-please-version

Windows（PowerShell / Windows 终端）： 请参阅 README.windows.md 获取等效命令。

该代理将能够访问 PROJECTS_PATH 下的任何项目。

选项 3：从源代码安装

[!警告]
这将在您安装的机器上直接运行代理服务器——代理将拥有对您的文件系统的完全访问权限！

先决条件：Node.js 22.12.x 或更高版本，npm，uv（用于通过 uvx 运行代理服务器）

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

通过 http://localhost:8000 访问 npm/source 启动器的用户界面，或通过 http://localhost:8000/canvas 访问 Docker 镜像。您可以直接从用户界面添加其他后端。

建筑

Agent Canvas 由 OpenHands Agent Server 提供支持，这是一个用于在单台机器上运行多个代理的 REST API。每个 Agent Server 运行在单个主机/端口上；Agent Canvas 可以连接到多个 Agent Server 并轻松在它们之间切换。

你可以在任何地方运行代理服务器：

• 直接在你的笔记本上（小心！）
• 在像Mac Mini这样的专用机器上
• 在云端的虚拟机上
• OpenHands Cloud（我们的商业产品）内部

代理服务器通常与自动化服务器配对使用，它可以让你设置按计划运行或响应事件的代理。

存储库边界

Agent Canvas 是多仓库 OpenHands 系统的一部分。更改应发送到拥有该行为的仓库：

代理服务器 API 由 SDK 实现，并通过代理画布使用 TypeScript 客户端进行调用。自动化服务决定工作何时运行，并将会话分派给代理服务器/SDK，由其决定执行内容。有关贡献者特定的边界和所需的自定义代码审查指南，请参见 AGENTS.md。

更多文档

• 文档索引
• 架构概览
• 开发指南
• 自托管指南