梭子蟹API 文档
用量
立即开始
Base URLhttps://suoxie.codes/v1

辅助接入

Cockpit Tools

用 Cockpit Tools 为 Grok CLI 配置第三方 API/custom upstream 并验证启动。

先了解这条接入路径 ​

Cockpit Tools 是本地桌面账号管理工具。本页只讲 Grok CLI 账号的第三方 OpenAI-compatible API：你在 Cockpit Tools 中保存 Base URL、API Key 和 Model ID，它为该账号建立独立的 GROK_HOME，把配置写入该账号专属的 config.toml，并在启动对应的 Grok CLI 进程时注入 Key。

本页不讲 OAuth 登录、auth.json 导入、普通账号导入、本地 Codex API Service 或多实例编排。看到的菜单和字段如果与当前版本不同，请以官方项目文档为准，不要把 API Key 填进不确定的入口。官方项目：cockpit-tools。

下载前准备 ​

先准备以下内容：

  1. 一台可以运行 Cockpit Tools 的电脑，以及一个已登录、可用的梭子蟹账户。
  2. 一把单独、可撤销、有限额的专用 API Key。前往创建 API Key，不要复用生产脚本或其他客户端的 Key。
  3. 一个私密的终端。不要在共享屏幕、工单、截图或公共电脑上输入完整 Key。
  4. 一个可回滚的备份位置。只备份你理解的账号配置，并放在 Git、云盘同步目录和共享文件夹之外。

判断 Windows CPU 架构 ​

v1.3.22 的 Windows 安装包只提供 x64。在 Windows 11 或 Windows 10 中打开 设置 > 系统 > 系统信息，查看“系统类型”：

  • 基于 x64 的处理器：可以继续使用本页的 Windows 安装包。
  • 基于 ARM64 的处理器 或其他类型：本页没有可核验的 Windows 安装包，不要强行安装 x64；请等待官方提供匹配资产或改用官方资料支持的平台。

也可以在 PowerShell 中运行下面这条不含密钥的检查命令。这里读取的是处理器系统类型，而不是只能说明系统位数的 OSArchitecture：

powershell
(Get-CimInstance Win32_ComputerSystem).SystemType

只有输出包含 x64-based PC 才能按本页继续；若显示 ARM64-based PC 或其他值就停止。Windows 是 64 位并不能证明处理器一定是 x64。

下载并安装 v1.3.22 ​

只从官方 v1.3.22 Release下载。该 Release 的 Windows x64 安装资产名称是：

  • Cockpit.Tools_1.3.22_x64-setup.exe
  • Cockpit.Tools_1.3.22_x64_en-US.msi

两者都是 Windows x64 安装器；选一个即可，不要同时安装或从镜像站下载。下载后核对文件名和 Release 页面，不要把 .sig 签名文件当作安装器。若浏览器或安全软件提示风险，先确认下载地址确实是 github.com/jlcodes99/cockpit-tools，不要绕过安全检查去运行来源不明的副本。

Cockpit Tools v1.3.22 official GitHub Release page
v1.3.22 官方 Release 页面示例。截图只用于确认版本和下载入口，不展示 Grok CLI API Key 表单或任何凭据。

Windows 安装与首次启动 ​

  1. 退出正在运行的 Grok CLI，并保存你需要回滚的旧配置。
  2. 双击上面下载的 .exe，或用 Windows Installer 打开 .msi。按安装器提示完成安装；不要把 Key 粘贴到安装器或备注字段。
  3. 从开始菜单启动 Cockpit Tools。首次启动只确认应用能打开、Grok CLI 路径能被识别；不要在还没完成 cURL 基线时反复启动请求。
  4. 如果 Grok CLI 未被识别，先在 Cockpit Tools 的设置中按当前界面提示选择已安装的可执行文件；不要修改 API 字段来掩盖路径问题。

官方 README 将 macOS、Windows 和 Linux 列为支持平台。v1.3.22 Release 同时列出 macOS 的 x64、aarch64、universal 资产，以及 Linux 的 aarch64 AppImage、DEB 和 RPM 资产；本页不替这些平台补写未经核验的安装步骤。macOS/Linux 用户请按同一官方 Release 的资产、架构和系统权限说明操作，找不到匹配资产时停止，不要把 Windows 安装器用于其他系统。

先创建 Key，再建立 cURL 基线 ​

在 Cockpit Tools 之前先用同一把专用 Key 验证 API。打开 cURL 教程，依次确认：

  1. GET https://suoxie.codes/v1/models 返回 HTTP 200，并从同一 Key 的返回值复制一个精确 Model ID。
  2. POST https://suoxie.codes/v1/responses 的最小请求返回 HTTP 200、status: completed 和模型回复。

Windows PowerShell 的安全输入方式 ​

不要把真实 Key 写在命令行、脚本或会被记录的命令历史中。先在当前 PowerShell 会话中安全输入，下面的命令本身不包含 Key：

powershell
$secureKey = Read-Host 'API key' -AsSecureString
$keyPtr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureKey)
try { $env:SUOXIE_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($keyPtr) }
finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($keyPtr) }

然后使用 cURL 教程中的请求命令，但跳过其中的 Key/变量初始化步骤。保留当前 PowerShell 会话中已经安全设置的 $env:SUOXIE_API_KEY，直接从第一条请求 GET https://suoxie.codes/v1/models 开始；取得 Model ID 后，只在同一会话中设置 $env:SUOXIE_MODEL 并运行最小请求。把返回的 Model ID 只保存在当前会话变量或私密笔记中。验证完成后清除环境变量：

powershell
Remove-Item Env:SUOXIE_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:SUOXIE_MODEL -ErrorAction SilentlyContinue

macOS/Linux 可在私密终端使用 read -s 安全设置当前 shell 的临时 SUOXIE_API_KEY。参照 cURL 教程时，跳过其中的 API Key/环境变量初始化步骤，保留并复用当前 shell 中已安全设置的 SUOXIE_API_KEY，直接从第一条请求 GET https://suoxie.codes/v1/models 开始；不要把 export SUOXIE_API_KEY='<真实 Key>' 写入 shell 历史、启动脚本或共享配置。两项 cURL 基线都通过后，再继续配置 Cockpit Tools；否则先按 常见错误处理 API、分组、余额或网络问题。

在 Cockpit Tools 配置一个 Grok CLI API Key 账号 ​

当前版本的字段名称可能改变，下面按含义说明。只有当界面明确显示 Grok CLI 的 API Key / 第三方 API / custom upstream 路径时，才继续：

字段填写值说明
Base URLhttps://suoxie.codes/v1填到 /v1 为止，不要再拼接 /responses 或 /chat/completions。
API Key<API_KEY>这里只是占位符；粘贴你刚刚完成 cURL 基线的专用 Key。
Model ID<MODEL_FROM_V1_MODELS>填同一把 Key 的 /v1/models 返回的精确 ID，区分大小写。

不要把上表字段填入 OAuth、Token/JSON 导入或普通账号登录表单。官方资料没有 Grok API Key 表单截图；本节的字段表和文字才是配置依据。

按以下顺序操作：

  1. 在 Cockpit Tools 中新增或编辑一个 Grok CLI API Key 账号，选择第三方 API 或 custom upstream 模式。
  2. 填写 Base URL、API Key 和 Model ID；其他代理、端口或账号不要同时修改。
  3. 点击当前界面的“保存”或等价操作，确认没有保存错误。不要把 Key 写进公共脚本、日志、截图或共享模板。
  4. 确认该账号已“启用”或被选为当前启动账号。若当前版本没有启用开关，只启动你刚保存的这一个账号，不要猜测隐藏菜单。
  5. API Key 账号应使用独立的 GROK_HOME。Cockpit Tools 会把该账号的 config.toml 放在对应的专属目录，避免官方 OAuth 的 ~/.grok/auth.json 抢先生效；不要手动把两个账号的目录合并。
  6. 完全退出 Cockpit Tools 和由它启动的 Grok CLI，再重新打开并重启这个账号。只关闭窗口而进程仍在托盘运行时，可能没有重新读取配置。
  7. 发送一条简短的文本请求，不要先加载大型项目或复杂工具。请求完成后立即核对 Key 用量。

核对 Key 用量与成功标志 ​

打开Key 用量，按请求时间、Key、Model ID 和端点核对：

  • cURL 基线和 Cockpit Tools 使用的是同一把 Key、同一个 Model ID、同一个 https://suoxie.codes/v1。
  • Cockpit Tools 重启后确实启动了目标 Grok CLI 账号，而不是旧的 OAuth 账号或其他 GROK_HOME。
  • 最小请求成功，使用记录出现对应请求；不要把 Cockpit 的本地配额卡片当成梭子蟹 Key 用量记录。

若没有记录，先停止重复请求，确认进程、Key、模型和端点，再查常见错误。

常见错误 ​

现象先检查
安装器无法运行Windows 是否为 x64；下载文件名和 Release 标签是否为 v1.3.22；不要在 ARM64 上强行运行 x64。
看不到 API Key / custom upstream 字段当前版本是否真的提供 Grok CLI 第三方 API 路径；若只有 OAuth 或 JSON 导入，停止并查官方文档。
401 或认证失败用同一 Key 重跑 cURL，检查 Bearer Key 是否完整、是否已撤销、是否有空格。
403 或模型不存在用同一 Key 重新读取 /v1/models，确认分组/权限和精确 Model ID，不要猜模型名。
cURL 成功但 Grok CLI 失败检查该账号的 Base URL、Model ID、代理和 custom upstream 覆盖顺序；一次只改一个字段，然后完全重启。
启动了错误账号确认当前选中的账号、账号专属 GROK_HOME 和 config.toml，关闭旧进程后再启动。
用量与预期不符停止重试，按实际 Key、模型、端点过滤Key 用量；不要只看 Cockpit 的配额摘要。

回滚到已知可用状态 ​

  1. 停止受影响的 Grok CLI 进程，并确认它已经退出。
  2. 在 Cockpit Tools 中取消启用该 API Key 账号，切回之前可用的 Provider/账号，或恢复你保存的配置副本。
  3. 完全重启 Cockpit Tools 和 Grok CLI，再用原来的最小请求验证。
  4. 如果同一把 Key 的 cURL 也失败，停止修改 Cockpit Tools，先修复 API 基线。
  5. 确认不再需要该专用 Key 后，再到本站撤销它；撤销前不要让任何进程继续使用它。

凭据安全边界 ​

  • API Key 账号使用独立 Key、独立 GROK_HOME 和独立 config.toml；不要与 OAuth 账号或其他客户端共用目录。
  • 官方 README 说明 Grok CLI 的 access token 和 refresh token 可能以明文 JSON 保存在本机 ~/.grok/auth.json。不要上传、共享或把它当作安全备份；Windows 应将其留在个人用户目录，并限制其他用户读取。
  • 不要把完整 Key、auth.json、账号专属 config.toml、环境变量导出、终端截图或日志放入 Git、云盘共享、工单、聊天或公共设备。
  • 不使用 WebSocket 集成时将其关闭；默认本地地址 127.0.0.1:19528 不应暴露到公网或不受信任的局域网。
  • 共享电脑操作结束后，清除临时环境变量和剪贴板；发现 Key 泄露时立即在本站撤销并重新建立 cURL 基线。

完成一次稳定的第三方 API 启动后，再查看Key 用量和上线前检查。账号导入、OAuth、Token/JSON 和多实例功能请回到 Cockpit Tools 官方文档核对。