用 Paseo 把编码 Agent 从一个终端里解放出来：上手教程

一句话

Paseo 是一个本地运行的编码 Agent 调度器：它不自带 AI，而是接管你已经装好的 Agent CLI（Claude Code、Codex 等），让你用命令行、桌面、网页、手机四种客户端从任何地方驱动它们。

它解决什么

你直接跑 claude 或 codex 的时候，Agent 的命被绑在启动它的那个终端上。任务要跑二十分钟，你就不敢合上笔记本。人离开工位，就只能回来再看结果。更难受的是并行——你想让一个 Agent 改后端、另一个写测试，于是开两个终端，结果它俩在同一个工作目录里同时改文件，互相把对方的改动盖掉。

大多数人的应对办法很朴素：一次只跑一个，守着。或者专门腾一台机器，盖子开着，人肉值守。

Paseo 把这套搬进一个常驻后台服务。Agent 还是那个 Agent，模型还是你自己的账号和额度，但它现在跑在 daemon 里，不再被某个终端拴住；每个 Agent 拿到一块独立的 git worktree，并行也不打架；你人在地铁上，掏出手机就能看它跑到哪了。

先建立心智模型：四个词

把 Paseo 想成机场塔台。飞机（Agent）是你自己买的，塔台不替你开；它的价值是让一个人在一块屏上看清所有航班、给每架飞机分独立跑道、并且不管你在不在驾驶舱都能指挥。

• Daemon（塔台本身）：常驻后台的服务，负责拉起和管理所有 Agent。它一直在，客户端断开也不影响 Agent 继续跑。
• Provider（飞机型号适配）：Paseo 和一个外部 Agent CLI 之间的「契约」——怎么启动它、怎么读它的输出、怎么把输入回传。Claude Code、Codex、OpenCode、pi 是原生支持，装好对应 CLI 就自动发现；Cursor、Gemini、Copilot、Qwen 等 25+ 通过 ACP 协议接入。Paseo 不内置模型，你装好底层 CLI，它来跑。
• Client（塔台的屏幕）：CLI、桌面 App、网页、手机，四种都连同一个 daemon。手机扫码配对后，就是你口袋里的监控台。
• Worktree（独立跑道）：每个 Agent 在自己的 git worktree 里干活，分支隔离、PR 感知，所以并行的几个 Agent 不会在同一份工作区里互相覆盖。

记住一条主线：daemon 在跑，providers 是你的飞机，clients 是你看它们的屏幕，worktrees 是防撞的跑道。

快速上手

前提：先装好至少一个 Agent CLI（比如 Claude Code），并确认它自己能正常登录、能跑。Paseo 只负责调度，登录和额度是底层 CLI 自己的事。要用 PR 相关功能，再装好 gh 并完成认证。

1. 装 Paseo

npm install -g @getpaseo/cli
paseo

第一次跑 paseo 会拉起 daemon，并在终端里打印一个二维码。桌面 App 用户从 paseo.sh/download 下载，首次启动会自动起 daemon，二维码在 Settings 里。

2. 手机配对

用 Paseo 手机 App 扫终端或 Settings 里的二维码，手机就连上了这台机器的 daemon。从此这台机器上跑的所有 Agent，手机上都看得到、管得了。

3. 确认 provider 被发现

只要底层 CLI 装好了，Paseo 会自动发现它。需要改默认行为、跑多个配置、或指向不同 endpoint，就编辑 ~/.paseo/config.json。

4. 派第一个 Agent

paseo run        # 起一个 Agent 并交给它一个任务
paseo ls         # 看当前在跑的 Agent
paseo attach     # 实时跟它的输出流

具体参数先跑 paseo run --help 看，不同 provider 的可选项不一样。

核心命令速查

这张表是你日常 90% 的操作。Paseo 的命令围绕「派活—盯进度—追加—收尾」四步设计：

命令	作用
paseo run	起一个 Agent 并下发任务
paseo ls	列出在跑的 Agent
paseo attach	实时查看某个 Agent 的输出
paseo send	给在跑或空闲的 Agent 追加任务
paseo logs	查看 Agent 的时间线
paseo wait	阻塞，直到 Agent 跑完当前任务
paseo stop	停掉一个 Agent
paseo permit ls / allow / deny	处理 Agent 申请的权限（列出 / 全允许 / 全拒绝）
paseo agent mode	切换 Agent 的运行模式
paseo daemon start / status / stop	管理 daemon
paseo daemon pair	生成配对链接，供远程客户端接入

全局选项：--host 连到另一台 daemon、--json 输出 JSON、-q 安静模式、--no-color 关颜色。其中 --host 是远程玩法的钥匙——下面就用到。

三个真实工作流

一、在手机上盯远程跑的长任务

机器上派活，人走开：

paseo run            # 派一个重构任务
# 合上笔记本，去开会

daemon 不归终端管，Agent 继续跑。手机 App 里能看到它的 timeline，跑到哪一步、卡在哪、要不要授权，一目了然。遇到它申请权限，直接在手机上 allow。

二、并行跑多个 Agent，用 worktree 防撞

这是 Paseo 比「开几个终端」强的地方。派几个 Agent 各干各的，每个在自己的 git worktree 里：一个改 feature-a 分支，一个改 feature-b，文件互不覆盖，最后各自对应一个 PR。

paseo run    # Agent A：写支付模块
paseo run    # Agent B：补测试
paseo ls     # 两个一起跑，各在各的跑道

直接开两个 claude 做不到这点——它俩会在同一个工作目录里打架。worktree 隔离的具体用法见 docs 的 Git worktrees 一节。

三、headless 部署在开发机上

daemon 能无界面跑在一台远程开发机或服务器上：

# 在开发机上
paseo daemon start
paseo daemon pair    # 拿到配对链接

# 在你的笔记本 / 手机上
paseo --host <开发机地址> ls

Agent 在算力足、网络好的机器上跑，你从任何客户端 attach 过去。笔记本关机也不影响。

几个坑和安全须知

• Paseo 不解决「连不连得上模型」。它驱动的 Claude Code、Codex 等多是海外服务，在中国大陆用，科学上网这一关还是底层 CLI 自己要过——Paseo 只管调度。
• 权限别全自动放行。Agent 会申请执行命令、改文件的权限。paseo permit 给了你统一的关卡，远程时尤其要管住，别让一个跑飞的 Agent 在你的机器上乱来。先看 docs 的 Security 一节再开远程。
• provider 登录是底层 CLI 的事。Paseo 发现不了 Agent，先回去确认那个 CLI 自己能独立跑通、凭证没过期。

下一步

跑通上手流程后，按需深入这几节官方文档：Providers / Supported providers（接更多 Agent）、Git worktrees（并行隔离的细节）、Schedules（定时任务）、Skills、Security（开远程前必读）。文档首页：paseo.sh/docs。