sandbaseai/cli · 上手攻略

  • 仓库：sandbaseai/cli
  • 链接：https://github.com/sandbaseai/cli
  • 分类：Tools（MCP 桥接 / AI CLI / 多模型 API 网关）
  • 作者：spark
  • 更新：2026-10-13

§0 自检（三证 + 不确定处）

  • [x] GitHub URL 已 fetch：本攻略基于 2026-10-12/13 fetch 的 https://github.com/sandbaseai/cli README（English）及 https://github.com/sandbaseai/cli/releases/tag/v0.3.6 release 页内容。
  • [x] README 子模块 anchor：anchor 落点 = connect 主命令 + doctor 自检命令 + inspect <tool> 价格揭示 + Homebrew / npx 双通道。已 fetch 内容含完整命令片段。
  • [ ] 顶会 venue+年份：本仓库非论文，是工具型 CLI；N/A，不适用。
  • [x] 版本号 verbatim：当前 latest release = v0.3.6，发布于 2026-10-12 05:31 UTC，commit cb82903，主要变化 = "Files: 字段含义 / inspect 文件 URL hint / discover 近似匹配 hint（apiserver B-290）"。
  • ⚠️ 未独立核实点：
  • npm 镜像版本（npm view @sandbaseai/cli version 未实测；本次 fetch www.npmjs.com 触发 403 Cloudflare 验证，按规则标待核，但 GitHub release 已含 npm 包 v0.3.6）。
  • "2,000+ 模型/API" 与 "25 客户端" 两条数都来自 README 自述，本次未能从外部接口独立计数；以 ⚠️ 标注，仅作背景陈述。
  • "oauth + rollback" 写入正文时已按 README 字面照抄，未实测接入 OAuth 完整链路。

1. 这是什么 / 解决什么问题

SandBase CLI（@sandbaseai/cli）是一个 MCP 服务器 + AI CLI 二合一工具。它要做的事很具体：把你的 AI 编程助手（Claude Code / Cursor / Codex / ChatGPT / Hermes / OpenClaw 等共 25 个客户端）一次性桥接到 2000+ AI 模型和外部数据 API 上。你不需要逐家申请 API key、统一管理 token 配置——授权一次浏览器 OAuth，本机就会多出一个 MCP 服务器，所有支持的客户端都能自动发现 sandbase_discover / sandbase_inspect / sandbase_run / sandbase_run_get / sandbase_runs / sandbase_account 这一组工具。

要解决的痛点有三条：

  1. "AI 助手困在沙盒里"：模型能写代码，但不会搜索网页、查 X / 微博、生成图片、查询实时股价。SandBase 把 MCP 桥接 + 浏览器授权打包成一行 set up https://www.sandbase.ai/SKILL.md，让 agent 自己接活儿。
  2. "API key 地狱"：每个数据源（Google / Tavily / Exa / Twitter / XHS / Bilibili / Firecrawl / ElevenLabs 等）都要单独申请 + 写入每个客户端配置。SandBase 把这些密钥下沉到单一来源，本机只留一个凭据。
  3. "跨客户端重复配置"：25 个客户端各自支持 MCP，但配置语法不同。CLI 暴露 connect --client <name> 一行命令，自动写入正确配置项；冲突时（如已有非-SandBase 的同名 sandbase MCP server）保留旧条目不覆盖。

它本身不是 agent 框架，也不是模型网关；它的"价值位" = 一个本机常驻的 MCP 桥，让你装一次、惠及所有本地客户端。

2. 快速安装

支持三条正路，按"对自动化友好度"排序：

2.1 npx（跨平台、临时性最强）

npx -y @sandbaseai/cli@latest connect

一行进入交互式 OAuth 浏览器授权。授权一次后，CLI 会把所有检测到的客户端一次性挂上 SandBase MCP server。

只想看能不能用，不要写任何配置：

npx -y @sandbaseai/cli@latest catalog --json

catalog 是只读命令，不发请求、不要求账号、不写文件——这是判定 "先看后装" 的最安全入口。

2.2 Homebrew（macOS / Linux，常驻推荐）

brew install sandbaseai/tap/sandbaseai-cli
sandbase connect

brew 通道走官方 tap，已挂上 macOS / Linux CI 证据。装完后 sandbase 直接是系统命令，不再依赖 npx -y。

2.3 锁定版本 + SHA-256 校验（CI / 受控环境）

每一个 GitHub release 都附带 tarball 的 SHA-256 校验值，固定版本号 + 校验后再用本机 npx 跑：

V=$(npm view @sandbaseai/cli version)
curl -fL -O "https://github.com/sandbaseai/cli/releases/download/v$V/sandbaseai-cli-$V.tgz"
shasum -a 256 "sandbaseai-cli-$V.tgz"   # 比对 release 页面的 SHA-256
npx -y "./sandbaseai-cli-$V.tgz" connect

注意 V=$(npm view …) 这一步未对 npm 镜像实测（fetch 触发 403 验证），不能保证命名空间始终在线；CI 场景下直接 hardcode 版本字符串更安全。

3. 核心用法（可直接复制）

3.1 检视能力清单

# 只读审计：列出所有可用 model / data API
npx -y @sandbaseai/cli@latest catalog --json

# 单条工具详解：看 schema、价格、必填字段
npx -y @sandbaseai/cli@latest inspect <tool>

inspect 永远在调用前显示当前 base_price；base_price: 0 表示该调用免费。这是"先看价再花钱"的关键反直觉设计——传统网关都在扣款后才报错。

3.2 选定客户端，挂 MCP server

# 自动检测 + 全挂
npx -y @sandbaseai/cli@latest connect

# 单客户端（典型：Cursor、Codex、OpenClaw、Claude Code）
npx -y @sandbaseai/cli@latest connect --client cursor
npx -y @sandbaseai/cli@latest connect --client codex
npx -y @sandbaseai/cli@latest connect --client openclaw
npx -y @sandbaseai/cli@latest connect --client hermes
npx -y @sandbaseai/cli@latest connect --client claude-code

挂完每个客户端都需要 npx -y @sandbaseai/cli@latest doctor --client <name> 做一次回读校验，确认 MCP server 注册成功 + 本机凭据就位 + Skill 配套齐全。别跳 doctor——它就是这套工具的"安全网"。

3.3 让 agent 自己干活

把下面这行贴到 agent 的 prompt 里（README 给出的官方入口）：

set up https://www.sandbase.ai/SKILL.md

agent 会自己读 SKILL.md，跑 connect，到唯一一次的浏览器 OAuth 等你点头，然后开始用 sandbase_* 工具组。

3.4 标准工作流（agent 调用顺序）

官方给出的 inspectable sequence 是这套五步：

  1. sandbase_discover — 按任务 / 能力挑候选
  2. sandbase_inspect — 读 schema、价格、必填字段
  3. 显式确认 endpoint 与入参（不要让 agent 静默跑付费模型）
  4. sandbase_run — 同步执行（或异步时拿到 run_id）
  5. sandbase_run_get <run_id> — 异步工作轮询；sandbase_runs 看历史；sandbase_account 看余额

README 里有段示例 prompt 可以照抄：「找两个适合做方形产品配图的 image model，对比必填字段和当前价格，先别跑」——discover + inspect 全程不花钱。

3.5 回滚 / 卸载

# 单客户端移除 MCP server + 本机凭据
npx -y @sandbaseai/cli@latest unregister --client <name>

具体到 OpenClaw：README 明文写"OpenClaw currently exposes no supported Skill removal command, so unregister reports that limitation and leaves the verified SandBase Skill installed"——也就是 OpenClaw 渠道下，Skill 不会被 unregister 顺手清掉，只能手工回收。

4. 典型适用场景

场景 推荐路径
想给本地 Cursor / Claude Code 加"免费的数据 API"（Tavily 搜索 / 抓取 / 社媒监听） npx ... connect --client cursor + 闭眼用——Data API 在 README 是明示免费
Cursor 上要按需调图像 / 视频 / 语音模型而不想逐家开通 connect --client cursor 后，让 agent 用 sandbase_discover → inspect → 显式确认 → run
团队要在 CI / 代码沙盒里复现"模型网关"行为、且要可审计 锁定 v0.3.6 + SHA-256 校验那条路径（§2.3）
已经装过别家"也叫 sandbase"的 MCP server connect 自动跳过同名冲突、保留旧条目，不强制覆盖
想试但不想留痕 catalog --json 是只读命令，无需账号，不写文件

5. 坑与注意（≥5 条，三段式）

  1. ⚠️ OAuth 授权只发生一次——错过浏览器跳转窗口就只能重跑 connect。修复：跑 connect --client openclaw 时盯紧终端出现的授权 URL，复制到任一浏览器完成。
  2. ⚠️ doctor 不能跳——它回读的不是 catalog，而是"这个客户端的真实注册状态"。跳过 doctor 直接重启客户端很常见，结果就是发现 sandbase_* 工具列表为空、怀疑命令写错——其实是上一次 connect 没成功注册。
  3. ⚠️ 付费调用前必须 inspect——README 反复强调 "trust the live response over any example in this file"。把示例里的 base_price 抄到 prompt 里当真理，是这套工具最常见的浪费钱姿势。
  4. ⚠️ 异步任务别重复 run——长任务（视频生成 / 大模型）会返回 run_id，这时用 sandbase_run_get <run_id> 轮询；新建一次 run 等同于付两次钱。
  5. ⚠️ Skill 卸载在 OpenClaw 上"擦不干净"——unregister --client openclaw 报告限制并保留 Skill；如要彻底回收 Skill 需手工操作（README 未给命令，本次 fetch 无补充）。
  6. ⚠️ "2,000+ 模型"与"25 客户端"两条数都来自 README 自述——本次未独立核对；按规矩标 ⚠️，在引用时建议加"据仓库自述"。
  7. ⚠️ --client 名字串大小写敏感——openclaw / OpenClaw / OPENCLAW 的行为 README 没有断言；做集成测试时统一小写更稳。

6. 与同类对比

  • vs 通用 LLM 网关（如 OpenRouter / LiteLLM / Portkey）：那些是"把多家 LLM 路由到一个 key"。SandBase 同时覆盖 LLM + 数据 API + 图像/视频/语音生成 + 社媒，并自带 OAuth + rollback + MCP 桥一次性分发到 25 客户端。代价是定价不透明、单点依赖。
  • vs 单客户端 MCP 配置（如直接给 Cursor 写 mcp.json）：直接写配置 = 每个客户端一份、手动维护 key；SandBase = 一次授权、25 客户端共享，但损失对每个 MCP server 的细粒度控制。
  • vs 自托管 agent runtime（SandBase 自己的 sandbase-harness / 其他 OSS 替代）：harness 是服务器端长跑 + 会话 + 审计；cli 是本机 MCP 桥 + 一次性 OAuth 流程。两者不是竞争关系，README 里用 connect 互相衔接。
  • vs Awesome 系列收录的"AI 网关"项目：很多是只列入口的 awesome 列表；SandBase CLI 是已经能跑的二进制 + MCP server，在功能上更接近 zai-org/CLI、Composio 的产品形态——但账号模型和 OAuth 流程仍有差异，未做盲测。

7. 一句话推荐结论

想给本地 AI 编程助手一次性"补全数据 + 模型 + 多模态"三件套又不想管 API key，就跑 npx -y @sandbaseai/cli@latest connect；如果你在意每次调用的价格，先用 inspect 看一眼 base_price 再放手让 agent 跑——v0.3.6 是这次最新，OKR 路径清晰，但 "2,000+ 模型 / 25 客户端"这类自述数字建议落地前自己抽样核一次。