unbrowse

Unbrowse

使用托管服务 https://unbrowse.ai。执行、已索引路由和网站会话均保留在服务器端。此技能提供操作指南；登录方式为 OAuth，详见下文。

入门：使用 OAuth 登录

登录通过用户浏览器中的 OAuth 完成：先收到电子邮件中的登录链接，然后点击 Allow。无需密码，也无需粘贴任何内容。切勿在聊天中向用户索要令牌或密钥。

先检查，再仅登录缺少的部分：

1. MCP：如果此会话的工具列表中有 unbrowse_discover，则 MCP 已登录。
2. CLI：运行 npx unbrowse whoami。退出码为 0 表示已登录。退出码为 3 表示尚未登录。

登录 MCP（Agent 宿主）：

claude mcp add --transport http unbrowse https://unbrowse.ai/mcp

{"mcpServers":{"unbrowse":{"url":"https://unbrowse.ai/mcp"}}}

宿主会自行运行 OAuth 登录（在 Claude Code 中：/mcp，选择 unbrowse，然后选择 Authenticate）。不要在配置中添加 bearer 标头；设置后，宿主会跳过 OAuth。配置中的 URL 不代表会话已登录：在宿主完成 OAuth 之前，不会列出 Unbrowse 工具。

登录 CLI：

npx skills add unbrowse-ai/unbrowse && npx unbrowse login

unbrowse login 会在此机器的浏览器中打开登录页面。用户输入电子邮件地址，打开收到的链接，然后点击 Allow；CLI 会打印 Signed in to https://unbrowse.ai (workspace ws_…)，并将令牌存储在 ~/.config/unbrowse/cli.json（权限模式 0600，会自动刷新）。

从 Agent 的 shell 登录（用户没有终端）：在后台运行 npx unbrowse login --no-open，将其打印的 https://unbrowse.ai/authorize?… 链接提供给用户，然后等待 Signed in 行。该链接会返回到此机器上的 127.0.0.1，因此用户必须在同一台机器的浏览器中打开它。在远程或无头机器上，运行 npx unbrowse login --device，然后在任意设备上批准显示的代码，或者使用 API 密钥（见下文）。未登录时运行其他任何命令，如果有终端，就会启动相同的浏览器登录流程；如果没有终端，则会以退出码 3 退出，并提示运行 unbrowse login。

然后进行首次调用：npx unbrowse run 'top stories on hacker news'。默认情况下，网站请求会从用户自己的 IP 发出；使用 --from-unbrowse 则会改为从 Unbrowse 发出。

npx unbrowse mcp（适用于需要 stdio MCP 的宿主）使用 CLI 登录；unbrowse mcp add 会将其注册到 Claude Code 和 Codex，使它们共用这次登录。另一种方式是：如果 CLI 未登录，它可以使用 Claude Code 自己的 Unbrowse MCP 登录，但仅适用于添加到 https://unbrowse.ai/api/mcp 的服务。https://unbrowse.ai/mcp 的令牌（插件和上述设置使用的 URL）无法用于 REST API，因此这种情况下请运行 unbrowse login。MCP 配置中绝不会写入令牌。

如需在自动化和 CI 中无需浏览器即可运行，请从调用方的密钥管理器设置 UNBROWSE_API_KEY（在已登录的控制台 https://unbrowse.ai/app 中创建密钥）。切勿将密钥写入已提交的配置、提示词、命令参数或日志。

CLI 和 SDK：https://github.com/unbrowse-ai/unbrowse

宿主插件

捆绑此技能的打包安装会连接 Unbrowse，并将宿主自身的浏览器请求重定向到 Unbrowse（https://github.com/unbrowse-ai/unbrowse/tree/main/plugins）：

• Claude Code：claude plugin marketplace add unbrowse-ai/unbrowse，然后运行 claude plugin install unbrowse@unbrowse。
• Codex：codex plugin marketplace add unbrowse-ai/unbrowse，然后运行 codex plugin add unbrowse@unbrowse；设置 web_search = "disabled" 以停用内置搜索。
• Grok Build：grok plugin install unbrowse-ai/unbrowse#plugins/grok-build --trust。
• OpenClaw（@unbrowse/openclaw）、Hermes（plugins/hermes）、elizaOS（@unbrowse/plugin-unbrowse）：通过同一 MCP 使用原生工具或操作。

需要 stdio 服务的宿主可以运行 npx unbrowse mcp；它提供相同的 unbrowse_… 工具名称。安装插件后，对非本地 URL 使用内置网页抓取、网页搜索和浏览器导航都会被拒绝，并提示改用相应的 Unbrowse 工具；设置 UNBROWSE_ALLOW_BUILTIN_BROWSER=1 可在当前会话中解除此限制。

选择接口

• MCP：用于发现、运行、读取页面、云端浏览、索引和已保存登录信息请求。这些名称是 MCP 工具；CLI 为每个工具都提供了对应命令（见下文）。
• CLI：unbrowse discover、run、inspect、resume、scrape <url>（将单个页面转为 Markdown）、index <url>（学习网站；index status）、registry、site、whoami。scrape 和 index 需要 CLI 12.2.0 或更高版本。unbrowse run 绝不会在浏览器中操控网站（它唯一会打开的浏览器用于首次登录）。从 CLI 12.5.0 开始，每个 MCP 工具都有对应命令：unbrowse map <url>、sites [site]、forget、connect [app]、credits、云端浏览器命令 unbrowse browse open <url> / browse snapshot <id> / browse act <id> click e1 / browse finish <id> / browse close <id>、credentials list|request|status、replay list|search|get|timeline|ask；unbrowse tool <name> 可调用其他任何已列出的工具，例如学习到的网站工具。没有 unbrowse install。unbrowse help 会说明已安装版本的信息。
• SDK：用于 REST 集成和脚本编写。请查阅公开的 SDK 文档，了解其支持的方法；MCP 工具和 REST 方法的名称不可互换。

核心 MCP 工具：unbrowse_discover、unbrowse_run、unbrowse_inspect、unbrowse_resume、unbrowse_cancel、unbrowse_scrape、unbrowse_map、unbrowse_sites、unbrowse_usage、unbrowse_credits、unbrowse_forget、unbrowse_learn、unbrowse_index、unbrowse_index_status、unbrowse_credentials_list、unbrowse_credentials_request、unbrowse_credentials_status、unbrowse_connect（连接应用自己的 MCP 服务，例如 Linear、Notion 或 GitHub，使其工具以用户身份运行：需要登录的应用会返回一个由用户打开的链接）、unbrowse_import_mcps（将此 Agent 已拥有的 MCP 服务导入 Unbrowse，见下文），以及云端浏览器工具 unbrowse_browse_open、unbrowse_browse_snapshot、unbrowse_browse_act、unbrowse_browse_finish、unbrowse_browse_close。

references/tools.json 包含导出的核心 MCP 输入架构。已连接服务的 tools/list 是权威来源：其中还包括此用户工作区可用的动态工具。切勿臆造能力 ID 或输入架构。

执行任务

1. 使用 unbrowse_discover {query} 进行发现。检查返回的输入、选项和提示。优先选择匹配且状态正常的能力；warm 表示 HTTP 重放，rendered 表示需要渲染。相关时，使用 unbrowse_sites 检查已保存的会话和登录状态。公共工具包含 version，即生成这些工具的 Unbrowse 版本（YYYY.MM.DD）；匹配度相同的工具按最新版本优先排列，minVersion 会排除较旧的工具。
2. 按所列架构调用选定的工具，或使用 unbrowse_run {capability, input}。如果未选择 ID，可通过自然语言 task 进行路由。对同一预期变更使用稳定的 idempotencyKey。对于较大的答案，传入 select（MCP 运行工具、unbrowse_resume、unbrowse_inspect、POST /api/v1/runs）：路径示例：["results[].{id,title,price}", "total"]。它只会在验证后缩小返回内容的范围；计费不变。超过 40,000 个字符的结果会被缩短（truncated: true）；selectMissing 会列出未匹配到任何内容的路径。
3. 检查返回的状态和实际结果。input_required 表示需在同一次运行中回答待处理的要求：unbrowse_resume {runId, answers:{field:value}}。对于选项，请传入所列选项的值。如果提供了修订版本检查，请保留。
4. no_capability 表示没有匹配的可复用路线。按照 result.next 操作：tool 是 unbrowse_index（POST /api/v1/index，然后调用 GET /api/v1/index/{jobId}；CLI 命令为 unbrowse index <url>）。若要立即作答，请改为读取页面：使用 unbrowse_scrape（CLI 命令为 unbrowse scrape <url>）。仅当 unbrowse_browse_open 在本会话的工具列表中时才调用它（在 shell 中使用：unbrowse browse open <url>，CLI 12.5.0+）。不要 POST /api/v1/browse/open。它不是可用路线。请如实说明网站不受支持或遭到拦截。
5. 只有在验证结果后才能报告已完成。outcome_unknown 表示变更可能已经发生：重试前先检查效果回执和目标位置。取消操作会停止后续派发，但不会撤销已完成的操作。

不要根据 HTTP 200、工具传输成功、截图或生成的计划推断业务已成功。不要承诺普遍覆盖，也不要承诺每次请求都能免浏览器执行。发布、发送、购买或其他外部写入操作必须获得用户授权。

Unbrowse URL

当用户指定网站时：

1. 如果本会话的工具列表中没有 unbrowse_discover，说明 MCP 尚未登录。停止操作，并指出已配置的 MCP URL。远程 MCP 需要通过宿主自身的 OAuth 登录；如果已通过 CLI 登录，运行 npx unbrowse mcp add 可让宿主使用该登录会话连接服务端（需在新会话中生效）。
2. 查询主机（使用 unbrowse_sites，或 CLI 命令 unbrowse site <host>）。如果工具已编译完成，就使用其中一个。停止操作。
3. 如果没有工具：使用 unbrowse_index {url, focus} 或 POST /api/v1/index。轮询 unbrowse_index_status 或 GET /api/v1/index/{jobId}。
4. status: failed 且 error.code: model_unavailable 表示索引模型额度不足。报告任务 ID 和错误消息。不要改为浏览，也不要循环启动相同任务。
5. status: done 且 indexed: 0 表示没有获取到任何信息。请如实说明。indexed > 0 表示可以调用一个工具并检查结果。

/api/v1/index 返回的 202 是任务 ID，不是已编译的工具。

通过普通 HTTP 使用网站工具

每个已编译的网站也是一个 REST API，供代码调用，而非用于 Agent 会话：

• GET https://unbrowse.ai/api/v1/sites/<host>/openapi.json：OpenAPI 3.1，每个工具对应一个操作，包含类型化输入、经过验证的 example 输入，以及每种状态和标头。读取无需密钥。
• POST https://unbrowse.ai/api/v1/sites/<host>/call/<tool>：将工具的输入作为 JSON 请求体，并使用 Authorization: Bearer <key>。可选项：x-unbrowse-deadline-ms、Idempotency-Key、select。202 表示 input_required；504 run_timeout 会提供一个 runId 供轮询；409 tool_quarantined 表示应改用其他工具。
• SDK：new Unbrowse().callTool(host, tool, input)。

接口约定和示例：https://unbrowse.ai/docs/site-apis.md

读取或学习网站

对于结构化数据和网站任务，优先使用 unbrowse_discover 和匹配的工具，或使用 unbrowse_run。只有在没有合适的 API 或已学习工具时，才将 unbrowse_scrape {url} 作为静态页面和文档的最后手段。PDF、.docx、.xls 或 .xlsx URL 会返回提取出的 Markdown 文本（PDF 会在 metadata.pages 中提供页数；电子表格会保留工作表名称、行和格式化后的值）。metadata.truncated 表示提取内容有长度限制；formats: ["raw"] 会将完整文档字节作为 base64 返回；unbrowse_map {url} 会查找同一网站中的 URL。已知 URL 或支持页面渲染，都不意味着应默认使用抓取。对于没有匹配路由的动态内容、搜索、分页或交互，请使用 unbrowse_index 或可用的云浏览器工具来学习并重放网站 API：

1. unbrowse_browse_open {url,task} 会返回页面和元素引用。
2. 使用最新的引用调用 unbrowse_browse_act。对于普通输入，请提供有意义的 name，例如 date 或 query；测试任务所需的每个筛选器。页面变更后刷新快照。
3. 使用 unbrowse_browse_finish {sessionId} 返回最终页面并编译观察到的路由。使用不同输入的两个会话有助于识别可复用的参数。检查 learnError 和 newTool；浏览成功本身并不能证明存在可复用的路由。
4. 完成后关闭会话。除非设置 discard:true，否则 unbrowse_browse_close 仍会进行索引。

如果想提前覆盖整个网站，可使用 unbrowse_index {url, focus?, maxCapabilities?} 启动后台任务：Unbrowse 自带的 Agent 会执行网站的核心只读功能，通过无浏览器重放验证每项功能，并将其添加到你的工具中。之后使用 unbrowse_index_status {jobId} 查看状态。maxCapabilities 会限制任务索引的所有工具数量（声明的工具、站点地图页面类型和记录的流程合计）。focus 仅保留与其匹配的站点地图页面类型；如果它指定的是分页、页面大小、筛选器或搜索等流程，则不会保留任何页面类型。起始 URL 中的查询键（?page=0&pageSize=100）会成为工具的输入。stoppedReason 会说明任务结束的原因。若仍在验证工具，时间预算会延长一次，增幅为一半。

现有的 HAR 文件对可通过 unbrowse_learn 提交。只能提交用户授权的录制内容；HAR 文件可能包含私密数据。托管服务会拒绝私有和环回目标。

导入 Agent 的 MCP 服务

如果用户想在 Unbrowse 中使用现有的 MCP 服务（登录一次，所有 Agent 都能使用），请导入这些服务，而不是逐个手动重新添加。

• 在终端中：npx unbrowse mcps 会列出此机器上 Agent 配置中的服务（Claude Code、Claude Desktop、Cursor、Codex、VS Code、Windsurf、Gemini、Zed）；npx unbrowse mcps import 会导入这些服务（--dry-run 会显示计划）。这些配置中的密钥会保留在机器上，除非用户添加 --with-keys。
• 作为 MCP 工具：自行读取宿主的 MCP 配置，并调用 unbrowse_import_mcps {servers:[{name, url} | {name, command, args}]}。切勿传递密钥、标头或环境变量值；dryRun: true 会显示计划。
• 远程服务通过地址连接。本地（stdio）服务无法在 Unbrowse 云端运行：如果目录中托管了相同的应用，则改为连接该应用；否则状态为 local_only，并保留在 Agent 中。sign_in 和 key 行包含用户需要打开的链接。导入前请向用户展示计划。

网站登录

Unbrowse 账户登录与网站保存的登录信息是分开的。切勿在聊天中索要密码，也不要通过普通工具参数输入凭据。

• 在登录页面上，使用 unbrowse_browse_act {sessionId,action:"autofill"}，或者在填充操作中使用 vault:"username"|"email"|"password"|"totp"。值会直接从保险库传到网站。
• 如果缺少登录信息：提供返回的 signIn.url 或 details.url 保存登录链接。unbrowse_credentials_request 可以创建此链接；unbrowse_credentials_status 可以检查是否已完成。只有准备就绪后才继续。
• 不要绕过 CAPTCHA、MFA 或人工验证。提供受支持的交接方式，或说明遇到的阻碍。
• 保存的会话会自动复用（用户可以按网站或整个工作区关闭此功能）；不要仅仅因为开始了另一项任务就再次登录。

只读且不含密钥的学习路由可以清理后共享到公共注册表。所有者可以在控制台中选择退出。登录信息、私有会话值和写入操作不会成为公开的工具定义。

为多个用户提供服务（组织）

当调用方是为自身用户运行服务的构建者时，应使用组织密钥，并在每次调用中标明用户：X-Unbrowse-End-User: <that user's id>（REST 和 MCP 标头）。每位用户都有自己的登录信息和会话。

• 始终发送任务所属用户的 ID。切勿在不同用户的任务间复用某个用户的 ID，也不要省略 ID：如果没有 ID，此调用将以组织自身的身份执行，而不是以任何用户的身份执行。
• signIn.url（/connect/… 链接）属于同一位用户：将其发送给该用户，而不是构建者或其他用户。用户可在此处保存登录信息，无需 Unbrowse 账户；等待 unbrowse_credentials_status 返回 fulfilled 后再重新调用。
• org__… 工具由组织的用户共享（只读，不含登录信息）；my__… 工具属于当前用户。
• 配额错误反映的是组织的余额，而不是用户的余额。请将其报告给构建者。

指南：https://unbrowse.ai/docs/orgs.md

限制与恢复

• 401：使用 OAuth 重新登录该服务。CLI 返回 401：npx unbrowse login。远程 MCP 返回 401：使用该服务宿主自身的 OAuth（Claude Code：/mcp）。一次登录不能解决另一处的登录问题。
• 索引任务出现 model_unavailable：索引模型的额度不足。请报告任务 ID。未编译任何工具。这不是 unbrowse_usage 的问题，也不是网站的问题。
• 配额／付款错误：显示返回的限制和控制台链接；不要盲目重试付款。若有列出，unbrowse_credits 会显示免费／付费余额，并可返回用户的结账链接。打开账单链接并不代表授权付款。
• 验证或登录受阻：使用返回的交接方式；不要将挑战页面作为源内容展示。
• 写入操作超时：重试前先检查现有运行记录。
• 定价和配额：请查看账户当前方案和 unbrowse_usage；此技能无法更改价格。