从零配置 OpenClaw

准备（Preparation） ​

本页适用于能明确提供 OpenAI Responses 或 OpenAI Chat Completions 协议的上游。预计 10 分钟；准备 CC Switch v3.20.0、OpenClaw 和专用 Key。模型目录不是协议探测器：一个 ID 出现在 /v1/models 不表示它适合任意 api 适配器。

下载（Download） ​

从 OpenClaw 官方仓库 安装。官方 Windows 安装方式与其他系统命令请以仓库 README 为准；也可使用 npm install -g openclaw@latest --allow-scripts=openclaw。CC Switch 必须从 v3.20.0 Release 获取。打开已安装的 CC Switch，进入 关于，确认显示 v3.20.0；若实际版本不一致，先停止，不要继续配置。安装后运行 openclaw --version；只有命令成功并打印版本号才继续，失败时先检查受支持的 Node.js 版本和 PATH。

首次启动（First launch） ​

运行 OpenClaw 官方 onboarding，例如 openclaw onboard --install-daemon，完成其自身引导后退出。不要在 OpenClaw 或 daemon 正在写配置时保存 CC Switch Provider。

API Key 与分组（API Key and group） ​

为 OpenClaw 创建独立 Key，并选择允许目标模型、端点和所需能力的分组。仅保存 Key 标签和创建时间；完整 Key 不应进入 Git、截图或聊天记录。

模型目录：GET /v1/models ​

用这把 Key 执行 GET https://suoxie.codes/v1/models，将返回 data[].id 中的精确值记为 <MODEL_FROM_V1_MODELS>。下文的 <API_KEY> 只是说明应输入哪一把 Key；真实值通过隐藏提示临时进入环境变量，不写入命令历史。

$secureKey = Read-Host "API key" -AsSecureString
$credential = [System.Net.NetworkCredential]::new("", $secureKey)
$env:SUOXIE_API_KEY = $credential.Password
try {
  curl.exe --fail-with-body https://suoxie.codes/v1/models `
    -H "Authorization: Bearer $env:SUOXIE_API_KEY"
}
finally {
  Remove-Item Env:SUOXIE_API_KEY
  Remove-Variable secureKey, credential
}

read -rsp "API key: " SUOXIE_API_KEY
printf '\n'
export SUOXIE_API_KEY
curl --fail-with-body https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"
unset SUOXIE_API_KEY

在 CC Switch 配置 Provider ​

选择 OpenClaw，新增 provider suoxie-openai。Base URL 为 https://suoxie.codes/v1，填入专用 Key 和 <MODEL_FROM_V1_MODELS>。在 api 中显式选择与上游匹配的 openai-responses 或 openai-completions，不要让名称或模型列表替你猜协议。点击保存只会增量更新 JSON5 文件 ~/.openclaw/openclaw.json 的 models.providers；它不会同时修改 agents.defaults.model.primary，因此保存不等于已经设为默认。

{
  models: {
    providers: {
      "suoxie-openai": {
        baseUrl: "https://suoxie.codes/v1",
        apiKey: "<API_KEY>",
        api: "openai-responses",
        models: [
          { id: "<MODEL_FROM_V1_MODELS>", name: "<MODEL_FROM_V1_MODELS>" }
        ]
      }
    }
  }
}

模型映射与协议（Model mapping and protocol） ​

Provider/model 映射是 suoxie-openai/<MODEL_FROM_V1_MODELS>，默认模型必须精确指向它。只有上游接受所选 api 和该模型 ID 时配置才成立；CC Switch 的本地代理转换不是通用兼容层。OpenClaw 原生 openai/* OAuth 路径与自定义 Base URL/Key 是不同路线，不要混用。

保存、启用与重启（Save, enable, and reload） ​

先保存 Provider，并用 openclaw models list 确认 suoxie-openai/<MODEL_FROM_V1_MODELS> 已进入目录。然后在该 Provider 卡片点击 设为默认 并选择该模型；也可以在终端执行 openclaw models set suoxie-openai/<MODEL_FROM_V1_MODELS>。这一步才会更新 agents.defaults.model.primary。重启 OpenClaw 或重新加载 daemon，再用 openclaw models status 确认 primary 指向该完整 provider/model；若不一致，不要发送首个请求。

第一个请求（First request） ​

只有在卡片或 openclaw models set 已设为默认、且 openclaw models status 显示正确 primary 后，才发送 Reply with OK。成功是得到短文本、当前模型仍为该 provider/model，并可在用量页看到同一 Key 的记录。401、403、404 或协议错误时先停止重试，按错误表逐项验证。

Key 用量（Key usage） ​

在 Key 用量 用时间、Key、分组、端点、真实模型筛选，核对请求数、Token 和费用。记录缺失时刷新并放宽时间范围，不要用重复请求制造额外费用。

错误处理（Errors） ​

回滚与安全（Rollback and security） ​

先恢复旧 Provider/默认模型并完成短请求，再移除 models.providers.suoxie-openai 和本次 primary 指向，或恢复 CC Switch 在 backups/openclaw 创建的 JSON5 备份。不要修改或导出其他 provider 的凭据；若正式凭据已泄露，应另行轮换。确认旧 Provider 路径的短请求正常后，最后撤销本轮临时测试 Key。若这里配置的是仍在使用的正式专用 Key，应继续保留它，只撤销本轮临时测试 Key，不影响正在使用的正式 Key。