paseo

Paseo 是一个远程守护进程，用于管理编码 Agent 和终端。可通过 MCP 工具或 CLI 控制它。

已连接的主机

调用 list_hosts 以发现调用方守护进程（self）及其已注册的目标（hosts）。工具调用时使用目标的 serverId；标签仅为显示名称。

create_workspace、list_workspaces、create_agent、send_agent_prompt、get_agent_status、get_agent_activity 和 list_agents 均接受 serverId。调用方守护进程无需指定该参数。其他 MCP 工具均在调用方守护进程上运行。

将 Agent 的 { serverId, agentId } 成对使用。例如，调用 send_agent_prompt 时传入：

{ "serverId": "srv_build", "agentId": "agent_123", "prompt": "Continue", "notifyOnFinish": true }

远程路径和工作区 ID 属于目标主机。远程 list_agents 没有调用方目录默认值；传入 cwd 进行筛选。

通过 CLI 管理注册；更新或移除时使用返回的 registrationId：

paseo --host localhost:6768 host add localhost:6779 --label build
paseo --host localhost:6768 host ls --json

项目

通过 CLI 管理守护进程的项目注册表：

paseo project create [path]
paseo project ls
paseo project rename <project-id> <name>
paseo project rename <project-id> --reset
paseo project delete <project-id>

对于本地守护进程，project create 默认使用当前目录，并在 CLI 所在机器上解析相对路径。使用 --host 或 PASEO_HOST 时，必须提供路径；目标守护进程会在其所在机器上解析该路径。删除项目会归档其活动工作区，并从 Paseo 中移除该项目，但不会删除项目目录。

工作区

create_workspace — 创建独立于任何 Agent 的工作区。必填项：isolation（local 或 worktree）。Worktree 隔离支持 mode: "branch-off" | "checkout-branch" | "checkout-pr"：创建新分支时使用 branchName/baseBranch，使用已有分支时使用 branch，创建变更请求时使用 prNumber，并可选提供 forge。本地目录或源代码检出使用 path，所属项目使用 projectId；未提供路径时，worktree 可从 projectId 解析其来源。worktreeSlug 用于控制托管路径。返回以 workspaceId 为核心的工作区描述信息。

background: true 会使工作区从默认列表和侧边栏中隐藏，但其内容仍会持久保留且可访问；省略 background 时，会继承当前工作区的值（没有调用方时为 false），只有用户明确提出要求时才覆盖此值。

请明确选择 baseBranch：origin/main 选择远程跟踪分支；refs/heads/main 选择本地 main 分支。裸写 main 时，若本地 main 分支存在则优先选择，否则选择 origin/main。即使分支已变基或其 PR 目标已更改，Paseo 仍会保留解析出的引用，以供工作区比较使用。

list_workspaces — 列出活动工作区；除非设置 includeBackground: true，否则不包括后台工作区。

archive_workspace — { workspaceId }。归档工作区及其 Agent 和终端。本地目录会保留；只有在归档其最后一个活动工作区引用后，Paseo 才会移除其拥有的 worktree。

rename_workspace — { workspaceId, name }。重命名工作区。

工作区脚本

已配置的 paseo.json 脚本通过工具和 CLI 使用相同的受监督生命周期。

list_workspace_scripts — { workspaceId }。列出已配置脚本及其生命周期、服务端口、代理 URL、运行状况、退出代码和终端 ID。

start_workspace_script — { workspaceId, scriptName }。通过 Paseo 托管的工作区脚本启动器启动一个已配置的脚本，并返回其状态元数据。

stop_workspace_script — { workspaceId, scriptName }。通过受监督的终端停止正在运行的脚本，并返回停止后的状态元数据。

对应的 CLI 命令可接受明确的工作区 ID，也可解析当前目录：

paseo script ls [--cwd <path> | --workspace <workspace-id>]
paseo script start <name> [--cwd <path> | --workspace <workspace-id>]
paseo script stop <name> [--cwd <path> | --workspace <workspace-id>]

Agent

create_agent — 必填：title、provider（claude/opus、codex/gpt-5.4、……）、initialPrompt。可选：workspaceId、notifyOnFinish、settings、labels。返回 { agentId, workspaceId, … }。

初始运行时设置位于 settings 下：modeId、thinkingOptionId 和特定于提供方的 features。Agent 配置文件是这些值的首选来源。对于 Codex 快速模式，创建 Agent 时传入 settings: { features: { "fast_mode": true } }。

Agent 作用域内的创建始终会创建你的子 Agent。在你自己的主机上，省略 workspaceId 即可使用当前工作区。在另一台主机上，先使用该 serverId 列出或创建工作区，再将其 workspaceId 和相同的 serverId 传给 create_agent。放置位置不会改变父子关系。

分离是子 Agent 功能中的一项明确用户操作，不是 Agent 工具。跨工作区的子 Agent 仍然是你的子 Agent，尽管它也会作为常规标签页显示在其工作区中。

Agent 作用域内的 create_agent 默认将 notifyOnFinish 设为 true。需要显式报告或不需要完成回调时，将其设为 false。

send_agent_prompt — { agentId, prompt, activeTurnBehavior? }。用于向现有 Agent 发送后续消息。Agent 作用域内的调用默认采用 steer；顶层调用默认采用 interrupt。将 activeTurnBehavior 设为 steer 或 interrupt 可覆盖默认值。无法引导时会回退为中断。CLI Agent 消息发送采用相同的默认值，并接受 --behavior steer|interrupt。Agent 作用域内的调用会立即返回排队回执；发送给每个接收方的消息会在安静两秒后送达。顶层调用会在确认分发后返回。Agent 作用域内的调用默认将 notifyOnFinish 设为 true；顶层调用没有父级回调。

update_agent — { agentId, name?, labels?, settings? }。对现有 Agent 进行运行时更改时使用 settings：modeId、model、thinkingOptionId 和特定于提供方的 features。对于 Codex 快速模式，传入 settings: { features: { "fast_mode": true } }。

list_agents — 按 cwd、statuses、sinceHours、includeArchived 筛选；将 includeBackground: true 设为包含后台工作区中的 Agent。

archive_agent — { agentId }。若 Agent 正在运行则中断，并将其从活动列表中移除。

Agent 配置文件与提供方发现

list_profiles — 由用户配置的命名启动配置包。选择如何启动委派的 Agent 前，先调用此工具并阅读每个配置文件的 notes。选择用户指定的命名配置文件，或选择备注与工作最匹配的配置文件。

create_agent 没有 profile 参数。将所选配置文件的内容应用到调用中：

• 将 provider 和 model 组合为 provider/model 值，作为 create_agent.provider
• 将 modeId 复制到 settings.modeId
• 将 thinkingOptionId 复制到 settings.thinkingOptionId
• 将 featureValues 复制到 settings.features

省略不存在的值。不要记住已选配置文件，也不要据此推断后续变化；配置文件仅用于启动配置。

如果没有合适的配置文件，或未配置任何配置文件，请使用以下提供方发现工具，而不要猜测。若因没有合适的已配置配置文件而回退，请告知用户。

list_providers — 查看简要的提供方可用性和模式信息。

list_models — 查看某个提供方的完整模型列表。仅在需要模型 ID 或思考选项时使用；列表可能很长。

inspect_provider — 查看简要的提供方能力和功能信息。必填：provider；若当前会话不在 Agent 作用域内，则传入 cwd。可选：传入包含草拟的 model、modeId、thinkingOptionId 和 features 的 settings。

仅设置 inspect_provider 返回的功能 ID。对于 Codex 快速模式，查找 fast_mode，并向 create_agent 或 update_agent 传入 settings: { features: { "fast_mode": true } }。

日程安排和心跳

create_schedule — 按 cron 计划启动一个新的 Agent。必需参数：prompt、cron、provider。可选参数：timezone、name、cwd、maxRuns、expiresIn。适用于需要由全新 Agent 执行的周期性任务。

create_heartbeat — 按 cron 计划向你发送提示词。必需参数：prompt、cron。可选参数：timezone、name、maxRuns、expiresIn。适用于提醒、PR／构建跟进，以及需要返回到当前对话的状态检查。

delete_heartbeat 会停止心跳。MCP 有意不提供心跳更新工具；任务或计划变更时，请删除后重新创建。

日程安排提供完整的列表、检查、更新、暂停、恢复、单次运行、查看日志和删除功能。心跳则刻意不提供这些功能。

等待

创建子 Agent 或向其发送提示词时，notifyOnFinish 默认值为 true，完成、出错或需要权限时都会报告，包括跨主机的情况。 结束本轮并等待通知，而不是轮询。 如果你想通过 send_agent_prompt 获得明确回复，请让发送方在将 notifyOnFinish 设为 false 之前，先通过 list_hosts 检查接收方所在的服务。

CLI 语义

即使语法不同，CLI 和工具也采用相同的所有权语义：

paseo workspace create --isolation worktree --mode branch-off --new-branch fix-x --base origin/main
paseo workspace create --isolation worktree --mode checkout-branch --branch existing-work
paseo workspace create --isolation worktree --mode checkout-pr --pr-number 42
paseo run --provider codex/gpt-5.4 --mode full-access --workspace <workspace-id> "<prompt>"
paseo run --provider codex/gpt-5.4 --mode full-access --new-workspace worktree --worktree-mode branch-off --new-branch fix-x --base origin/main "<prompt>"
paseo send <agent-id> "<follow-up>"
paseo ls
paseo schedule create --cron "*/15 * * * *" "ping main build"
paseo heartbeat create --cron "*/15 * * * *" "check the build"

通过 paseo --help 和 paseo <cmd> --help 了解用法。

有关产品问题、设置、日志、版本问题或故障排查，请使用 paseo-help 技能。