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

先记住一句话：Paseo 只编排、不自带 Agent。 它管理的是你已经装好的编程 Agent，本身不包含任何模型或编码能力。所以第一步是确认你已经有可用的 Agent CLI。

本教程目录

  1. 前置条件
  2. 安装 Paseo
  3. 配对客户端（手机扫码）
  4. 运行第一个 Agent 任务
  5. 管理与编排多个 Agent
  6. 远程 daemon 与自托管 relay
  7. 常见问题

步骤 1前置条件

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

怎么验证 Agent CLI 是否可用？ 按对应 Agent CLI 的官方方式确认它已安装并完成凭证登录、能正常使用。Paseo 后续会管理这些已安装的 Agent。

步骤 2安装 Paseo

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

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

方式 B：CLI / 无头服务器

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

npm install -g @getpaseo/cli
paseo

运行 paseo 后，终端会打印一个 QR 码，用于配对（见下一步）。

配置位于哪里？ Paseo 的本地配置和状态默认存放在 ~/.paseo，由环境变量 PASEO_HOME 控制，可自定义到其它路径。

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

Paseo 把 Agent 跑在你的机器上，再通过客户端远程操控。配对方式：

支持的客户端：iOS、Android、桌面、Web、CLI。Paseo 也支持语音控制。

步骤 4运行第一个 Agent 任务

用 paseo run 启动一个编程 Agent 任务，--provider 指定用哪个 Agent 和模型：

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

想为任务指定一个 git worktree，加 --worktree：

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

可按官方示例为不同任务分别指定各自的 --worktree。worktree 相关的编排功能官方建议配合 gh 使用。

步骤 5管理与编排多个 Agent

启动多个任务后，用以下命令统一管理：

paseo ls                            # 列出所有运行中的 Agent
paseo attach abc123                 # 实时查看某个 Agent 的输出流
paseo send abc123 "also add tests"  # 给运行中的 Agent 追加指令

典型编排玩法：一个任务用 claude/opus-4.6 写主功能、另一个用 codex/gpt-5.4 在独立 worktree 写另一个特性，paseo ls 总览全局，需要补充需求时 paseo send 直接下发——多个编程 Agent 像一个团队一样并行干活。

步骤 6远程 daemon 与自托管 relay

想从另一台机器连到你的 Paseo daemon（比如本地控制工作站）：

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

如果需要带 TLS 的远程连通（自托管中继），用环境变量配置后启动 daemon：

PASEO_RELAY_ENDPOINT=127.0.0.1:8080 \
PASEO_RELAY_PUBLIC_ENDPOINT=relay.example.com:443 \
PASEO_RELAY_USE_TLS=true \
paseo daemon start
Paseo 支持自托管且无遥测，relay 中继也可以自托管。（注意：Paseo 编排的 Claude Code / Codex 等 Agent 本身仍会按各自方式与对应模型服务通信。）

常见问题

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 多端都能控制，也支持语音控制。

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

本教程不覆盖各 provider 的具体配置、语音启用步骤或故障排查；这些请以 Paseo 官方文档（paseo.sh/docs）和各 Agent 自己的官方文档为准。

本教程基于 Paseo 官方公开材料（GitHub: getpaseo/paseo 与 paseo.sh/docs）整理，命令与配置以官方文档为准。Paseo 持续迭代，若命令有变化请以官方最新文档为准。本页由 NGJOO AI 实验室编写，2026-05-26 更新。