From 33b2474337de57bc4c96e8e09e3325aafdc209d0 Mon Sep 17 00:00:00 2001
From: OpenClaw Backup Bot <openclaw@transiglobal.com>
Date: Tue, 21 Apr 2026 13:35:57 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20custom=20provider?=
 =?UTF-8?q?=20=E5=AE=98=E6=96=B9=E5=8F=82=E8=80=83=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 SKILL.md                             |  9 +++
 references/custom-provider-config.md | 91 ++++++++++++++++++++++++++++
 2 files changed, 100 insertions(+)
 create mode 100644 references/custom-provider-config.md

diff --git a/SKILL.md b/SKILL.md
index 8ec5d30..8f9a925 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -214,6 +214,15 @@ sessions_spawn(
 4. Patch 模型到 `trapi.models`，别名到 `agents.defaults.models`
 5. 验证
 
+## 参考文档
+
+遇到问题时，读取 `references/custom-provider-config.md` 获取 OpenClaw 官方 Custom Provider 配置参考。
+
+### 在线文档
+
+- 模型与 Provider：https://docs.openclaw.ai/concepts/models
+- Model Providers：https://docs.openclaw.ai/concepts/model-providers
+
 ## 故障排查
 
 - **401/403**：API Key 无效或过期 — 请用户核实
diff --git a/references/custom-provider-config.md b/references/custom-provider-config.md
new file mode 100644
index 0000000..ef34a3b
--- /dev/null
+++ b/references/custom-provider-config.md
@@ -0,0 +1,91 @@
+# Custom Provider 配置参考
+
+> 来源：OpenClaw 官方文档
+> - https://docs.openclaw.ai/concepts/models
+> - https://docs.openclaw.ai/concepts/model-providers
+
+## Custom Provider 配置方式
+
+在 `openclaw.json` 的 `models.providers` 中添加自定义 provider：
+
+```json
+{
+  "models": {
+    "providers": {
+      "<provider_id>": {
+        "baseUrl": "https://api.example.com",
+        "apiKey": "sk-xxx",
+        "api": "anthropic-messages",
+        "models": [
+          {
+            "id": "model-name",
+            "name": "Display Name",
+            "api": "anthropic-messages",
+            "reasoning": false,
+            "input": ["text"],
+            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
+            "contextWindow": 200000,
+            "maxTokens": 64000
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## API 格式（api 字段）
+
+| 值 | 说明 |
+|----|------|
+| `anthropic-messages` | Anthropic Messages API 格式 |
+| `openai-completions` | OpenAI Chat Completions 格式 |
+| `openai-responses` | OpenAI Responses API 格式 |
+
+## 模型字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 模型 ID（必填），用于 provider/model 引用 |
+| `name` | string | 显示名称 |
+| `api` | string | API 格式，可覆盖 provider 级别设置 |
+| `reasoning` | boolean | 是否支持推理/思考模式 |
+| `input` | string[] | 支持的输入类型：`"text"`, `"image"` |
+| `cost` | object | 费用设置，免费模型全部设为 0 |
+| `contextWindow` | number | 上下文窗口大小（token 数） |
+| `maxTokens` | number | 最大输出 token 数 |
+
+## 模型别名配置
+
+在 `agents.defaults.models` 中注册别名：
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "models": {
+        "trapi/GLM-5-Turbo": { "alias": "glm5t" },
+        "trapi/GLM-5.1": { "alias": "glm51" }
+      }
+    }
+  }
+}
+```
+
+别名注册后可通过 `/alias` 快速切换模型。
+
+## 注意事项
+
+- `agents.defaults.models` 设置后成为 **allowlist**，只有列表中的模型才可用
+- Provider 配置会写入 `models.json`，合并模式（merge）下不会覆盖已有配置
+- API Key 会从 `models.providers` 和 auth profiles 两处解析
+- 模型引用格式：`provider/model`（如 `trapi/GLM-5-Turbo`）
+
+## 相关 CLI 命令
+
+```bash
+openclaw models list           # 查看已配置模型
+openclaw models status         # 查看当前模型和认证状态
+openclaw models aliases list   # 查看所有别名
+openclaw models aliases add <alias> <provider/model>  # 添加别名
+```