Paseo 是什么,这篇讲什么
Paseo 是一个开源的 agentic development environment(代理式开发环境):本地 daemon 统一管理你的编码代理,桌面、移动、Web、CLI 四端接入,Apache-2.0 协议、TypeScript monorepo,GitHub 约 2 万 star(2026-10 查询为 20,755),官网 paseo.sh;作者 Mohamed Boudra 在 README 自述一人开发、靠用户赞助维持、日活开发者数以万计。部署分三条路线——桌面 app、服务端 CLI、Docker 自托管——手机配对后,通勤路上也能给 coding agent 派活、看进度。这篇把三条路线的命令、参数解释、选型、安全与排错一次讲完,背景与定位见 Paseo 是什么。
部署前三问:在哪跑、怎么连、装什么
三个答案先给:daemon 跑在哪看算力归属;设备怎么连看网络环境;agent CLI 至少装一个并配好凭据,这是三条路线共同的前置条件。
一问:daemon 跑在哪。 Paseo 的架构是本地 daemon(packages/server)管理所有编码代理,对外提供 WebSocket API 与 MCP server;桌面(Electron)、移动(Expo 原生 iOS/Android)、Web、CLI 全都是客户端(README 架构说明)。所以”部署 Paseo”实际上是”部署 daemon”,位置三选一:本机桌面最省事,服务器或 VM 算力足、常在线,Docker 隔离干净、可迁移。
二问:设备之间怎么连。 daemon 启动时会问是否启用端到端加密的 relay——设备配对用的加密通道(README),手机要随时接入就启用,纯内网或 VPN 组网就拒绝,详细解释放在路线二。官方 relay 是独立项目 getpaseo/paseo-relay(Elixir 编写)。机器多、设备杂的场景可另看网关型方案(AgentDock 多设备编排)。
三问:agent CLI 装了没。 Paseo 不自带模型和代理,它是管理层——前置条件是至少装好一个编码代理 CLI 并配置凭据(README 原文),清单里有 Claude Code、Codex、Copilot、OpenCode、Pi、Antigravity、Muse Code。凭据没配,daemon 起来了也没活可干。
路线一:桌面 app,打开即起 daemon
这是 README 的推荐路径:下载、打开,两步完成。
- 从 paseo.sh/download 或 GitHub Releases 下载桌面 app;
- 打开即自动启动 daemon,无需其他安装(README 原文)。
Provider 在 Settings 里配置,手机接入也在这条路线内:Settings → your host → Pair Device(README 流程)。桌面路线适合主力开发机:界面、代理会话、终端在同一台机器,算力就是你的本机。
路线二:服务端安装,npm 一条命令起 daemon
服务器或 VM 上跑 daemon 走这条路:npm 全局安装 CLI,paseo 启动 daemon。
npm install -g @getpaseo/cli
paseo
启动时的 relay 询问这样理解:选启用,relay 成为设备配对通道,流量端到端加密——relay 只做传输与加密(monorepo 中的 packages/relay 即这一层),读不到会话内容;选拒绝,改走 TCP 直连、Tailscale 或其他 VPN(README 原文)。两条路都官方支持,按网络环境选即可。
路线三:Docker 自托管,一条 docker run
README 给的命令原样如下,一条起容器,浏览器开 http://localhost:6767 就是自托管的 Web 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
逐参数拆解:
| 参数 | 作用 | 注意点 |
|---|---|---|
-p 6767:6767 | 容器 6767 端口映射到宿主机 | 启动后开 http://localhost:6767 即 Web UI(README) |
-e PASEO_PASSWORD=change-me | 设置访问口令 | change-me 是占位符,务必换成强密码(占位为 README 原样,提醒为工程建议) |
-v "$PWD/paseo-home:/home/paseo" | 持久化 /home/paseo 卷 | 凭据可经环境变量或这个卷提供,容器重建不丢(README) |
-v "$PWD:/workspace" | 把当前目录挂载为工作区 | 容器里的代理就在这个目录里干活 |
ghcr.io/getpaseo/paseo:latest | 官方镜像 | 基础镜像可自行扩展装 agent CLI,完整细节在 docs/docker.md |
镜像里没有预装 agent CLI,要自己带进去:写一个基于 ghcr.io/getpaseo/paseo 的 Dockerfile 装上所需 CLI,或把凭据放进 /home/paseo 卷持久化(细节 docs/docker.md)。
三条路线怎么选
上手速度桌面最快,算力弹性服务端与 Docker 最好,移动接入三条路线都支持(表中”适用人群”一行为工程建议,供参考)。
| 维度 | 桌面 app | 服务端 npm | Docker |
|---|---|---|---|
| 上手速度 | 最快:打开即用 | 快:两条命令 | 中:需会 docker 与卷挂载 |
| daemon 位置 | 本机 | 服务器/VM | 容器 |
| 算力归属 | 本机 | 远端机器 | Docker 宿主机 |
| 手机接入 | Settings → Pair Device | relay 配对或直连 | relay 配对或直连 |
| 适用人群(工程建议) | 个人开发机首选 | 有常开服务器的重度用户 | 要环境隔离与可迁移的团队 |
拿不定就先走桌面路线,需求长出来再迁服务器或 Docker——daemon 与客户端分离,换端不换脑(工程建议)。与 Omnigent 的取舍另有专文:Paseo vs Omnigent。
远程场景:笔记本指挥工作站
daemon 在哪台机器,命令就能打到哪台:--host 指向远程 daemon,--cwd 是远程主机上的路径(README 说明)。README 原样命令:
paseo run --host workstation.local:6767 --cwd /workspace "run the full test suite"
这条命令的工程含义:daemon 跑在 workstation.local 的 6767 端口,任务在工作站的 /workspace 里执行,你的笔记本只是发令端。
其余高频命令一并放上(README 原样):
paseo run --provider claude/opus-4.6 "task"
paseo run --provider codex/gpt-5.5 --worktree feature-x "task"
paseo ls
paseo attach abc123
paseo send abc123 "follow-up"
ls 列出在跑的代理,attach 接入会话,send 补一句指令,--worktree 把任务隔离进独立 worktree。另有官方 skills:npx skills add getpaseo/paseo,装上 /paseo-handoff、/paseo-advisor、/paseo-committee 三个技能(README);并行调度的完整玩法见(Paseo 并行代理实战)。
安全与隐私清单
Paseo 的隐私基线在 README 里写得很硬:无遥测、无跟踪、无强制登录;需要你自己把关的是口令、插件和暴露面。
- 换掉占位口令(工程建议,非官方要求):
PASEO_PASSWORD=change-me里的 change-me 只是示例,容器端口对局域网或公网可达前,换成强随机密码。 - 插件只装信任的:README 安全提示原文——插件可访问 daemon 所在机器,
paseo plugin add owner/slug之前确认来源可信。与 npm 全局装包同级对待:有机器访问权的代码,按最高权限审。 - relay 与直连的取舍(工程建议):relay 端到端加密,但流量经第三方转发;纯内网或 VPN 环境选直连,暴露面更小。
- 暴露面最小化(工程建议):daemon 端口无必要不暴露公网,远程接入优先走 VPN 组网;确需公网访问时,确认口令强度并缩短暴露时长。
排错思路:没活干、配不上、打不开
三类高频故障对应三条检查链:先查 agent CLI 与凭据,再查连接路径,最后查端口与口令(排查思路为工程建议,具体以官方 connectivity 文档为准)。
- daemon 起来了但没活干:多半是 agent CLI 未装或凭据缺失。先在 daemon 所在机器直接跑一次那个 CLI,能跑通再回 Paseo 派活。
- 手机配对不上:先确认 daemon 侧 relay 是否启用;走直连就确认两端在同一 VPN 或内网。
- Web UI 打不开:Docker 路线依次查容器状态、
-p 6767:6767映射、PASEO_PASSWORD 是否输对。 - 远程
--host连不上:确认 daemon 主机名解析与 6767 端口可达;VPN 直连再确认两端路由。
常见问题
paseo 部署哪种方式最快?
直接答:桌面 app 最快——paseo.sh/download 下载后打开即自动启动 daemon,无需其他安装,这也是 README 的推荐路径;手机在 Settings → Pair Device 配对。
展开说:桌面路线的代价是算力绑在本机。要常在线、多设备共享算力,再迁到服务端 npm 或 Docker 路线,命令见上文,前置条件(agent CLI 与凭据)不变。
paseo docker 怎么跑?
直接答:一条 docker run 命令——映射 6767 端口、设置 PASEO_PASSWORD、挂载 paseo-home 与 workspace 两个卷,启动后浏览器开 http://localhost:6767 进入自托管 Web UI(README 原样命令见路线三)。
展开说:镜像里没有预装 agent CLI,要用扩展镜像或 /home/paseo 卷把 CLI 和凭据带进去,否则容器起来了也没有代理可跑(细节 docs/docker.md)。
coding agent 手机 远程 怎么实现?
直接答:Paseo 的方案是 daemon 常开、手机装原生 iOS/Android app 配对接入——桌面端 Settings → your host → Pair Device,relay 端到端加密,出门也能派任务、看进度、补指令。
展开说:不想经 relay 的内网用户,Tailscale 等 VPN 直连同样能手机接入;命令行党还有 --host 直打远程 daemon 的用法,见上文远程场景一节。