你是不是也遇到过这种情况：
AI 接口时好时坏、切换供应商就要改代码、多个 Key 分散在各处，调试时还看不到统一日志。

这不是你“配置能力不够”，而是架构层缺了一层“本地网关”。
一旦补上这层，稳定性、可维护性和扩展性会一起提升。

这篇教程会带你用 OpenClaw + CC Switch 搭建一个可长期复用的本地 AI 中转架构。
目标很明确：一次配置，后续换渠道不改业务代码。

---

这套方案能解决什么问题？

在项目里直接连官方 API，通常会出现 4 个高频痛点：

• 网络抖动明显：跨境链路不稳，超时和重试增多
• 渠道管理分散：多个供应商 Key 难统一维护
• 切换成本过高：换渠道就要改 base_url、鉴权和环境变量
• 排障效率低：缺少统一日志入口，不容易定位问题

对应地，CC Switch 负责“渠道管理层”，OpenClaw 负责“本地网关层”。
前者管供应商，后者统一对外接口。

如果你还没有稳定渠道，可先准备一个兼容 OpenAI 格式的 Key（例如 88API）。

---

架构先看懂：请求是怎么走的？

业务代码并不直接连外部渠道，而是统一发到本地：

你的应用 -> OpenClaw(127.0.0.1:18789) -> CC Switch 默认供应商 -> 上游模型

这样做的好处是：

1. 业务层只认一个本地地址
2. 渠道切换在 CC Switch 完成
3. OpenClaw 提供统一监控与转发

到这里你可以记住一句话：
OpenClaw 稳定“入口”，CC Switch 稳定“出口”。

---

Step 0：准备清单（2 分钟）

开始前确认这 4 项：

• 已安装 Node.js（建议 >= 18.x）
• 已安装 CC Switch
• 至少一个可用供应商 API Key
• 本机可用端口（示例用 18789）

验证 Node 与 npm：

node -v
npm -v

看到版本号即可继续。

---

Step 1：安装并设置 CC Switch（渠道层）

1.1 下载与安装

从 Release 页面下载安装包：

https://github.com/farion1231/cc-switch/releases

按系统选择对应版本，安装后启动 CC Switch。

1.2 添加自定义供应商

进入 供应商管理，点击“添加供应商”，填写：

• 供应商名称：如 88API中转、备用渠道A
• API Base URL：如 https://api.88api.shop
• API Key：对应渠道密钥

保存后，你会在列表里看到新供应商。

1.3 设置默认渠道（关键）

在供应商列表中选择主用渠道，点击“设为默认”。
这个动作决定 OpenClaw 的默认转发出口。

建议现在就配置一个“备用供应商”。
后面任一渠道异常时，你可以秒切，不影响业务请求。

---

Step 2：安装 OpenClaw 并初始化（网关层）

2.1 全局安装 OpenClaw

npm install -g openclaw@latest

安装完成后验证版本：

openclaw --version

2.2 运行初始化向导

openclaw onboard

根据提示依次完成：

• 选择 Chat 模式
• 选择默认模型
• 关联 CC Switch 的供应商配置

如果某些选项无特殊要求，可直接回车使用默认值。
但涉及渠道映射的步骤，请按你在 CC Switch 中的配置准确填写。

到这里，网关和渠道已经“打通”。

---

Step 3：启动 Gateway 并连通性验证

3.1 启动本地网关

openclaw gateway --port 18789

成功后，OpenClaw 会监听 127.0.0.1:18789。
你的应用后续统一将请求发往这个地址即可。

3.2 打开 Web 控制台

浏览器访问：

http://127.0.0.1:18789/

你可以看到：

• 请求日志
• 渠道状态
• 可用模型列表

这一步建议立刻做一次真实调用，确认日志可见、响应正常。

---

Step 4：在业务代码里使用统一入口

把你原来的上游地址替换为本地网关地址：

base_url = http://127.0.0.1:18789/v1

之后你再切换供应商，只需要在 CC Switch 中改默认渠道。
应用代码和部署配置可以保持不变。

这就是“接口层与业务层解耦”的实际价值。

---

进阶：不重启服务也能动态切换渠道

当主渠道不稳定、模型不可用或成本波动时：

1. 打开 CC Switch
2. 选择另一个供应商
3. 点击“设为默认”

切换会立即生效，OpenClaw 无需重启。

如果你希望减少多账号维护成本，可以把聚合渠道作为主入口（例如 88API），
再保留 1~2 个备用出口，形成“主用 + 兜底”结构。

---

常见问题（FAQ）

Q1：openclaw gateway 提示端口占用怎么办？

换一个端口启动即可：

openclaw gateway --port 18790

并同步更新你应用中的 base_url 端口。

Q2：CC Switch 已添加供应商，但 OpenClaw 识别不到？

先确认 CC Switch 正常运行。
然后重新执行 openclaw onboard，检查渠道映射是否正确。

Q3：接口返回 401，通常是哪类问题？

优先排查 API Key：

• 是否填写错误
• 是否复制了前后空格
• 渠道是否已过期或权限不足

Q4：切换渠道后请求仍走旧渠道？

先看 CC Switch 中“默认供应商”是否真的变更。
再到 OpenClaw 控制台查看最新请求日志，确认路由是否更新。

---

总结：这套组合为什么值得长期用？

你今天完成的不是一次“临时配置”，而是一次可复用的接口架构升级。

核心收益有三点：

• 稳定：本地统一入口，降低外部链路波动影响
• 灵活：渠道切换在 CC Switch 完成，业务代码无感
• 可运维：OpenClaw 控制台让排障和监控更直接

如果你正在做多模型应用、AI 工具链或 SaaS 集成，
建议把这套 OpenClaw + CC Switch 作为默认基建模板。

下一步你可以做两件事：

1. 新增一个备用供应商，验证“故障切换”流程
2. 给团队沉淀一份统一 base_url 规范，避免项目各自为战

当入口统一后，你的迭代速度会明显提升。