Paseo：跨设备编排多个编码智能体

Paseo 把多个编码智能体收到同一套界面下调度。它的做法是在你的机器上跑一个本地服务，官方叫 daemon，由 daemon 负责启动和管理 Claude Code、Codex、Copilot、OpenCode、Pi 这几类命令行智能体进程，桌面应用、手机应用、网页端和终端 CLI 作为客户端连到 daemon 上操作。

Paseo 是 TypeScript 写的自托管多智能体编排工具，在本机 daemon 上并行拉起 Claude Code、Codex 等编码 CLI，通过桌面、手机、网页或终端统一操作。

典型的用法是：手头有好几个互不相干的改动要并行推进；在工位起了一个任务，出门后用手机看进度、补一句需求；或者把重复性的巡检写进脚本，从终端批量投给不同的智能体。项目主页在 paseo.sh，仓库地址 https://github.com/getpaseo/paseo，主要语言 TypeScript，占比 98.0%。GitHub 元数据把许可证标成 Other（NOASSERTION），README 的 License 一节写的是 Apache-2.0，两者不一致的原因见下文。

仓库当前 Star 数 18559，Fork 2132，Watcher 54，开放 Issue 904 个。创建于 2025-10-13，最近一次提交在 2026-09-25，最新版本 v0.9.2（2026-09-24）。版本号还在 0.x，迭代节奏很快，从 v0.9.0 到 v0.9.2 只隔了两天。

基础用法

安装与依赖

前置条件只有一条：本机至少要装好并配置好其中一种智能体 CLI，包括 Claude Code、Codex、GitHub Copilot、OpenCode、Pi。Paseo 自己不提供模型，它调度的是这些已经存在的命令行工具。

桌面版是官方推荐路径。从 paseo.sh/download 或 GitHub releases 页面下载安装，打开应用后 daemon 自动启动，不需要额外装别的东西。

在服务器或远程机器上走 CLI 路径：

npm install -g @getpaseo/cli
paseo

启动后它会问你是否启用端到端加密的 relay 用于设备配对。选择拒绝，就改为通过 TCP、Tailscale 或其他 VPN 直连。这条路径适合长期挂着的机器。

Docker 路径会同时跑起 daemon 和自托管的网页 UI：

docker run -d --name paseo \
  -p 6767:6767 \
  -e PASEO_PASSWORD=change-me \
  -v "$PWD/paseo-home:/home/paseo" \
  -v "$PWD:/workspace" \
  ghcr.io/getpaseo/paseo:latest

基础镜像里不含智能体 CLI，需要自己扩展镜像，再通过环境变量或持久化的 /home/paseo 卷提供凭据。README 里只说了「扩展基础镜像」这件事，具体怎么扩指向 docs/docker.md。

最短能跑通的示例

从终端投一个任务给 Claude：

paseo run --provider claude/opus-4.6 "implement user authentication"

换成 Codex 并指定 worktree：

paseo run --provider codex/gpt-5.5 --worktree feature-x "implement feature X"

如果 daemon 跑在别的机器上，加 --host，注意 --cwd 指的是那台机器上的路径：

paseo run --host workstation.local:6767 --cwd /workspace "run the full test suite"

仓库里没有给出 --provider 的完整取值列表，只在示例里出现了 claude/opus-4.6 和 codex/gpt-5.5 两种写法，其余组合要自己看 CLI 文档。

确认它跑起来了

用 paseo ls 看当前有哪些 agent 在运行，用 attach 接上某个会话看实时输出，用 send 追加后续任务。

paseo ls                           # list running agents
paseo attach abc123                # stream live output
paseo send abc123 "also add tests" # follow-up task

Docker 方式启动后，浏览器打开 http://localhost:6767 就能看到自托管网页 UI。桌面端要连手机的话，进 Settings → your host → Pair Device 配对。判断一次运行是否正常，看 daemon 进程有没有起来、paseo ls 里能不能列出刚投出去的那个 agent，两样都满足就算通了。

主要功能

多智能体编排与运行

• 多 provider 接入。在同一套界面里调用 Claude Code、Codex、Copilot、OpenCode、Pi，每个任务可以单独挑 provider 和模型。用法就是 paseo run --provider claude/opus-4.6 这类写法。限制在于这些 CLI 必须提前装好并配好凭据，Paseo 不代管凭据。
• 并行运行与 worktree 隔离。用 --worktree feature-x 给任务分配独立的 git worktree，多个 agent 同时改同一个仓库时互不干扰。仓库里没有说明 worktree 的清理策略，长期使用要留意磁盘上的残留目录。
• 远程 daemon。通过 --host workstation.local:6767 把任务投到另一台机器的 daemon 上执行，--cwd 指定那台机器上的工作目录。适合开发机放家里、人在外面用笔记本或手机操作的情况。
• 跨设备客户端。桌面应用、iOS、Android、网页、CLI 五类入口连的是同一个 daemon，工位上开了任务，走开之后可以从手机接手。移动端需要先做设备配对，配对的路径是 relay 或自建 VPN，两者都要额外配置。
• 语音控制。README 提到可以口述任务或在 voice mode 里讨论问题。仓库里没有说明语音走的是哪个服务、是否需要额外授权。

扩展与集成

• 插件。用 TypeScript 写插件给 Paseo 加主题、工作区面板、命令、设置界面和新的 agent provider，安装命令是 paseo plugin install <source>，来源支持 npm、Git 和本地目录。官方在 README 里明确写了插件运行时可访问 daemon 所在的机器以及已连接的客户端，只能装你信任的代码。这一条是硬限制，不是提示。
• TypeScript SDK。用 @getpaseo/client 把 Paseo 接进自己的脚本或服务，比如做 issue 集成、看板或者编排服务。初始化方式是 createPaseoClient({ url: "ws://127.0.0.1:6767/ws" })，连接后调 client.agents.create 建 agent，再用 agent.waitForFinish() 拿最后一条消息。走的是 WebSocket 接口。
• Skills。执行 npx skills add getpaseo/paseo 之后，可以在任意 agent 会话里用 /paseo-handoff 把工作从一个 agent 交接给另一个，用 /paseo-advisor 拉一个 agent 当顾问做二次判断，用 /paseo-committee 组两个立场不同的 agent 做根因分析和出方案。这三个技能是给 agent 自己用的，用途是让它们去编排别的 agent。

参数与配置

常用参数

CLI 侧最常打交道的四个参数是 --provider（选 provider 和模型）、--worktree（给任务分独立 worktree）、--host（指定远端 daemon 地址和端口）、--cwd（指定远端机器上的工作目录）。子命令上，run 投任务、ls 列运行中的 agent、attach 接上会话看输出、send 追加任务。

Docker 侧的三个参数分别是 -p 6767:6767 暴露 daemon 端口、-e PASEO_PASSWORD 设置访问密码、-v 挂载 paseo-home 和 workspace 两个目录。密码示例里写的是 change-me，实际部署要改掉，端口 6767 直接映射到宿主机也意味着同一网络内谁都能访问，需要靠密码和网络隔离兜住。

配置文件

仓库根目录里有一个 paseo.json，大小 1.7 KB。README 没有展开这个文件有哪些字段，只在文档链接里给了 paseo.sh/docs/configuration 作为配置参考。

Docker 部署下持久化靠 /home/paseo 卷，凭据可以走这个卷，也可以走环境变量。仓库里没有说明这两条路径的优先级，也没说明配置文件和各环境变量的对应关系。项目自述里写了不带遥测、不带追踪、不强制登录，实际部署中需要自己确认 daemon 的对外暴露范围。

实际使用中的坑

许可证问题已经处理完，但留下一个容易踩的坑。Issue 里记录了把 Paseo 从 AGPL-3.0-or-later 重新授权为 Apache-2.0 的过程，讨论有 122 条评论、15 个 reaction。README 的 License 一节现在写 Apache-2.0，但 GitHub 元数据里这个仓库的许可证字段仍然显示 Other（NOASSERTION）。公司内部走合规审查时，别只看仓库首页那一栏，要打开 LICENSE 文件（11.4 KB）核对最终文本。

开放 Issue 有 904 个，对比 18559 个 Star 是偏高的比例。项目自述里写着由一个人开发、靠使用者赞助维持。这个数字说明积压的提交可能不少，遇到问题不一定能很快拿到回复。这一段是从仓库结构推断，不是实测结论。

插件的权限模型需要提前想清楚。官方文档写明插件运行时可以访问 daemon 机器，也可以在已连接的客户端里运行，还专门加了一句只安装你信任的代码。第三方插件没有沙箱隔离，装上就等于把 daemon 所在的机器交出去一部分。

Docker 基础镜像只跑 daemon 和网页 UI，不含任何智能体 CLI。想让容器里的 daemon 拉起 Claude Code 或 Codex，你得先自己扩展镜像并在容器里完成这些 CLI 的登录。README 只说了「扩展基础镜像」这一句，扩展示例和凭据注入方式指向 docs/docker.md。

同类项目对比

如果你的使用场景全部发生在桌面，不需要手机端或网页端跟进，去装 Paseo 的收益不大。桌面形态的同类项目在配置上更省事，你不用先跑一个 daemon、再想清楚端口和密码怎么暴露，也不用为设备配对去配 relay 或 VPN。Paseo 换来跨设备能力的代价，就是这套必须自己维护的服务端结构，单机桌面场景里它是净负担。

适合谁

已经在用 Claude Code 或 Codex、手头常有多个并行改动、并且希望从手机或另一台机器跟进的开发者，适合用 Paseo。愿意自己跑一个本地服务、自己管凭据和镜像的人，也适合。用不上跨设备能力、只想在桌面上跑单个 agent 的人，用 Paseo 属于多此一举。不愿意维护自托管服务、希望打开就能用的人，应该先看纯桌面形态的编排工具。