OpenClaw | 青云TOP API 文档

安装 OpenClaw，配置青云TOP API Provider、默认模型与最小工具权限。

本页按照“准备运行时 → 创建令牌 → 写入 Provider → 设为默认模型 → 本地对话”的顺序配置，命令适用于 OpenClaw 2026.7.1-2。

第一步：检查 Node.js 与 OpenClaw

参考 OpenClaw 官方安装说明安装客户端。安装前先检查版本：

node --version
openclaw --version

OpenClaw 2026.7.1-2 要求 Node.js >=22.22.3 <23、>=24.15.0 <25 或 >=25.9.0。如果默认 Node.js 不符合要求，请用版本管理器为 OpenClaw 单独选择兼容版本，不要替换其他项目的系统运行时。

第二步：创建专用 API 密钥并确认模型

登录青云TOP API 控制台并打开“令牌管理”。
新建一个只供 OpenClaw 使用的令牌。
选择需要的模型分组。
使用同一令牌请求 /v1/models，复制准确的模型 ID。

export QINGYUN_TOP_API_KEY="你的 青云TOP API API 密钥"

curl "https://top.qingyuntop.ai/v1/models" \
  -H "Authorization: Bearer $QINGYUN_TOP_API_KEY"

下文以 gpt-4o-mini 与 openai-completions 为例。只有模型明确支持 /v1/responses 时，才选择 openai-responses。

第三步：选择配置方式

方法 A：使用 CC Switch

在 CC Switch 顶部选择 OpenClaw。
点击“添加供应商”→“自定义配置”。
API 协议选择 OpenAI Completions。
API 端点填 https://top.qingyuntop.ai/v1，再填入 OpenClaw 专用青云TOP API 密钥。

CC Switch OpenClaw 分支中的青云TOP API Provider 配置

CC Switch 中填写青云TOP API OpenClaw Provider；密钥保持掩码

点击“添加模型”，填写 /v1/models 实际返回的模型 ID。下图使用 gpt-4o-mini 演示字段位置，输入类型保持 text；你的账户应使用实际返回的模型 ID。

在 OpenClaw Provider 中添加青云TOP API 模型并设为默认模型

保存 Provider 后，先点击“添加”写入 OpenClaw 配置，再点击“设为默认”。界面显示“当前默认”和“已设为默认模型”后，才进入下一步验证。

CC Switch 已将青云TOP API 设为 OpenClaw 默认 Provider

青云TOP API Provider 已写入 OpenClaw 并设为默认

第四步：手工打开配置文件（方法 B）

OpenClaw 默认读取：

~/.openclaw/openclaw.json

如果文件已经存在，只合并下面的青云TOP API Provider、默认模型和工具配置；不要覆盖已有 Agent、Gateway 或外部渠道。

第五步：添加青云TOP API Provider

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "青云TOP API/gpt-4o-mini"
      }
    }
  },
  "tools": {
    "profile": "minimal"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "青云TOP API": {
        "baseUrl": "https://top.qingyuntop.ai/v1",
        "apiKey": "${QINGYUN_TOP_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4o-mini",
            "name": "青云TOP API gpt-4o-mini",
            "input": ["text"]
          }
        ]
      }
    }
  }
}

配置要点：

baseUrl 填 https://top.qingyuntop.ai/v1，不要追加具体接口路径。
apiKey 引用环境变量，不把真实密钥写入配置文件。
mode: "merge" 保留客户端已有 Provider。
默认模型使用 青云TOP API/模型ID 格式。
首次配置先保持 tools.profile: "minimal"，避免把工具调用兼容性与基础对话混在一起排查。

第六步：检查并启用配置

openclaw config validate

校验通过后，完全退出旧的 OpenClaw 进程，再从已经导出 QINGYUN_TOP_API_KEY 的终端重新启动。环境变量只对当前终端及其子进程生效。

第七步：发送第一条本地消息

openclaw agent \
  --local \
  --agent main \
  --model 青云TOP API/gpt-4o-mini \
  --message "Reply with exactly OK" \
  --json \
  --timeout 30

成功时，JSON 输出应包含 Provider、模型、最终回复和成功状态，例如：

provider=青云TOP API api=openai-completions model=gpt-4o-mini
POST https://top.qingyuntop.ai/v1/chat/completions
status=200 content-type=text/event-stream
finalAssistantVisibleText=OK
stopReason=stop result=success

必须同时看到 result=success 和最终回复正文。只有 HTTP 200，但没有可见回复，不能算配置完成。

第八步：逐项开启工具与渠道

普通文本会话成功后，再按需调整 tools.profile，并逐项验证文件、命令、浏览器等工具。Gateway、Telegram、Discord 等外部渠道需要独立 Bot Token 或账号授权，不要与 Provider 首次配置同时进行。

常见问题

运行时版本不受支持：为 OpenClaw 单独切换兼容的 Node.js 版本。
提示 401：确认密钥已注入启动 OpenClaw 的同一个进程。
提示 404：检查模型 ID、Base URL 和 api 适配器，避免出现 /v1/v1。
HTTP 200 但 `incomplete_turn`：恢复 tools.profile: "minimal" 验证纯文本，再逐项启用工具。
配置有效但没有发起请求：本地 Agent 命令同时指定 --agent main 和模型。
外部消息不返回：先回到本地 Agent 验证 Provider，不要同时排查 Gateway 和聊天平台。

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。