在 Codex、Claude Code 或 WorkBuddy 中工作时，你可以把一项跟进要求交给已有的 Sparse Agent，再从同一个客户端查看进展。CLI 和 MCP 都沿用该 Agent 原来的目标、记忆和对话；你也可以回到网页查看同一份聊天记录。
接入状态：已开放（2026 年 10 月 13 日）。 登录网页工作台后，进入「设置 → CLI / MCP」获取接入密钥、复制安装命令或配置 MCP。
选择接入方式
| 你的客户端 | 建议方式 | 需要准备什么 |
|---|---|---|
| 能执行本机命令的 Codex、Claude Code 或 WorkBuddy | CLI | 安装工具和技能，完成密钥登录 |
| 支持远程 MCP 和浏览器授权的客户端 | MCP | 添加服务地址，登录并授权所选 Agent |
CLI 是本机运行的命令行工具，技能告诉第三方 Agent 怎样调用它。MCP 让客户端把 Sparse Agent 的能力作为工具调用，无需安装 Sparse Agent CLI。MCP 客户端需支持 Streamable HTTP；浏览器授权还需要支持 OAuth。
准备一个已有 Agent
按主手册完成登录、模型和云环境设置，创建 Agent 并填写 Goal。确认环境已经就绪，再决定开放哪些 Agent。
CLI 用户进入设置 → CLI / MCP，选择已有 Agent、填写便于识别的接入名称、设置有效期并生成密钥。密钥只显示一次，请由你自己在终端的隐藏输入中使用。MCP 用户可以直接从客户端发起浏览器授权，在授权页面选择 Agent。
客户端只能访问授权的 Agent。模型密钥和云厂商 Token 留在对应设置中，不需要交给客户端。不要把接入密钥粘贴到 Agent 聊天窗口、命令参数或项目文件里。
安装 CLI 并登录
macOS 和 Linux 在终端执行：
curl -fsSL https://sparse-agent.com/install.sh | sh -s -- --client all
只配置一个客户端时，把 all 改为 codex、claude 或 workbuddy。CLI 支持 macOS / Linux 的 Intel 与 ARM64，以及 Windows x64；「下载与接入」页也提供对应系统的安装包。
Windows 在 PowerShell 执行：
Invoke-WebRequest https://sparse-agent.com/install.ps1 -OutFile install-sparse-agent.ps1
.\install-sparse-agent.ps1 -Client all
安装后重新打开终端，检查工具并完成登录：
sparse-agent --version
sparse-agent --help
sparse-agent login
sparse-agent agents --json
login 提示你粘贴密钥，终端不显示输入内容。成功后，agents 列出已授权 Agent；记下你要使用的名称和 ID。找不到命令时，检查安装目录是否在 PATH 中：macOS / Linux 默认为 ~/.local/bin，Windows 为 %LOCALAPPDATA%\SparseAgent\bin。
让客户端发现技能
Codex 和 Claude Code 的安装会加入 sparse-agent 技能，分别保存在 ~/.agents/skills/sparse-agent/ 和 ~/.claude/skills/sparse-agent/。开启新的客户端会话，让它读取 sparse-agent --skill。
WorkBuddy 默认生成一个技能 ZIP，安装输出会显示位置。在添加技能 → 上传技能中导入，确认技能启用，再开始新任务。下载页也会提供 workbuddy-sparse-agent.zip。界面步骤见 WorkBuddy 官方技能说明。
安装技能、启用技能和登录是三个步骤。客户端无法执行本机命令时，使用它支持的 MCP 连接方式。
在客户端对话里发送要求
例如，你已经有一个名为「内容运营助手」的 Sparse Agent，可以这样说：
请先读取 sparse-agent --skill，列出我已授权的 Agent。
找到“内容运营助手”，发送一次 Run Now：整理今天的工作进展，说明已完成事项、遇到的问题和下一步计划。
持续读取它公开发送的中间消息，收到本次请求的最终回复后再整理给我。
如果名称无法唯一确定，请先让我选择。保留请求标识和读取位置，等待中断后继续查询原请求。
Run Now 是给已有 Agent 发送一条跟进要求。Agent 正在工作时，新要求可能排队；遇到扫码或登录等待时，仍需要先处理网页中的「需要协助」。发送新消息不会自动修改长期 Goal。
也可以直接在终端调用，把 AGENT_ID 换成查询结果中的实际 ID：
sparse-agent run-now --agent AGENT_ID --message "整理今天的进展，过程中告诉我处理到哪一步" --follow --jsonl
--follow 持续等待公开进展和最终回复，--jsonl 便于客户端逐条读取。进展是 Agent 主动公开发送的消息。本次请求完成表示这条跟进已处理，长期目标仍按原安排推进。
通过 MCP 连接
在客户端的 MCP 配置中添加以下地址，选择 HTTP / Streamable HTTP：
https://sparse-agent.com/mcp
Codex 的终端配置示例：
codex mcp add sparse-agent --url https://sparse-agent.com/mcp
codex mcp login sparse-agent
Claude Code 的终端配置示例：
claude mcp add --transport http sparse-agent https://sparse-agent.com/mcp
随后进入 Claude Code 对话，使用 /mcp 选择服务并完成浏览器授权。更多选项见 Claude Code 官方 MCP 说明。界面名称可能随客户端版本不同。
在浏览器里登录 Sparse Agent，确认服务地址并选择允许访问的 Agent。完成后，客户端可以使用四个工具：
| 工具 | 用来做什么 |
|---|---|
sparse_list_agents |
查找已授权 Agent |
sparse_run_now |
向所选 Agent 发送一次要求 |
sparse_read_events |
继续读取公开进展和回复 |
sparse_get_request |
查询同一次请求的状态与结果 |
可以告诉客户端：“列出已授权 Agent，向内容运营助手询问今天的进展。只提交一次，保留请求标识，继续读取消息直到完成或失败。”每次新要求应生成独立的 request_id，后续查询沿用它和返回的 cursor。
有些客户端显示实时进度，有些需要继续读取消息。一次工具调用最多等待 30 秒，结束等待后继续调用读取工具即可。支持刷新令牌的 OAuth 客户端可自动续期；访问令牌最长一小时，连续 30 天未续期或授权满 90 天后需要重新授权。只支持手工 Bearer 配置的客户端可以使用网页生成的接入密钥，按网页显示的期限更新。
等待中断后继续查看
CLI 默认最多等待 300 秒，可用 --timeout 调整。超时（退出码 3）、Ctrl-C 或关闭终端只结束本地等待；云端已接受的请求仍会继续。
保留输出中的 REQUEST_ID 和最近读取位置 CURSOR，继续查看原请求：
sparse-agent events --agent AGENT_ID --request-id REQUEST_ID --after CURSOR --follow --jsonl
sparse-agent request --agent AGENT_ID --request-id REQUEST_ID --json
提交时网络中断，先用已输出的请求标识查询。确实需要重试时，用相同的 --request-id 和原消息重试，避免重复执行；新要求则使用新的标识。读取位置过期时，CLI 会恢复当前记录并提示可能缺少较早进展。
撤销接入与常见问题
在设置 → CLI / MCP撤销对应授权，API、MCP 和后续续期都会停止。sparse-agent logout 只删除本机密钥；要停止其他设备上的访问，仍需网页撤销。
| 遇到的情况 | 下一步 |
|---|---|
| 设置中找不到 CLI / MCP 入口 | 刷新官网，确认已登录；检查所用地址是否为 https://sparse-agent.com |
| 列表为空或找不到 Agent | 检查账号和授权范围，确认已在网页创建 Agent |
| 环境未就绪或未设置目标 | 在工作台完成准备，再发送新的要求 |
runtime_upgrade_required |
联系维护人员升级云端运行环境，再查询原请求；是否重试以请求状态为准 |
| 密钥过期、被撤销或需要重新授权 | 生成新密钥并登录，或重走客户端浏览器授权 |
| 等待结束，仍没有最终回复 | 查询原请求并续读，不要直接重新提交 |
| Agent 等待扫码或登录 | 在网页完成「需要协助」，再查看原任务 |
首次接入建议只授权一个 Agent，询问一次进展，并在网页核对同一条消息和回复。确认使用方式后，再增加开放的 Agent。