电脑刚打开桌面版，却不知道 Agent 到底跑在哪里；或者终端一关，任务也跟着停止。
最快解法：个人试用优先桌面预览版或 npx；要限制本地文件访问选 Docker；要常驻运行、团队共享或使用更强资源，就连接 Remote Backend。

最后更新于 2026 年 9 月 7 日，安装命令、桌面应用状态与后端连接方式核实自 2026 年 9 月 6 日的官方资料。

这篇文章适合三类人：第一次安装 OpenHands Agent Canvas、还不熟悉 Node.js 与 uv 的个人开发者；准备让 Agent 修改本地项目、但不想开放整个用户目录的 Docker 用户；以及需要为团队提供持续运行后端的平台工程师和技术负责人。

五类场景的直接选择

先不要从“哪个安装命令最短”开始，而要先判断执行环境。Agent Canvas 是客户端，真正运行 Agent、工具、设置、密钥和自动化任务的是活动后端；工作区则决定 Agent 能读写哪些文件。官方架构文档也将客户端、后端和执行环境分开描述，后端所在位置才是权限与持续运行能力的核心。 Agent Canvas 架构说明

  • 只想完成首次试用：选桌面预览版，或直接运行 npx @openhands/agent-canvas。Agent 在本机后端运行，默认可接触本机允许它使用的工作区；关闭桌面应用或终端后，本地进程停止。
  • 需要让 Agent 修改一个本地项目：如果项目不敏感、你信任当前用户环境，可用 npm 或 npx；如果必须限制目录，选 Docker，只挂载项目目录和必要的持久化目录。
  • 需要可重复的隔离开发环境：选 Docker。Agent 在容器内执行，能访问你显式挂载的目录；容器停止后，未挂载的数据通常不会保留，设置和会话应放入持久化目录。
  • 需要后台常驻或跨设备访问：选 Remote Backend，把 Agent Server 放到持续在线的 VM、专用主机或远程 Mac，本地 Canvas 只连接它。电脑休眠、终端退出不会直接终止远程任务。
  • 需要团队共享：不要只共享一个浏览器地址。你要分别设计共享界面、共享后端和共享执行环境，并按 Linux 通用任务与必须使用 macOS 工具链的任务分池。

决策评分：桌面预览版的首次启动便利性为 5 / 5，本机隔离性为 2 / 5；Docker 的边界清晰度为 4 / 5，跨设备能力为 2 / 5；Remote Backend 的持续运行能力为 5 / 5，初始运维复杂度为 3 / 5。这些是部署决策评分，不是性能测试。

首次启动路径：桌面版、npx 与 npm

当前官方将 macOS、Windows 和 Linux 桌面应用标注为早期预览。桌面版会捆绑 Node.js 与 uv，普通试用者不需要先配置 Node.js、npm 和 uv，也不需要一直保留终端窗口。macOS 预构建安装包支持 Apple silicon；Intel Mac 应改用 npm 或源码方式。 官方安装页

Agent Canvas Desktop App 的价值是减少前置配置，不是自动提供沙盒。它启动的是本地后端，Agent 仍然会在该后端所在的机器上执行命令、读写工作区并使用连接的工具。因此，桌面应用解决的是“怎样更快打开页面”，没有自动解决“Agent 能碰到哪些文件”。

如果你使用桌面版，建议按以下顺序完成最小验证：

  1. 从官方发布页下载与你操作系统匹配的安装包；macOS 用户先确认是 Apple silicon 还是 Intel。
  2. 安装并启动 Agent Canvas，等待本地后端自动启动。
  3. 打开 Settings > LLM，配置模型访问方式。
  4. 使用 Open Workspace 选择一个专门的测试目录，不要一开始就选择整个用户目录。
  5. 创建最小任务，例如让 Agent 在测试目录中创建一个文本文件，并说明文件路径。
  6. 手动检查文件是否只出现在预期目录，再关闭应用并重新启动，确认会话和配置是否按你的预期保留。

npx 适合一次性试用：

npx @openhands/agent-canvas

npm 全局安装适合经常使用：

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

本地启动默认通过 http://localhost:8000 访问。npx 不会把软件包作为全局命令长期安装，npm 则便于以后重复运行；两者的共同限制是 Agent 和后端仍然直接运行在本机，终端关闭后本地服务停止。 npm 与 npx 安装步骤

如果页面能打开但后端显示断开，不要先重复配置模型。先检查启动命令所在的终端、端口是否被占用，以及 uv 是否可用。当前本地路径要求 Node.js 22.12 或更高版本，同时需要 npm 与 uv；桌面预览版则会自行携带这些运行时。Node.js 的安装方式也应以对应平台的官方包管理说明为准。 Node.js 官方安装说明

本地项目：权限边界与文件范围

本机直接运行时，Agent Server 可能以当前用户身份执行 shell 命令，并接触该用户有权限访问的文件、环境变量和网络。是否方便打开界面，与是否限制了执行权限，是两个不同问题。

本机方案适合以下条件：

  • 测试仓库没有生产密钥、个人证书或客户数据；
  • 你能接受 Agent 以当前用户权限运行；
  • 任务需要访问本机工具链，而且不方便容器化；
  • 任务失败后可以通过 Git 回滚，工作区也有独立备份。

Docker 更适合以下条件：

  • 只允许 Agent 访问一个或几个指定项目目录；
  • 需要把设置、会话和项目文件分开管理；
  • 希望团队成员使用接近一致的启动参数；
  • 需要在执行前确认读写挂载，而不是把整个主目录暴露出去。

要特别注意“挂载目录”这条边界。容器能看到什么，主要取决于你传入的 -v 或 --mount 参数；没有挂载的主机目录不会因为 Canvas 页面能打开就自动对 Agent 可见。Docker 官方也将卷和绑定挂载区分为不同的数据管理方式，团队应把项目目录、配置目录和临时目录分别规划。 Docker 卷存储文档

⚠️ 容器边界不等于完整租户隔离。Docker 套接字、--privileged、过宽的读写挂载、共享密钥和开放网络，都可能显著削弱隔离效果。

如果项目包含 .env、云平台密钥、签名证书或客户数据，最稳妥的做法不是“提醒 Agent 不要读取”，而是从工作区和挂载清单中移除这些文件。对需要访问私有仓库的任务，应使用专门的低权限凭据，并在任务结束后撤销或轮换。

Docker：可重复启动与验收步骤

使用 Docker 时，Agent、Agent Server、Automation Server 和 Canvas 相关服务可以在容器中运行。官方示例使用 8000 端口，并把设置目录和项目目录分别挂载到容器内。 Docker 官方 Agent Canvas 指南

macOS 或 Linux 可以从一个干净目录开始：

mkdir -p ~/projects ~/.openhands

docker run -it --rm \
  -p 8000:8000 \
  -v ~/.openhands:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

然后访问：

http://localhost:8000/canvas

Docker 方案不要只验证“网页能打开”，还要完成下面的验收：

  1. 执行 docker ps，确认容器处于运行状态。
  2. 在 Canvas 中检查活动后端是否指向 http://localhost:8000。
  3. 只在 ~/projects 中放入一个测试项目，确认 Agent 能读取该目录。
  4. 让 Agent 创建一个测试文件，再确认宿主机的 ~/projects 能看到它。
  5. 在容器内尝试访问未挂载目录，确认它没有被意外暴露。
  6. 停止容器，再用同一条命令启动；检查 ~/.openhands 中的设置和会话是否仍可用。
  7. 如果需要修改 Dockerfile 或运行 docker compose，重新评估权限。

Docker 的隐性成本是目录权限、镜像更新和网络配置。使用 latest 便于快速更新，但复现问题时不够稳定；团队环境应记录镜像标签、挂载清单、环境变量和模型配置。设置和会话放在 ~/.openhands 等持久化目录后，删除容器不会自动删除这些数据，但删除持久化目录则可能同时删除设置、密钥和历史记录。

不要为了让 Agent 在容器中继续管理 Docker，就轻易加入 --privileged 或挂载宿主机 Docker 套接字。Docker 官方安全文档指出，容器权限、守护进程访问和宿主机内核能力之间存在直接关系；一旦扩大权限，原本用于限制文件范围的容器方案可能变成新的高权限入口。 Docker 安全文档

Remote Backend：常驻运行与团队协作

当本地电脑会休眠、终端会退出，或者任务需要运行较长时间时，Remote Backend 的价值不在“安装更快”，而在于把活动后端从个人电脑移到持续在线的机器。Agent 在远程 VM、专用主机或远程 Mac 上运行，能访问的是该主机上的工作区、工具、密钥和网络；本地 Canvas 只是控制界面。

远程后端适合以下情况：

  • 任务需要在你合上笔记本后继续执行；
  • 你需要从多台电脑访问同一个任务状态；
  • 团队成员需要使用相同的依赖、工具和目录结构；
  • 本地电脑没有足够的 CPU、内存、磁盘或专用开发工具；
  • 任务必须运行 macOS 工具链，而当前电脑无法提供对应环境。

官方自托管文档建议，在远程主机上使用 --public 时设置 LOCAL_BACKEND_API_KEY，并在公网暴露前配置防火墙、认证和 TLS。服务可以先通过 SSH 隧道访问；如果直接提供浏览器访问，则至少限制开放端口和允许来源。 VM 自托管部署说明

一个合格的远程后端验收，至少包含：

  • 本地 Canvas 能通过后端 Base URL 连接；
  • API Key 错误时会被拒绝，而不是仍然允许执行任务；
  • Agent 的工作区位于远程主机，而非本地电脑；
  • 本地浏览器关闭后，远程任务仍能继续；
  • 重新打开 Canvas 后，可以看到后端保存的会话和任务状态；
  • 防火墙只开放必要端口，管理入口仍通过 SSH 或受控网络访问；
  • 远程主机上的密钥与本地用户密钥分开保存。

桌面版可以作为远程后端的客户端，前提是当前版本提供后端管理入口，并且团队后端能通过可达地址提供服务。你需要确认后端名称、Base URL、认证密钥、工作区路径和任务保存位置；仅仅把一个远程地址填入设置，并不能证明任务恢复、权限控制和多人并发都已经验收。

团队部署时要分开讨论三件事：

  • 共享界面：多人看到同一个 Canvas 页面或同一套入口；
  • 共享后端：多人连接同一个 Agent Server；
  • 共享执行环境：多人让 Agent 修改同一批目录、使用同一组密钥和工具。

这三者不能混为一谈。Linux 通用编译、测试和脚本任务可以放入通用 Linux 后端；需要 Xcode、Apple SDK、签名证书或 macOS 专属工具链的任务，应放入单独的远程 Mac 后端。需要 Mac 工具链时，可以参考 macOS 开发任务远程执行；如果只是浏览器访问远程桌面，则先确认 VNC 连接方式 是否满足你的操作流程。

安装方式的条件分支

按照下面的条件选择，通常比比较命令长度更可靠：

  • 若你只需要在当天完成一次最小试用，且不想安装 Node.js 与 uv，则选桌面预览版；否则回退到 npx。
  • 若你希望以后反复使用同一个命令，且能接受本机权限，则选 npm 全局安装；否则继续使用 npx。
  • 若 Agent 要修改本地项目，而项目目录之外的文件不应可见，则选 Docker；否则可以使用本机后端，但必须先清理密钥和无关目录。
  • 若任务必须在终端关闭、电脑休眠或网络短暂变化后继续，则不要把本地 npm、npx 或桌面版当作常驻服务，改用 Remote Backend。
  • 若团队需要共享任务恢复、工具链和权限策略，则选远程后端；若只是共享一个临时界面，仍要为每个项目划分工作区和密钥。
  • 若任务必须运行 macOS 工具链，则不要因为 Linux 后端安装更简单就强行迁移，先确认远程 Mac 的系统版本、证书、SDK、网络和交互式登录条件。

截至 2026 年 9 月 6 日，官方发布说明显示 Agent Canvas 1.16.0继续围绕 Canvas 界面、模型设置、自动化和桌面安装体验迭代；桌面应用仍应按预览版对待，升级前保留当前配置和工作区记录。 Agent Canvas 1.16.0 发布说明

如果你只想试用，下一步应进入 SSHMac 帮助中心 按最小安装路径验证；如果你的重点是后台常驻，就转向远程后端部署；如果涉及 Apple 工具链，则先检查远程 Mac 的系统条件、证书和交互式工具是否齐全。

从当前方案迁移到 Mac 方案时，真正需要比较的不是“本地还是远程”四个字，而是执行环境是否匹配。Windows 或 Linux 本机方案可能受休眠、WSL、容器权限和 Apple 工具缺失影响；通用云主机虽然容易常驻，但无法直接提供 macOS 专属 SDK、Xcode 和签名链；本地桌面版则会把任务恢复和网络稳定性绑定到你的电脑。

若任务需要临时 Mac 算力、跨设备访问或验证 Apple 工具链，租赁 SSHMac 的远程 Mac 环境通常比长期改造本地方案更省事；但如果你要全年稳定运行高负载任务，或必须接入物理设备与本地 USB，购买并自管设备仍然更合适。