Paseo 使用教程：安装、配对与多 Agent 编排实战

Paseo 是一个开源的 AI 编程 Agent 统一控制台：它统一管理 Claude Code、Codex、GitHub Copilot、OpenCode、Pi 等编程 Agent，把它们跑在你自己的机器上，再通过手机、桌面、Web、CLI 多端远程控制和编排。本教程基于 Paseo 官方文档，手把手带你从安装到编排走一遍。

本次核对：2026-09-22，官方稳定版为 v0.8.0（2026-09-10 发布）；v0.9.0-beta.2 是预览版，本文不按预览版写法展开。下文依据当前官方文档和 v0.8.0 发布说明修订；不同版本的参数可能有差异，运行前可用 paseo --version 和 paseo run --help 核对本机选项。

步骤 1前置条件

使用 Paseo 前，确保以下条件满足：

• 至少一个 Agent CLI 已安装并登录：Claude Code、Codex、GitHub Copilot、OpenCode、Pi 任选其一（或多个）。先单独把它装好、确认能正常用自己的账号跑通——Paseo 不会替你配置它们的凭证。
• Node.js + npm：CLI 方式安装 Paseo 需要。
• 桌面版系统要求：v0.8.0 起 macOS 桌面端要求 macOS 13 或更高版本；Linux 和 Windows 的要求没有随该版本改变。
• GitHub CLI（gh，可选）：如需 worktree 编排功能，官方建议安装并认证 gh。

步骤 2安装 Paseo

方式 A：桌面版（推荐普通用户）

从 paseo.sh/download 或 GitHub Releases 下载桌面应用。打开后 daemon 会自动启动，安装本身不需要命令行。后续仍需完成配对（步骤 3），并确保已有可用的 Agent CLI（步骤 1）。

方式 B：CLI / 无头服务器

适合在远程开发机、服务器上跑：

npm install -g @getpaseo/cli
paseo

运行 paseo 后会先启动本地 daemon，再询问是否启用端到端加密 relay 并显示配对二维码。如果选择不启用，可通过 TCP、Tailscale 或其他 VPN 手动连接。

方式 C：Docker / 自托管 Web UI

官方提供 ghcr.io/getpaseo/paseo:latest 镜像，可同时运行 daemon 和 Web UI。以下示例在项目目录执行，将端口限定到本机访问；请先设置自己的强密码：

export PASEO_PASSWORD='替换为自己的强密码'
docker run -d --name paseo \
  -p 127.0.0.1:6767:6767 \
  -e PASEO_PASSWORD \
  -v "$PWD/paseo-home:/home/paseo" \
  -v "$PWD:/workspace" \
  ghcr.io/getpaseo/paseo:latest

启动后打开 http://localhost:6767。基础镜像不包含 Agent CLI，需要扩展镜像安装要用的 Agent，并配置凭证；主机上已经安装的 CLI 不会自动出现在容器中。完整部署方式见官方入门文档中的 Docker 入口。

步骤 3配对客户端（手机扫码）

Paseo 把 Agent 跑在你的机器上，再通过客户端远程操控。Relay 需要主动启用：

• 桌面版：打开 Settings → 选择你的 host → Pair a device，选择 Enable relay，再用手机 Paseo App 扫码。
• CLI：首次启动时确认启用 relay；之后也可运行以下命令，确认提示后显示二维码和配对链接。

paseo daemon pair

不方便扫码时，在手机 App 选择 Paste pairing link，粘贴配对链接。无需使用 relay 的用户，可通过 Tailscale 等方式直连，见步骤 6。具体流程见官方连接文档。

支持的客户端包括 iOS、Android、桌面、Web、CLI，也支持语音控制；语音配置见官方语音文档。

步骤 4运行第一个 Agent 任务

先在终端进入要操作的项目目录，再用 paseo run 启动任务。--provider 选择 Agent；也可以按官方 README 示例指定 provider/model，例如 claude/opus-4.6 或 codex/gpt-5.5，实际可用模型取决于 provider 和账号。

paseo run --provider codex "检查当前项目，说明目录结构与测试命令，暂不修改文件"

默认会等待任务完成。想立即返回终端、让 Agent 在后台继续运行，可加 --background。

当前 CLI 文档通过 workspace 参数创建独立 git worktree。以下示例要求当前目录是 Git 仓库、存在 origin/main，且新分支名尚未占用；请按自己的仓库调整：

paseo run --provider codex --background \
  --new-workspace worktree --worktree-mode branch-off \
  --new-branch feature/paseo-demo --base origin/main \
  "在独立分支实现一个小功能，并补充测试"

旧教程采用 README 中的 --worktree feature-x 简写；本节改用当前 CLI 参考中的明确参数。若本机不识别这些选项，先检查 paseo run --help 和版本，再参考下方升级说明。

步骤 5管理与编排多个 Agent

需要并行工作时，为每个任务使用不同分支的独立 worktree，并加 --background。沿用上节命令、替换分支名和任务描述即可创建另一个任务。

paseo ls                           # 当前目录中运行的 Agent
paseo ls -g                        # 跨目录查看运行的 Agent
paseo ls -a -g                     # 同时包含已完成或停止的 Agent
paseo attach abc123                # 实时查看输出，Ctrl+C 退出查看
paseo send abc123 "请补充测试"      # 给运行中或空闲的 Agent 追加任务
paseo logs abc123                  # 查看任务时间线
paseo stop abc123                  # 停止指定 Agent

将 abc123 替换为列表中实际的 Agent ID。一个 Agent 写功能，另一个在独立 worktree 处理其他任务；完成后仍需检查差异、运行测试并合并分支，独立 worktree 不会自动解决最终合并冲突。

步骤 6远程 daemon 与自托管 relay

通过 SSH 连接远程 daemon

先在远程主机安装并启动 Paseo，确认本机能使用密钥或 SSH agent 执行 ssh user@host。SSH 连接不会替你安装或启动远端 daemon。

paseo --host ssh://user@host ls -a
paseo --host ssh://user@host run --cwd /workspace/my-project "运行测试并报告结果"

v0.8.0 已将 --host 调整为全局 CLI 选项，所以要放在子命令前；--cwd 必须是远程主机上存在的项目目录。默认连接远端的 127.0.0.1:6767；SSH URL 中的端口是 SSH 端口，不是 daemon 端口。桌面端入口为 Settings → Add host → Remote SSH。

如果你从 0.7 版本升级并维护了自定义插件，请先查看官方的插件迁移说明；升级前不要把旧插件配置直接复制到新环境。

直连、Tailscale 与 relay

已有可访问的 daemon 地址时，可以通过 paseo --host workstation.local:6767 run --cwd /workspace/my-project "运行测试" 连接。Tailscale 方案需要手机与 daemon 主机加入同一 tailnet，并按连接文档配置监听地址和访问方式。

使用官方 relay 时，按步骤 3 启用即可，通信采用端到端加密。需要自托管 relay，可参考官方 relay 仓库；部署 relay 服务和让 daemon 指向该服务是两个步骤，仅设置客户端环境变量并不会部署中继。

常见问题

Paseo 自带 AI 编程能力吗？需要单独装 Claude Code 吗？

不自带。Paseo 是控制台，编排你已装好的编程 Agent。必须先安装并登录至少一个 Agent CLI（Claude Code / Codex / Copilot / OpenCode / Pi 之一）。

有不用命令行的安装方式吗？

有。桌面版从 paseo.sh/download 下载，打开后 daemon 自动启动、安装本身不需要命令行（仍需完成配对并装好 Agent CLI）。

配置文件在哪？

默认在 ~/.paseo（环境变量 PASEO_HOME 可改）。

能用手机控制吗？

能。扫码配对后，手机 / Web / 桌面 / CLI 多端都能控制，也支持语音控制。

为什么没有出现配对二维码？

Relay 默认未启用。运行 paseo daemon pair 并确认提示，或在桌面端 Pair a device 中启用 relay；也可以复制配对链接到手机 App。

Agent CLI 在终端能用，但 Paseo 找不到怎么办？

先确认 Agent 已独立登录成功，再运行 paseo provider diagnostic codex（按需换成 claude 等 provider），检查 daemon 实际使用的 PATH、可执行文件路径和状态。桌面端也可在 Settings → 你的 host → Providers → 对应 provider → Diagnostic 查看诊断。

如何升级 Paseo？

桌面端在 Settings → About 检查更新；Release channel 可选择 Stable 或 Beta，普通用户建议保持 Stable。CLI 可重新运行 npm install -g @getpaseo/cli 更新安装包；运行中的 daemon 可能仍使用旧进程，按安装方式完成重启前先处理好正在运行的任务。v0.8.0 升级后，macOS 桌面端至少需要 macOS 13；维护自定义插件的用户还要先看插件迁移说明。手机应用商店版本可能因审核晚于桌面和 CLI 发布，详见官方更新说明。

v0.8.0 的远程命令为什么和旧教程不一样？

v0.8.0 把 --host 改成全局选项，因此写成 paseo --host ssh://user@host run ...；如果把它放在 run 后面，本机可能提示参数不存在。升级后用 paseo --help 和 paseo run --help 重新确认选项。

每个 Agent provider 的详细配置在哪看？

请从Paseo 官方文档的 Providers 栏目进入对应配置页；Agent 的账号授权和模型可用性以各 Agent 自己的官方说明为准。