OpenClaw 综合配置

融合 OpenClaw 官方 New API 配置、自定义中转站、CC Switch 和多渠道机器人接入。

本页将青云 TOP API 客户端接入资料按使用场景合并整理，适合第一次接入的用户，也适合需要核对协议和路径的 API 开发者。青云 TOP API 基于 New API 部署，因此 New API 官方应用教程中的兼容配置可以直接复用。

快速判断：我应该看哪一段？

只想聊天：先看桌面端的基础配置。
要接入 MCP、知识库或工作流：看 Agent/自动化章节。
要在终端写代码：看 CLI、Provider 和环境变量章节。
遇到 401、403、404 或模型不兼容：先检查本文末尾的接入检查清单，再查看对应来源章节。

OpenClaw（融合自原文档）

OpenClaw 教程 — 安装 OpenClaw、对接青云 TOP API，快速搭建自托管 AI 助手。开源项目，支持 Telegram、Discord、WhatsApp 等多渠道集成。

项目介绍

OpenClaw 是一个开源、自托管的个人 AI 助手平台，将消息应用连接到运行在你自己硬件上的 AI 代理。专为开发者和高级用户设计，无需交出数据控制权即可拥有自主 AI 助手。

官方主页：https://openclaw.ai
项目文档：https://docs.openclaw.ai
GitHub：https://github.com/openclaw/openclaw

OpenClaw 完全开源，你可以在 OpenClaw 的 GitHub 仓库浏览源码、提交 Issue 或参与贡献。本教程涵盖安装、配置，以及将 OpenClaw 对接青云 TOP API 的完整步骤。

🌟 核心特性

多渠道集成

多渠道集成：支持 Telegram、Discord、WhatsApp、iMessage 等多种消息渠道，也可通过插件扩展更多平台
单一网关：通过一个 Gateway 进程统一管理所有渠道
语音支持：支持 macOS/iOS/Android 语音交互
Canvas 界面：可渲染交互式 Canvas 界面

自托管与数据安全

完全自托管：运行在你自己的机器或服务器上
开源透明：MIT 开源协议，代码完全透明
数据本地化：上下文和技能存储在你的本地计算机，而非云端

智能代理能力

持续运行：支持后台常驻运行，拥有持久记忆
计划任务：支持 cron 定时任务
会话隔离：按代理/工作区/发送者隔离会话
多代理路由：支持多代理协同工作
工具调用：原生支持工具调用和代码执行

📦 接入前准备

准备信息

Node.js 22 或更高版本
一个可用的青云 TOP API 地址（通常以 /v1 结尾）
一个可用的青云 TOP API API Key
请使用您自己部署的青云 TOP API，或确认服务方具备合法上游授权和合规义务的青云 TOP API 服务。不要将来源不明的 API 地址或密钥接入生产环境。

在开始接入青云 TOP API 之前，建议先按 OpenClaw 官方当前推荐流程把 Gateway 和 Control UI 跑起来。这样后续排查问题时，更容易区分是 OpenClaw 本身未启动，还是模型提供商配置有误。

1\. 安装 OpenClaw（macOS/Linux）

curl -fsSL https://openclaw.ai/install.sh | bash

其他安装方式可参考 OpenClaw 官方文档：Getting Started。

2\. 运行引导向导

openclaw onboard --install-daemon

该向导会完成基础认证、Gateway 设置，以及可选的渠道初始化。这里的目标是先把 OpenClaw 跑起来，后面再把默认模型切到青云 TOP API。

3\. 检查 Gateway 与 Control UI

openclaw gateway status

openclaw dashboard

如果浏览器能打开 Control UI，说明 OpenClaw 基础运行已经正常。这个阶段不需要先配置 Telegram、Discord、飞书等消息渠道。

4\. 定位配置文件

OpenClaw 的配置文件通常位于 ~/.openclaw/openclaw.json，你可以在引导向导生成的基础上继续修改。

路径相关环境变量

如果你把 OpenClaw 跑在专用服务账号下，或希望自定义配置/状态目录，可以使用：

OPENCLAW_HOME
OPENCLAW_STATE_DIR
OPENCLAW_CONFIG_PATH

详细说明见官方环境变量文档：Environment Variables。

🚀 使用青云 TOP API 作为模型提供商

OpenClaw 支持通过 models.providers 接入自定义或兼容 OpenAI 接口的模型网关。对于青云 TOP API，最常见的做法是把它作为一个自定义 provider 加进配置里，再把默认模型指向 青云 TOP API/模型ID。

接入思路

在 models.providers 下声明一个 青云 TOP API provider
将 baseUrl 指向你的青云 TOP API 地址，并确保包含 /v1
将 api 设为 openai-completions
在 models 中列出你希望 OpenClaw 使用的模型 ID
在 agents.defaults.model.primary 中把默认模型切到 青云 TOP API/...

推荐做法：用环境变量保存密钥

先在当前 shell、服务环境，或 OpenClaw 可读取的 .env 中提供你的青云 TOP API 密钥：

export NEWAPI_API_KEY="$QINGYUN_TOP_API_KEY"

然后在 openclaw.json 里补充或修改以下片段：

{
  models: {
    mode: "merge",
    providers: {
      QINGYUN_TOP_API_KEY=$QINGYUN_TOP_API_KEY
        baseUrl: "https://top.qingyuntop.ai/v1",
        apiKey: "${NEWAPI_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gemini-2.5-flash", name: "Gemini 2.5 Flash" },
          { id: "kimi-k2.5", name: "Kimi K2.5" },
        ],
      },
    },
  },

  agents: {
    defaults: {
      model: {
        primary: "青云 TOP API/gemini-2.5-flash",
        fallbacks: ["青云 TOP API/kimi-k2.5"],
      },
      models: {
        "青云 TOP API/gemini-2.5-flash": { alias: "flash" },
        "青云 TOP API/kimi-k2.5": { alias: "kimi" },
      },
    },
  },
}

这不是一份必须原样照抄的完整配置，而是接入青云 TOP API 最关键的部分。只要 provider、模型 ID 和默认模型引用对应正确，OpenClaw 就能通过青云 TOP API 调用你暴露出来的模型资源。

关键配置说明

配置项

说明

models.mode

建议设为 merge，在保留 OpenClaw 内置 provider 的同时追加 青云 TOP API

models.providers.青云 TOP API.baseUrl

你的青云 TOP API 地址，通常需要带上 /v1

models.providers.青云 TOP API.apiKey

青云 TOP API 密钥，推荐通过 ${NEWAPI_API_KEY} 注入

models.providers.青云 TOP API.api

对于青云 TOP API 这类 OpenAI 兼容网关，使用 openai-completions

models.providers.青云 TOP API.models

这里列出的模型 ID 必须与你的青云 TOP API 实际暴露的模型名称一致

agents.defaults.model.primary

默认主模型，格式必须是 provider/model-id

agents.defaults.model.fallbacks

备选模型列表，主模型失败时自动切换

agents.defaults.models

可选，用来给模型起别名，方便在 UI 或会话里引用

验证是否接入成功

完成配置后，回到 Control UI 或重新打开：

openclaw dashboard

如果你能在 OpenClaw 中正常发起对话，并且默认模型已经变成 青云 TOP API/...，说明接入成功。你也可以使用：

openclaw models list

确认 青云 TOP API/ 前缀的模型已经出现在可选列表中。

常见问题

baseUrl 没带 /v1：这是最常见的接入错误之一。
模型 ID 填错：primary 和 fallbacks 必须与 models.providers.青云 TOP API.models 里的 id 对应。
密钥只在当前终端生效：如果 Gateway 以后台服务运行，请确保服务进程也能读取 NEWAPI_API_KEY。
想前台排障：可使用官方前台运行方式 openclaw gateway --port 18789 观察日志与报错。

接入检查

API 地址填写青云 TOP API 的 Base URL：https://top.qingyuntop.ai/v1；应用若要求不带 /v1 的站点地址，请按页面说明填写对应格式。
API Key 只使用环境变量 $QINGYUN_TOP_API_KEY 或应用的安全密钥存储，不要把真实密钥提交到代码仓库。
模型名称必须与控制台可用模型完全一致；遇到 401/403 检查密钥、分组和模型权限，遇到 404 检查 Base URL 是否重复填写 /v1。

OpenClaw 配合 CC Switch（融合自原文档）

OpenClaw配合CC switch自定义中转站配置

第一步：安装CC switch

\\下载CC Switch并安装

下载地址：下载CC Stitch

配置CC Switch

添加供应商（中转站）

添加供应商（中转站）信息

API端点：https://top.qingyuntop.ai/v1

选择添加

同时可以选择设置为默认渠道

第二步：安装openclaw与基础初始化

首先确保你已经安装了 Node.js 环境，然后在终端执行：

全局安装：

执行引导（根据提示完成基础设置）：

caht配置引导示例
红框标注的地方为需要选择的地方

第三步：检查并启动

启动 Gateway 服务：

访问控制台：
打开浏览器访问 http://127.0.0.1:18789/

接入检查

API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

OpenClaw 最新版自定义中转站（融合自原文档）

OpenClaw 最新版本自定义中转站配置教程

第一步：安装与基础初始化

首先确保你已经安装了 Node.js 环境，然后在终端执行：

全局安装：

执行引导（根据提示完成基础设置）：

第二步：修改主配置文件 `clawdbot.json`

打开路径：C:\Users\admin\.openclaw\openclaw.json
将 models 和 auth 部分修改为以下内容，以支持自定义中转站。

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "api-proxy-claude/claude-sonnet-4-5-20250929"
      },
      "models": {
        "api-proxy-gpt/gpt-5.2": {
          "alias": "GPT-5.2"
        },
        "api-proxy-claude/claude-sonnet-4-5-20250929": {
          "alias": "Claude Sonnet 4.5"
        },
        "api-proxy-google/gemini-3-pro-preview": {
          "alias": "Gemini 3 Pro"
        },
        "api-proxy-deepseek/deepseek-v3.2": {
          "alias": "Deepseek v3.2"
        }
      },
      "workspace": "C:\\Users\\admin\\clawd",
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "auth": {
    "profiles": {
      "api-proxy-gpt:default": {
        "provider": "api-proxy-gpt",
        "mode": "api_key"
      },
      "api-proxy-claude:default": {
        "provider": "api-proxy-claude",
        "mode": "api_key"
      },
      "api-proxy-google:default": {
        "provider": "api-proxy-google",
        "mode": "api_key"
      },
      "api-proxy-deepseek:default": {
        "provider": "api-proxy-deepseek",
        "mode": "api_key"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "api-proxy-gpt": {
        "baseUrl": "https://top.qingyuntop.ai/v1",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.2",
            "name": "GPT-5.2",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      },
      "api-proxy-claude": {
        "baseUrl": "https://top.qingyuntop.ai/dashboard/",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      },
      "api-proxy-google": {
        "baseUrl": "https://top.qingyuntop.ai/v1",
        "api": "google-generative-ai",
        "models": [
          {
            "id": "gemini-3-pro-preview",
            "name": "Gemini 3 Pro",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 2000000,
            "maxTokens": 8192
          }
        ]
      },
      "api-proxy-deepseek": {
        "baseUrl": "https://top.qingyuntop.ai/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-v3.2",
            "name": "Deepseek v3.2",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 2000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

第三步：配置鉴权文件 `auth-profiles.json`

打开路径：C:\Users\admin\.openclaw\agents\main\agent\auth-profiles.json
在此处填入你从中转站获取的真实 API Key。

{
  "version": 1,
  "profiles": {
    "api-proxy-gpt:default": {
      "type": "api_key",
      "provider": "api-proxy-gpt",
      "API_KEY" : "$QINGYUN_TOP_API_KEY"
    },
    "api-proxy-claude:default": {
      "type": "api_key",
      "provider": "api-proxy-claude",
      "API_KEY" : "$QINGYUN_TOP_API_KEY"
    },
    "api-proxy-google:default": {
      "type": "api_key",
      "provider": "api-proxy-google",
      "API_KEY" : "$QINGYUN_TOP_API_KEY"
    },
    "api-proxy-deepseek:default": {
      "type": "api_key",
      "provider": "api-proxy-deepseek",
      "API_KEY" : "$QINGYUN_TOP_API_KEY"
    }
  }
}

第四步：检查并启动

启动 Gateway 服务：

访问控制台：
打开浏览器访问 http://127.0.0.1:18789/

接入检查

API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

OpenClaw（融合自原文档）

本页按照“准备运行时 → 创建令牌 → 写入 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 和聊天平台。

统一接入检查与故障排查

401/403：确认 API Key 未过期、令牌分组允许目标模型，且没有把示例占位符原样提交。
404：核对应用要求的 Base URL 形式；https://top.qingyuntop.ai/dashboard/、https://top.qingyuntop.ai/v1 和完整路径不能重复拼接。
模型为空或不可用：调用 GET /v1/models，复制返回的完整模型 ID，并确认应用使用的协议（OpenAI Chat Completions、Responses 或 Anthropic Messages）。
切换 Provider 后仍访问旧地址：完全退出并重启客户端，检查环境变量、代理和 CC Switch 路由是否覆盖了新配置。
生产环境安全：不要把真实密钥放进前端代码、截图、公开仓库、Deep Link 或工作流导出文件；先用低额度测试令牌验证。

> 本页保留每个来源教程的具体字段、命令、截图和高级选项；重复的 API Key、Base URL 和验证说明已统一到本页开头与本节。

发布前检查

以下检查适用于客户端中选择 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 判定成功。

快速判断：我应该看哪一段？

OpenClaw（融合自原文档）

🌟 核心特性

多渠道集成

自托管与数据安全

智能代理能力

📦 接入前准备

1\. 安装 OpenClaw（macOS/Linux）

2\. 运行引导向导

3\. 检查 Gateway 与 Control UI

4\. 定位配置文件

🚀 使用 青云 TOP API 作为模型提供商

接入思路

推荐做法：用环境变量保存密钥

关键配置说明

验证是否接入成功

常见问题

接入检查

OpenClaw 配合 CC Switch（融合自原文档）

OpenClaw配合CC switch自定义中转站配置

第一步：安装CC switch

第二步：安装openclaw与基础初始化

第三步：检查并启动

接入检查

OpenClaw 最新版自定义中转站（融合自原文档）

OpenClaw 最新版本 自定义中转站配置教程

第一步：安装与基础初始化

第二步：修改主配置文件 clawdbot.json

第三步：配置鉴权文件 auth-profiles.json

第四步：检查并启动

接入检查

OpenClaw（融合自原文档）

统一接入检查与故障排查

发布前检查

🚀 使用青云 TOP API 作为模型提供商

OpenClaw 最新版本自定义中转站配置教程

第二步：修改主配置文件 `clawdbot.json`

第三步：配置鉴权文件 `auth-profiles.json`