企业官网建设流程全解析

OneAPI + OpenClaw 对接实践：从踩坑到跑通

本文记录了一次完整的 OneAPI 网关搭建与 OpenClaw 对接过程，重点整理了过程中遇到的报错、根因分析和解决方案，供后续参考。

一、背景与目标

• 最终架构：OpenClaw（智能体） → OneAPI（统一网关） → 上游模型服务商
• 上游策略：首选智谱免费模型（glm-4-flash），备选阿里云百炼（qwen3.8-flash）兜底
• 部署环境：同一台服务器，OpenClaw 与 OneAPI 均以 Docker 容器部署
• 配置方式：OpenClaw 使用 JSON 格式的配置文件

调用链路图

OpenClaw ──HTTP──▶ OneAPI(网关) ──调度──▶ 智谱(权重高/免费) ◀──主 │ │ │ │ └──故障转移──▶ 百炼(权重低/兜底) ◀──备 │ └──令牌鉴权 + IP限制 + 模型重定向

二、整体踩坑地图（先看这张表）

三、问题与解决方案详解

1. DeepSeek 接入

问题 A：调用返回 402

http status code: 402, error message: Insufficient Balance

• 根因：DeepSeek API 没有永久免费，新号赠送的试用额度消耗完毕，再调用直接返回 402 余额不足。
• 结论：渠道配置本身没错（BaseURL、模型名、Key 都正确），只是账号没钱。
• 处理：充值后即可恢复；未充值时可在 OneAPI 中禁用该渠道，避免客户端轮询调度到它报错。

问题 B：模型名

• 旧的deepseek-chat / deepseek-reasoner已废弃，应使用：

  deepseek-flash,deepseek-v4-pro

• ⚠️ DeepSeek 官方 BaseURL 末尾不要加/v1，与大多数平台不同：

  https://api.deepseek.com

2. Kimi 接入（最容易踩的坑）

报错：

http status code: 404, error message: Not found the model kimi-k3.1-pro or Permission denied http status code: 401, error message: Invalid Authentication

根因一：新旧平台域名混用（最常见）

• 老后台platform.moonshot.cn的老 Key，只能用旧模型kimi-k3
• 新后台platform.kimi.com的新 Key，才能访问kimi-k3.1-pro
• Key 和站点不能混用，否则 404 无权限

根因二：旗舰模型需要充值解锁

• kimi-k3.1-pro / kimi-k3.1-pro-highspeed新账号不充值无权限
• 门槛低、可先测的模型：kimi-k2.7-code-highspeed

正确配置（platform.kimi.com 的 Key）

Base URL: https://api.moonshot.cn/v1 模型: kimi-k3.1-pro,kimi-k3.1-pro-highspeed,kimi-k3,kimi-k2.7-code-highspeed

平台对照表

本次最终验证时，Kimi 三条渠道仍因权限/未充值而失败（见文末截图），因此主线全部切到智谱免费模型。

3. OneAPI 令牌：IP 限制填什么

问题：给 OpenClaw 建令牌时，IP 限制（IP 白名单）该填谁的地址？

结论（一句话记忆）：

谁发请求过来，就填谁的 IP，即「调用方（OpenClaw）」的出网 IP，不是上游服务商 IP，也不是 OneAPI 自身 IP。

分场景：

• OpenClaw 与 OneAPI同机 Docker：本地访问填127.0.0.1；容器互通需查容器网段（docker 默认 bridge 一般是172.17.x.x），但容器重建后 IP 会变，不建议写死。
• OpenClaw 在远程机器：填 OpenClaw 那台机器的公网出口 IP。
• ✅测试阶段强烈建议留空（空 = 不限 IP），避免因容器 IP 变动导致 OpenClaw 突然 403 鉴权失败，等链路跑通稳定后再加固。

4. OpenClaw 容器连不上 OneAPI

问题：配置里写127.0.0.1，OpenClaw 连不上。
根因：容器内的127.0.0.1指向容器自己，访问不到宿主机上另一个 OneAPI 容器。

正确写法（同机 Docker，三选一）

1. 同一 docker 网络，用容器名：http://oneapi:3000/v1
2. 宿主机网关（Linux）：http://172.17.0.1:3000/v1
3. 宿主机内网 IP（实测可用）：http://宿主机内网 IP:3000/v1

结尾必须带/v1；.openclaw配置可写：baseUrl: http://宿主机内网 IP:3000/v1

调试小贴士：

• curl 报URL rejected: No host part in the URL→http://后多打了空格。
• /v1/models裸 curl 返回未提供令牌是正常的，需带鉴权头：

  curlhttp://172.25.33.212:3000/v1/models-H"Authorization: Bearer sk-****"

5. OpenClaw 关键字段：apikey→apiKey（本次最大坑）

现象：日志显示

provider=oneapi ... status=401 rawErrorPreview: "401 未提供令牌"

OpenClaw 发请求时根本没带 Authorization 头。

根因：JSON 里字段名写成了小写apikey，OpenClaw 该版本 schema 要求的是apiKey（K 大写），小写字段被当作无效字段忽略，鉴权头自然丢失。

修复：

- "apikey": "sk-****" + "apiKey": "sk-****"

⚠️ 字段名大小写敏感，这是所有 OpenAI 兼容配置里最隐蔽的坑之一。

6. 自定义 provider 必须声明 models

报错：

Error: Config validation failed: models.providers.oneapi.models: custom model providers must declare models; provider overlays without models are only supported for bundled providers

根因：自定义 OpenAI 兼容网关必须手动声明models数组，内置捆绑 provider 才可省略。

7. 模型对象必须同时有id和name

报错：

models.providers.oneapi.models.0.name: Invalid input: expected string, received undefined

根因：schema 要求每个模型对象同时包含id与name两个字符串字段，只写id会校验失败。name可直接与id相同（仅作展示名）。

8.agents.defaults.model必须是对象

报错：

agents.defaults.model: Invalid input

根因：该字段不能填字符串，必须是对象：

"model":{"primary":"oneapi/glm-4-flash"}

如需在 OpenClaw 层做兜底，可加fallbacks：

"model":{"primary":"oneapi/glm-4-flash","fallbacks":["oneapi/qwen3.8-flash"]}

9. 主备配置：智谱为主、百炼兜底

目标：优先走智谱免费模型；智谱限流/报错时自动切百炼。

OneAPI 渠道权重配置

• 智谱渠道：分组default，权重 10，倍率全部0（免费主力）
• 百炼 DashScope 渠道：分组default，权重 1，倍率按官方价格（付费兜底）
• 权重越大被选中概率越高，10:1保证绝大多数请求走智谱。

百炼 DashScope 接入参数

类型: OpenAI BaseURL: https://dashscope.aliyuncs.com/compatible-mode/v1 模型: qwen3.8-flash,qwen-vl-flash

故障转移机制说明

• 同分组内，请求按权重挑选渠道；选中渠道返回429 限流 / 超时 / 5xx时，OneAPI 会自动重试同分组其他渠道（即自动切百炼兜底）。
• ⚠️402 余额不足不会触发故障转移，直接返回报错，不会继续切回其他渠道。

模型重定向（关键！）
因为智谱主模型是glm-4-flash，而百炼渠道没有这个模型，若直接切过去会 404。需要在百炼渠道「高级设置」添加模型映射：

{"glm-4-flash":"qwen3.8-flash"}

含义：下游请求glm-4-flash走到百炼渠道时，自动翻译为qwen3.8-flash调用。

四、OpenClaw 最终可用配置（已脱敏）

以下为校验通过的完整参考配置，Key 已用****替代，请替换为自己的 OneAPI 令牌。

{"models":{"providers":{"oneapi":{"baseUrl":"http://172.25.33.212:3000/v1","apiKey":"sk-****","api":"openai-completions","models":[{"id":"glm-4-flash","name":"glm-4-flash"},{"id":"glm-z1-flash","name":"glm-z1-flash"},{"id":"glm-4.6v-flash","name":"glm-4.6v-flash"},{"id":"qwen3.8-flash","name":"qwen3.8-flash"}]}}},"agents":{"defaults":{"workspace":"~/.openclaw/workspace","model":{"primary":"oneapi/glm-4-flash"}}}}

调用模型写法：oneapi/glm-4-flash（provider 名 + 模型 id）

说明："oneapi"只是自定义 provider 的标识名，可随意改（如gateway），改后调用前缀同步变化即可。

五、令牌额度建议（智谱为主 + 百炼兜底场景）

• 智谱渠道倍率设为0，走智谱不会扣 OneAPI 令牌额度；
• 令牌额度建议填大值（如9999999），真正的消耗上限交给阿里云百炼侧（套餐 Credits 或充值余额）控制；
• 令牌额度填太小会导致：智谱明明正常，却因令牌额度耗尽而拒绝请求。

六、验证与最终成果

1. 底层链路验证命令

curlhttp://172.25.33.212:3000/v1/chat/completions\-H"Authorization: Bearer sk-****"\-H"Content-Type: application/json"\-d'{"model":"glm-4-flash","messages":[{"role":"user","content":"你好"}]}'

2. 配置校验 + 重启

openclaw config validate systemctl restart openclaw-gateway.service

3. 问题定位工具

# 查看网关实时日志（定位真实报错）journalctl-uopenclaw-gateway.service-f

4. 最终验证截图

下图为 OneAPI 日志面板：智谱glm-4-flash渠道测试成功，OpenClaw令牌正常消费；Kimi 相关渠道因权限/未充值保持失败状态，符合预期（主线已全部切换到智谱免费模型）。但是免费的确实很卡，跑自己的小技能要半天。

七、经验总结（避坑清单）

1. 字段名大小写敏感：OpenAI 兼容配置务必核对apiKey（K 大写）、baseUrl等字段。
2. 自定义网关必须声明 models，且每个模型要id+name双字段。
3. 容器内别用127.0.0.1访问宿主机上的其他容器。
4. BaseURL 末尾/v1是否加各平台不一致：DeepSeek 不加，Kimi/百炼/OpenAI 兼容一般要加。
5. 新老平台域名与 Key 必须配对，否则 404/401。
6. 旗舰模型多需充值解锁，测试先用门槛低的模型。
7. IP 白名单填调用方 IP，测试阶段留空最省事。
8. 主备兜底要做「模型重定向」，否则备用渠道因模型名不同照样 404。
9. 402 余额不足不触发故障转移，务必保证主力渠道余额充足。
10. 令牌 IP 限制留空、分组与渠道保持一致，可避免大量偶发鉴权问题。