根据 OpenHands 官方仓库，OpenHands Agent Canvas 是一个自托管的开发者控制中心，用于运行和管理 AI 编码代理。以下是根据其文档整理的完整部署与使用教程。

🧭 核心概念与模式选择

Agent Canvas 的核心是提供一个统一的界面，让你可以在本地、远程服务器或云端启动、切换和管理多个 AI 代理（如 OpenHands 自身、Claude Code、Codex 等）。它本质上是一个“代理的操作系统”。

主要有两种部署模式，根据你的需求和硬件条件选择：

部署模式 说明与适用场景
无沙箱模式 (Without a Sandbox) 代理直接运行在你的宿主机上，拥有对你文件系统的完整访问权限。适合在你自己信任的开发机器上使用，需谨慎操作。
Docker 沙箱模式 (With a Docker Sandbox) 代理运行在隔离的 Docker 容器内，通过挂载卷仅能访问你指定的项目目录。推荐用于生产或对安全性有要求的场景，风险可控。

安全提示：无论哪种方式，Agent Canvas 都默认运行在 http://localhost:8000。如需暴露到公网，务必参考官方 SELF_HOSTING.md 进行安全加固。

📦 安装与部署

通用前提

  • Node.js：需要 Node.js 22.12.x 或更高版本。
  • 包管理器：npm（用于安装全局包）。
  • （可选）uv：用于运行 Python 编写的 Agent Server。如不安装，部分功能可能受限。

方式一：无沙箱模式（快速上手）

此方式直接在宿主机运行，适合个人开发环境。

步骤：

  1. 通过 npm 全局安装 Agent Canvas：

    1
    npm install -g @openhands/agent-canvas

  2. 启动服务：

    1
    agent-canvas

    该命令默认启动完整本地栈（前端 + 后端）。你也可以通过 --frontend-only 或 --backend-only 分别启动。

  3. 访问 http://localhost:8000 即可开始使用。

方式二：Docker 沙箱模式（推荐生产）

此方式将代理隔离在容器中，更安全。

步骤：

  1. 准备项目目录：在宿主机上创建一个目录（例如 $HOME/projects），用于存放你希望代理访问的代码项目。

  2. 运行 Docker 容器：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    # 对于 macOS / Linux
    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.15.0 # 或替换为最新稳定版本

    Windows 用户：请参考项目根目录的 README.windows.md 文件获取等效的 PowerShell 命令。

  3. 访问 http://localhost:8000/canvas 即可。

方式三：从源码运行（开发者）

适合想进行二次开发或调试的用户。

步骤：

1
2
3
4
git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm install
npm run dev

访问 http://localhost:8000。

🚀 快速开始与核心工作流

启动后，你可以进行以下典型操作：

  1. 配置 LLM：在设置中添加你的 LLM 提供商（如 OpenAI、Anthropic）的 API 密钥。Agent Canvas 支持使用任何 LLM。
  2. 连接后端：默认已连接本地 Agent Server。你可以通过 UI 添加更多后端（例如运行在远程 VM 上的 Agent Server），并在不同后端间切换。
  3. 创建对话/自动化：
    • 对话：点击“新建对话”，选择代理和模型，像使用 ChatGPT 一样描述你的开发任务（如“重构 src/utils.js 中的函数”）。
    • 自动化：你可以创建“自动化”（Automations），让代理在特定事件（如 GitHub 推送）或按计划（如每日）运行任务，并将结果发送到 Slack 等工具。

🔧 进阶配置与架构理解

  • 架构概览：Agent Canvas 前端通过 REST API 与 Agent Server 通信。Agent Server 负责实际运行代理。一个 Agent Canvas 可以连接多个 Agent Server（例如本地一个、云端一个），实现灵活切换。
  • 自带模型 (BYOM)：你可以在 LLM 设置中配置任何兼容 OpenAI API 格式的模型端点，或使用 Claude Code、Codex 等特定的 CLI 工具。
  • 自动化集成：Agent Canvas 可以与你日常使用的 Slack、GitHub、Linear 等工具集成，构建完整的 DevOps 自动化流水线。

📋 常用命令参考

命令 说明
agent-canvas 启动完整栈（前端+后端+入口）
agent-canvas --frontend-only 仅启动前端服务
agent-canvas --backend-only 仅启动后端 Agent Server 和自动化后端

💡 故障排查与最佳实践

  • 端口占用：确保 8000 端口未被占用。你可以通过 -p 参数映射到其他端口（如 -p 8080:8000）。
  • 权限问题：在 Docker 模式中，请确保 PROJECTS_PATH 目录的权限允许容器内的 openhands 用户读取。
  • 查看日志：Docker 模式下，日志会直接输出到终端。从源码运行时，日志在项目根目录下。
  • 生产部署：如需要持久化数据、配置 HTTPS 或进行用户管理，请务必阅读官方的 Self-Hosting 指南。

总结

OpenHands Agent Canvas 提供了一个强大的统一平台来管理你的 AI 开发团队。对于个人开发者，推荐从 Docker 沙箱模式开始，它既安全又易于上手。通过 npm 全局安装的“无沙箱模式”则更适合在完全受控的个人开发环境中快速测试。无论哪种方式，你都能获得一个可扩展的、自托管的 AI 开发控制中心。