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

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：无沙箱

先决条件：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

Access the UI at http://localhost:8000 for the npm/source launchers, or http://localhost:8000/canvas for the Docker image. You can add additional backends directly from the UI.

Architecture

Agent Canvas is powered by the OpenHands Agent Server, a REST API for running multiple agents on a single machine. Each Agent Server runs on a single host/port; the Agent Canvas can connect to multiple Agent Servers and easily flip between them.

You can run an Agent Server anywhere:

• Directly on your laptop (be careful!)
• On a dedicated machine like a Mac Mini
• On a virtual machine in the cloud
• Inside OpenHands Cloud (our commercial offering)

The Agent Server is often paired with an Automation Server, which lets you set up agents that run on a schedule or in response to events.

Repository boundaries

Agent Canvas is part of a multi-repository OpenHands system. Changes should go to the repository that owns the behavior:

The Agent Server API is implemented by the SDK and consumed through the TypeScript client by Agent Canvas. The automation service decides when work runs and dispatches conversations to the Agent Server/SDK, which decides what runs. See AGENTS.md for contributor-specific boundaries and the required custom code-review guide.

更多文档

• Documentation index
• Architecture overview
• Development guide
• Self-hosting guide