Paseo 使用指南

Paseo 是一个多 AI 编程 Agent 编排工具，让你在桌面、手机、Web 和 CLI 上统一管理 Claude Code、Codex、Copilot、OpenCode 等 Agent。
官网：https://paseo.sh | GitHub：https://github.com/getpaseo/paseo（11k+ Stars）

一、Paseo 是什么

核心理念

Paseo 不提供自己的 Agent。它运行一个本地守护进程（daemon），管理你已安装的 Agent CLI，通过统一界面跨设备操控。

┌─────────────────────────────────────────────────────────┐
│                    Paseo Daemon                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  守护进程：Agent 生命周期管理                       │   │
│  │  WebSocket API + MCP Server + 反向代理             │   │
│  └──────────┬──────────┬──────────┬──────────────────┘   │
│             │          │          │                        │
│     ┌───────┴──┐  ┌───┴────┐  ┌──┴────────┐              │
│     │ Claude   │  │ Codex  │  │ OpenCode  │  ...          │
│     │ Code     │  │        │  │           │                │
│     └──────────┘  └────────┘  └───────────┘               │
└─────────────────────────────────────────────────────────┘
         │              │              │
    ┌────┴────┐   ┌────┴────┐   ┌────┴────┐
    │ Desktop │   │ Mobile  │   │  CLI    │
    │  App    │   │ iOS/And │   │         │
    └─────────┘   └─────────┘   └─────────┘

核心特性

特性	说明
多 Provider	同一界面管理 Claude Code、Codex、Copilot、OpenCode、Pi、Cursor、Gemini 等
跨设备	桌面开工 → 手机查看进度 → CLI 脚本化，全设备覆盖
自托管	Agent 在你本地机器上运行，使用你的工具、配置和技能
语音控制	口述任务或语音讨论问题，免手动操作
隐私优先	无遥测、无追踪、无强制登录
编排能力	Agent 可以跨 Provider 创建子 Agent，实现规划+实现+审查分离

支持的 Agent（Provider）

原生支持：Claude Code、Codex、OpenCode、Pi
ACP 目录：Cursor、Gemini、GitHub Copilot、Hermes、Kimi、Qwen Code 等 25+ 种
自定义：任意 ACP（Agent Client Protocol）兼容 Agent

二、安装

前置条件

至少安装一个 Agent CLI 并完成认证：

还需要 GitHub CLI (gh) 安装并认证，Paseo 用它做 PR-aware worktrees。

方式一：桌面 App（推荐）

从 paseo.sh/download 或 GitHub Releases 下载安装包。打开 App，守护进程自动启动。

手机连接：打开 Settings → your host → Connections → Pair a device，扫码即可。

方式二：CLI / 无头模式

bash

npm install -g @getpaseo/cli
paseo

终端会显示一个二维码，用手机 App 扫码或手动输入守护进程地址连接。

方式三：Docker

bash

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

启动后访问 http://localhost:6767。需要在镜像中扩展安装 Agent CLI。

三、CLI 快速上手

运行 Agent

bash

# 启动一个 Agent 执行任务
paseo run "修复测试"

# 指定 Provider 和模型
paseo run --provider claude/opus-4.6 "实现用户认证"

# 后台运行
paseo run --background "运行测试套件"

# 使用 Git worktree 隔离
paseo run --isolation worktree --base main "实现 feature X"

# 指定输出 JSON Schema
paseo run --output-schema schema.json "提取发布说明"

管理 Agent

bash

paseo ls                    # 列出当前目录运行中的 Agent
paseo ls -a                 # 包含已完成的
paseo ls -g                 # 所有目录
paseo ls -a -g --json       # JSON 格式输出

paseo attach abc123         # 实时流式输出（Ctrl+C 分离）
paseo send abc123 "再加测试" # 发送跟进任务
paseo logs abc123           # 查看日志
paseo logs abc123 -f        # 流式日志
paseo logs abc123 --tail 10 # 最后 10 条
paseo logs abc123 --filter tools  # 只看工具调用
paseo stop abc123           # 停止 Agent
paseo wait abc123           # 等待完成
paseo wait abc123 --timeout 60  # 60 秒超时

工作区管理

bash

# 创建工作区
paseo workspace create --isolation local --path ~/dev/my-app --title main

# 创建 Git worktree 隔离工作区
paseo workspace create \
  --isolation worktree \
  --mode branch-off \
  --new-branch feature/auth \
  --base main

# 列出工作区
paseo workspace ls

# 在指定工作区运行 Agent
paseo run --workspace <workspace-id> "实现认证"

# 归档工作区
paseo workspace archive <workspace-id>

守护进程管理

bash

paseo daemon start              # 启动守护进程
paseo daemon start --web-ui     # 启动并开启 Web UI
paseo daemon status             # 查看状态
paseo daemon stop               # 停止
paseo daemon set-password       # 设置密码
paseo daemon pair --json        # 获取配对 URL

权限管理

bash

paseo permit ls                # 列出待审批
paseo permit allow <id>        # 批准
paseo permit deny <id> --all   # 拒绝全部

定时任务（Schedules）

bash

paseo schedule create --every 30m --cwd ~/dev/my-app "继续重构并留下说明"
paseo schedule ls
paseo schedule pause <id>

输出格式

bash

paseo ls --json          # JSON
paseo ls --format yaml   # YAML
paseo ls -q              # 仅 ID（静默模式）

四、Agent 编排与跨 Provider 工作流

核心概念：Native Subagent vs Paseo Subagent

Paseo 最核心的能力：让一个 Agent 跨 Provider 创建和管理其他 Agent。

维度	Native Subagent	Paseo Subagent
Provider	同父 Agent 的 Provider	Paseo 中配置的任意 Provider
工作目录	父 Provider 管理	当前工作区或指定工作区
生命周期	父 Provider 拥有	Paseo 管理，可接收跟进任务
查看方式	Subagents 面板（只读时间线）	完整 Agent 会话
适用场景	快速同级委托	跨 Provider 工作 + 精细工作区控制

# 跨 Provider 编排示例
Claude Code (Fable 5)  →  Codex (GPT-5.6)
Codex (GPT-5.6)        →  Grok Build
Cursor                 →  Claude Code (Fable 5)

启用编排

Settings → your host → Agents → 开启 Enable Paseo tools。然后重启 Agent 使其加载工具。

编排工作流

1. 委托给不同模型

Stay as the orchestrator. Use Paseo to find the available Codex 5.6 model, then
create a worktree-isolated workspace and launch a subagent there. Ask it to
implement the parser change and run the focused tests.

2. 并行研究（只读，共享工作区）

Create three Paseo subagents in this workspace. Have one trace the request path,
one inspect the tests, and one look for related regressions. Do not edit files.
Synthesize their findings when all three report back.

3. 并行实现（隔离工作区，无冲突）

Split these two issues between two Paseo subagents. Create a separate workspace
with worktree isolation from main for each issue, use the best available
implementation model, and have each agent run the focused checks for its change.
Summarize both diffs when done.

4. 实现 + 审查（不同模型，不同角色）

Create a worktree-isolated workspace and launch a worker there to implement this
feature. When it finishes, create a second subagent in the same workspace to
review the diff for correctness, missing tests, and unnecessary complexity.
Bring the review back here.

5. 心跳任务（持续工作直到条件满足）

Use Paseo to create a heartbeat every 10 minutes. Keep checking this PR, fix any
new CI failures, and stop when all checks pass or after two hours.

五、Orchestration Skills 技能包

Paseo 自带编排技能，让 Agent 学会使用 Paseo CLI 来管理其他 Agent。

安装

bash

# 方式一：手动安装
npx skills add getpaseo/paseo

# 方式二：桌面 App → Settings → Integrations → Install

技能列表

技能	命令	用途
Paseo Reference	`/paseo`	基础技能，其他技能依赖。告诉 Agent 如何使用 Paseo CLI
Task Handoff	`/paseo-handoff`	将当前任务连同完整上下文移交给另一个 Agent
Iterative Loops	`/paseo-loop`	循环执行直到条件满足（worker/verifier 模式）
Committee Planning	`/paseo-committee`	两个高推理 Agent 组成委员会，做根因分析和计划
Advisor	`/paseo-advisor`	启动一个 Agent 作为顾问，提供第二意见（只读）

使用示例

/paseo-handoff hand off the auth fix to codex in a worktree-isolated workspace

/paseo-loop keep trying until the changed test file passes, max 5 iterations

/paseo-committee why are the websocket connections dropping under load?

/paseo-advisor did I miss anything in this migration plan?

六、Git Worktree 隔离工作区

为什么需要 Worktree

多个 Agent 并行修改同一仓库时，Worktree 让每个 Agent 在独立分支的独立目录中工作，互不干扰。

~/.paseo/worktrees/
└── 1vnnm9k3/               # 源码路径哈希
    ├── tidy-fox/           # worktree slug
    └── bold-owl/           # 另一个 worktree

创建工作区

bash

# 从 main 分支分出新分支
paseo workspace create \
  --isolation worktree \
  --mode branch-off \
  --new-branch feature/auth \
  --worktree-slug feature-auth \
  --base main

# 检出已有分支
paseo workspace create \
  --isolation worktree \
  --mode checkout-branch \
  --branch feature/existing \
  --worktree-slug existing-copy

# 基于 PR 创建工作区
paseo workspace create \
  --isolation worktree \
  --mode checkout-pr \
  --pr-number 2186

paseo.json 项目配置

在项目根目录创建 paseo.json，Paseo 会读取 base 分支的已提交版本：

json

{
  "worktree": {
    "setup": "npm ci\ncp \"$PASEO_SOURCE_CHECKOUT_PATH/.env\" .env\ndb:migrate",
    "teardown": "rm -rf .cache"
  },
  "scripts": {
    "test": { "command": "npm test" },
    "lint": { "command": "npm run lint" },
    "web": {
      "type": "service",
      "command": "npm run dev -- --port $PASEO_PORT",
      "port": 3000
    }
  }
}

Setup/Teardown：setup 在 worktree 创建后执行一次（安装依赖、复制配置）；teardown 在归档时执行。

Services：标记为 "type": "service" 的脚本作为长期进程运行，Paseo 分配端口并通过反向代理路由：

http://<script>--<branch>--<project>.localhost:<daemon-port>
http://web--my-app.localhost:6767

环境变量：

变量	说明
`$PASEO_SOURCE_CHECKOUT_PATH`	原始仓库根目录
`$PASEO_WORKTREE_PATH`	Worktree 目录
`$PASEO_BRANCH_NAME`	分支名
`$PASEO_PORT`	当前服务端口
`$PASEO_URL`	当前服务代理 URL
`$PASEO_SERVICE_<NAME>_PORT`	同级服务端口
`$PASEO_SERVICE_<NAME>_URL`	同级服务代理 URL

七、配置参考

配置文件位置

~/.paseo/config.json

可通过 PASEO_HOME 环境变量或 --home 参数修改。

优先级

默认值 → 2. config.json → 3. 环境变量 → 4. CLI 参数（列表类型追加合并）

完整配置示例

json

{
  "$schema": "https://paseo.sh/schemas/paseo.config.v1.json",
  "version": 1,
  "daemon": {
    "listen": "127.0.0.1:6767",
    "hostnames": ["localhost", ".localhost"],
    "mcp": { "enabled": true },
    "auth": {
      "password": "$2b$12$..."
    }
  },
  "worktrees": {
    "root": "/mnt/fast/paseo-worktrees",
    "servicePorts": { "range": "3000-4000" }
  },
  "features": {
    "webUi": { "enabled": true }
  },
  "log": {
    "console": { "level": "info", "format": "pretty" },
    "file": {
      "level": "trace",
      "path": "daemon.log",
      "rotate": { "maxSize": "10m", "maxFiles": 2 }
    }
  }
}

常用环境变量

变量	说明
`PASEO_HOME`	Paseo 主目录
`PASEO_PASSWORD`	守护进程密码（明文，启动时自动哈希）
`PASEO_LISTEN`	覆盖 `daemon.listen`
`PASEO_HOSTNAMES`	覆盖/扩展 `daemon.hostnames`
`PASEO_WEB_UI_ENABLED`	启用 Web UI
`PASEO_LOG_CONSOLE_LEVEL`	控制台日志级别
`OPENAI_API_KEY`	覆盖 OpenAI Provider Key
`PASEO_VOICE_LLM_PROVIDER`	语音 LLM Provider（claude/codex/opencode）

八、Docker 部署

完整部署示例：

bash

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

注意：基础镜像不包含 Agent CLI。需要扩展镜像安装你需要的 Agent：

dockerfile

FROM ghcr.io/getpaseo/paseo:latest

# 安装 Claude Code
RUN npm install -g @anthropic-ai/claude-code

# 安装 GitHub CLI
RUN apt-get update && apt-get install -y gh

启动后访问 http://localhost:6767 打开 Web UI。

九、远程连接

Paseo 支持通过 Relay 服务进行端到端加密的远程连接。

获取配对 URL

bash

paseo daemon pair --json
# 输出: { "url": "https://app.paseo.sh/#offer=eyJ2IjoyLC...", "qr": "..." }

从远程连接

bash

# 使用配对 URL 连接
paseo ls --host 'https://app.paseo.sh/#offer=eyJ2IjoyLC...'
paseo run --host "$OFFER_URL" "修复失败的测试"

# 或设置环境变量持久化
export PASEO_HOST="https://app.paseo.sh/#offer=eyJ2IjoyLC..."
paseo ls

直接连接

bash

# TCP 直连（需密码）
paseo --host "tcp://192.168.1.10:6767?password=my-secret" ls

# 或通过环境变量
export PASEO_PASSWORD=my-secret
paseo --host 192.168.1.10:6767 ls

社区项目

paseo-relay — 自托管 Relay（Go 实现）
paseo-vscode — VS Code 扩展

十、常见工作流模板

个人开发

bash

# 启动 Agent 实现功能
paseo run --isolation worktree --base main "实现用户认证模块"

# 手机查看进度（扫码配对后）
paseo ls -g --json

# 下班后让 Agent 继续工作
paseo schedule create --every 30m --cwd ~/dev/my-app "继续重构，每步提交"

团队协作

bash

# 基于 PR 创建工作区审查
paseo workspace create --isolation worktree --mode checkout-pr --pr-number 42

# 派 Agent 审查
paseo run --workspace <workspace-id> --provider claude/opus "审查这个 PR 的代码质量"

CI/CD 集成

bash

# 在 CI 脚本中使用
paseo run --provider codex "修复 CI 失败的测试"
paseo wait <agent-id>
paseo logs <agent-id> --tail 10

多模型编排

# 在 Agent 对话中使用
Stay as the orchestrator.
1. Use Paseo to find available models
2. Create a worktree-isolated workspace from main
3. Launch a Codex subagent to implement the feature
4. When done, launch a Claude subagent to review
5. Bring the review back here

十一、架构与包结构

单体仓库结构

getpaseo/paseo/
├── packages/
│   ├── server/       # 守护进程：Agent 生命周期、WebSocket API、MCP Server
│   ├── app/          # Expo 客户端（iOS、Android、Web）
│   ├── cli/          # Docker 风格 CLI（paseo run/ls/logs/wait）
│   ├── desktop/      # Electron 桌面 App
│   ├── relay/        # 端到端加密 Relay 远程连接
│   └── website/      # 营销站点和文档（paseo.sh）
├── docs/             # 文档
├── public-docs/      # 公开文档（Skills 等）
└── CLAUDE.md         # 项目级 AI 指令

开发命令

bash

# 克隆仓库
git clone https://github.com/getpaseo/paseo.git
cd paseo

# 运行所有本地开发服务
npm run dev

# 单独运行某个模块
npm run dev:server
npm run dev:app
npm run dev:desktop
npm run dev:website

# 构建
npm run build:server

# 类型检查
npm run typecheck

参考资源

官网：https://paseo.sh
GitHub：https://github.com/getpaseo/paseo
文档：https://paseo.sh/docs
CLI 参考：https://paseo.sh/docs/cli
Provider 配置：https://paseo.sh/docs/providers
编排指南：https://paseo.sh/docs/orchestration
Discord 社区：https://discord.gg/jz8T2uahpH
Reddit：https://www.reddit.com/r/PaseoAI/
X (Twitter)：https://x.com/moboudra
Agent Client Protocol：https://agentclientprotocol.com/

Paseo 使用指南 ​

目录 ​

一、Paseo 是什么 ​

核心理念 ​

核心特性 ​

支持的 Agent（Provider） ​

二、安装 ​

前置条件 ​

方式一：桌面 App（推荐） ​

方式二：CLI / 无头模式 ​

方式三：Docker ​

三、CLI 快速上手 ​

运行 Agent ​

管理 Agent ​

工作区管理 ​

守护进程管理 ​

权限管理 ​

定时任务（Schedules） ​

输出格式 ​

四、Agent 编排与跨 Provider 工作流 ​

核心概念：Native Subagent vs Paseo Subagent ​

启用编排 ​

编排工作流 ​

五、Orchestration Skills 技能包 ​

安装 ​

技能列表 ​

使用示例 ​

六、Git Worktree 隔离工作区 ​

为什么需要 Worktree ​

创建工作区 ​

paseo.json 项目配置 ​

七、配置参考 ​

配置文件位置 ​

优先级 ​

完整配置示例 ​

常用环境变量 ​

八、Docker 部署 ​

九、远程连接 ​

获取配对 URL ​

从远程连接 ​

直接连接 ​

社区项目 ​

十、常见工作流模板 ​

个人开发 ​

团队协作 ​

CI/CD 集成 ​

多模型编排 ​

十一、架构与包结构 ​

单体仓库结构 ​

开发命令 ​

参考资源 ​

Paseo 使用指南

目录

一、Paseo 是什么

核心理念

核心特性

支持的 Agent（Provider）

二、安装

前置条件

方式一：桌面 App（推荐）

方式二：CLI / 无头模式

方式三：Docker

三、CLI 快速上手

运行 Agent

管理 Agent

工作区管理

守护进程管理

权限管理

定时任务（Schedules）

输出格式

四、Agent 编排与跨 Provider 工作流

核心概念：Native Subagent vs Paseo Subagent

启用编排

编排工作流

五、Orchestration Skills 技能包

安装

技能列表

使用示例

六、Git Worktree 隔离工作区

为什么需要 Worktree

创建工作区

paseo.json 项目配置

七、配置参考

配置文件位置

优先级

完整配置示例

常用环境变量

八、Docker 部署

九、远程连接

获取配对 URL

从远程连接

直接连接

社区项目

十、常见工作流模板

个人开发

团队协作

CI/CD 集成

多模型编排

十一、架构与包结构

单体仓库结构

开发命令

参考资源