diff --git a/README.md b/README.md
index a20b61e..fbe61d5 100644
--- a/README.md
+++ b/README.md
@@ -1,107 +1,99 @@
 # openclaw-trapi-config
 
-OpenClaw 技能（Skill）：配置传米科技 trapi 自定义 Provider 及模型。
-
-## 简介
-
-trapi 是传米科技（Transiglobal）提供的大模型中转 API 服务，统一使用 Anthropic Messages 格式。本技能帮助用户在任意 OpenClaw 实例上一键配置 trapi Provider，包含预置模型和别名，并支持动态添加新模型。
+用于配置和维护传米科技 trapi 自定义 Provider 的 OpenClaw Skill，支持首次安装、模型增量更新、别名、图像模型、静态验证和故障排查。
 
 ## 服务信息
 
 | 项目 | 值 |
-|------|-----|
-| Provider 名称 | `trapi` |
-| API 地址 | `https://lapi.transiglobal.com` |
-| API 格式 | `anthropic-messages` |
-| 运营方 | 传米科技 |
+|---|---|
+| Provider ID | `trapi` |
+| Base URL | `https://lapi.transiglobal.com` |
+| API Key 环境变量 | `TRAPI_API_KEY` |
+| 默认 API 适配器 | `anthropic-messages` |
+| GPT 模型适配器 | `openai-responses` |
+
+trapi 支持模型级 API 适配器，不要求所有模型统一使用 Anthropic Messages。
 
 ## 预置模型
 
-| 模型 ID | 别名 | 输入类型 | 上下文窗口 | 最大输出 |
-|---------|------|---------|-----------|---------|
-| GLM-5-Turbo | `glm5t` | 文本 | 200K | 64K |
-| GLM-5.1 | `glm51` | 文本 | 200K | 64K |
-| GLM-4.5-Air | `glm45a` | 文本 | 200K | 64K |
-| MiniMax-M2 | `mxm2` | 文本 | 200K | 64K |
-| MiniMax-M2.7 | `mxm27` | 文本 | 200K | 64K |
-| kimi-for-coding | `kimi` | 文本 + 图片 | 262K | 32K |
-| deepseek-v4-pro | `dsv4p` | 文本 | 1M | 384K |
-| deepseek-v4-flash | `dsv4f` | 文本 | 1M | 384K |
-| gpt-5.5 | `gpt55` | 文本 | 200K | 65K |
-| GLM-5V-Turbo | `glm5v` | 文本 + 图片 | 200K | 64K |
-| PaddleOCR-VL-1.5 | `pocr` | 文本 + 图片 | 131K | 8K |
-| mimo-v2.5-pro | `mimo25p` | 文本 | 200K | 64K |
-| mimo-v2.5 | `mimo25` | 文本 + 图片 + 视频 + 音频 | 200K | 64K |
-| claude-opus-4.7 | `opus47` | 文本 | 300K | 64K |
-| qwen3.7-max | `qwn37` | 文本 | 1M | 100K |
-| qwen3.6-plus | `qwn36` | 文本 + 图片 | 1M | 100K |
+| 模型 ID | 别名 | API | 输入 | 上下文 | 最大输出 |
+|---|---|---|---|---:|---:|
+| GLM-5-Turbo | `glm5t` | anthropic-messages | 文本 | 200K | 64K |
+| GLM-5.2 | `glm52` | anthropic-messages | 文本 | 200K | 64K |
+| GLM-4.5-Air | `glm45a` | anthropic-messages | 文本 | 200K | 64K |
+| MiniMax-M2 | `mxm2` | anthropic-messages | 文本 | 200K | 64K |
+| MiniMax-M2.7 | `mxm27` | anthropic-messages | 文本 | 200K | 64K |
+| MiniMax-M3 | `mxm3` | anthropic-messages | 文本、图片 | 1M | 131K |
+| kimi-for-coding | `kimi` | anthropic-messages | 文本、图片 | 262K | 32K |
+| GLM-5V-Turbo | `glm5v` | anthropic-messages | 文本、图片 | 200K | 64K |
+| PaddleOCR-VL-1.5 | `pocr` | anthropic-messages | 文本、图片 | 131K | 8K |
+| deepseek-v4-pro | `dsv4p` | anthropic-messages | 文本 | 1M | 384K |
+| deepseek-v4-flash | `dsv4f` | anthropic-messages | 文本 | 1M | 384K |
+| gpt-5.5 | `gpt55` | openai-responses | 文本 | 200K | 65K |
+| gpt-5.6-sol | `g56s` | openai-responses | 文本、图片 | 372K | 128K |
+| gpt-5.6-terra | `g56t` | openai-responses | 文本、图片 | 372K | 128K |
+| gpt-5.6-luna | `g56l` | openai-responses | 文本、图片 | 372K | 128K |
+| mimo-v2.5-pro | `mimo25p` | anthropic-messages | 文本 | 200K | 64K |
+| mimo-v2.5 | `mimo25` | anthropic-messages | 文本、图片、视频、音频 | 200K | 64K |
+| claude-opus-4.7 | `opus47` | anthropic-messages | 文本 | 300K | 64K |
+| qwen3.7-max | `qwn37` | anthropic-messages | 文本 | 1M | 100K |
+| qwen3.6-plus | `qwn36` | anthropic-messages | 文本、图片 | 1M | 100K |
 
-## 快捷切换模型
-
-```
-/glm45a   → GLM-4.5-Air（轻量）
-/glm5t    → GLM-5-Turbo（高性价比）
-/glm51    → GLM-5.1（旗舰）
-/mxm2     → MiniMax-M2
-/mxm27    → MiniMax-M2.7
-/kimi     → kimi-for-coding（支持图片）
-/dsv4p    → DeepSeek V4 Pro（1M上下文）
-/dsv4f    → DeepSeek V4 Flash（1M上下文，快速）
-/gpt55    → GPT-5.5
-/glm5v    → GLM-5V-Turbo（支持图片）
-/pocr     → PaddleOCR-VL-1.5（OCR识别）
-/mimo25p  → MiMo 2.5 Pro
-/mimo25   → MiMo 2.5（全模态：文本+图片+视频+音频）
-/opus47    → Claude Opus 4.7（最新旗舰）
-/qwn37     → Qwen 3.7 Max（1M上下文，纯文本）
-/qwn36     → Qwen 3.6 Plus（1M上下文，支持图片）
-```
+模型目录不设置 `reasoning` 字段，费用元数据暂时全部保持为 0。
 
 ## 使用方式
 
-### 首次配置 trapi
-
 在 OpenClaw 对话中说：
 
-> "配置 trapi"
+> 配置 trapi
 
-技能会引导你完成：
-1. **提供 API Key**（必须提供，不会使用任何默认 key）
-2. **自动写入 Provider 配置**到 `openclaw.json`
-3. **注册模型别名**（glm5t / glm51 / mxm27 / kimi / dsv4p / dsv4f / gpt55 / opus47 等）
-4. **逐个模型验证**，确保连通性
-5. **检查已有配置**，只补齐缺失部分，不重复配置
+Skill 会执行以下流程：
 
-### 添加新模型
+1. 检查 OpenClaw 版本、Schema 和现有 trapi 配置。
+2. 对照预置目录生成新增、更新、保留和额外模型差异。
+3. 保留已有认证；首次配置时优先使用 `TRAPI_API_KEY` SecretRef。
+4. 展示变更方案，获得确认后使用 CLI `--merge` 安全增量写入。
+5. 注册缺失别名，并按需配置 imageModel。
+6. 执行配置、模型、别名和 Gateway 静态验证。
+7. 经用户确认后，只对本次变更模型执行最小实时调用。
 
-当 trapi 已配置好后，说：
+不会使用不完整的 `gateway config.patch` 覆盖模型数组，也不会自动删除目录外模型、覆盖默认模型或重写已有 imageModel。
 
-> "给 trapi 添加 Qwen-3-Plus"
+## 切换模型
 
-技能会：
-1. 询问模型全称
-2. 自动生成 ≤5 字符的别名（避免与已有别名冲突）
-3. 默认 200K 上下文 / 64K 最大输出，支持自定义
-4. 写入配置并验证
+在对话中使用 `/model <alias>`：
 
-## 图像模型配置（imageModel）
+```text
+/model glm5t
+/model mxm3
+/model g56s
+/model g56t
+/model g56l
+```
 
-配置 trapi 后，建议同步设置 OpenClaw 的 `imageModel`，使 Agent 具备图像识别能力：
+不能直接使用 `/<alias>` 切换模型。
 
-| 角色 | 模型 | 说明 |
-|------|------|------|
-| **Primary** | `trapi/kimi-for-coding` | 默认图像识别模型 |
-| Fallback 1 | `trapi/qwen3.6-plus` | 1M 上下文，支持图像 |
-| Fallback 2 | `trapi/mimo-v2.5` | 全模态（文本+图片+视频+音频） |
-| Fallback 3 | `trapi/GLM-5V-Turbo` | 智谱视觉模型 |
-| Fallback 4 | `zai/glm-4.6v` | 智谱官方 API 备选 |
-| Fallback 5 | `xiaomi/mimo-v2-omni` | 小米多模态备选 |
+## 图像模型
+
+建议链仅引用已配置且认证可用的 trapi 模型：
+
+1. `trapi/kimi-for-coding`
+2. `trapi/qwen3.6-plus`
+3. `trapi/mimo-v2.5`
+4. `trapi/GLM-5V-Turbo`
+5. `trapi/MiniMax-M3`
+
+Skill 默认保留现有 imageModel；只有用户明确要求，或当前未配置且用户接受建议时才写入。
 
 ## 安全说明
 
-- **API Key 必须由用户提供**，技能中不存储任何默认密钥
-- 未提供 Key 时配置流程会立即终止
-- 所有配置通过 OpenClaw 标准的 `gateway config.patch` 写入
+- 不在聊天、命令参数、日志或文档中回显 API Key。
+- 优先使用环境变量 SecretRef，不把真实 Key 明文写入 `openclaw.json`。
+- 所有持久配置变更先展示差异并等待确认。
+- 不使用 `--replace` 绕过 OpenClaw 的配置防覆盖保护。
+- 不默认调用付费模型；实时验证前说明范围并征得确认。
+
+详细参数见 [`references/custom-provider-config.md`](references/custom-provider-config.md)。
 
 ## 许可证
 
diff --git a/SKILL.md b/SKILL.md
index fc190f4..eb30c20 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,550 +1,203 @@
 ---
-name: openclaw-trapi-config
-description: |
-  配置传米科技 trapi 自定义 Provider 及模型。引导用户将 trapi Provider（lapi.transiglobal.com）添加到 OpenClaw，支持首次安装和动态添加新模型。触发词："配置 trapi"、"安装 trapi"、"添加 trapi provider"、"trapi 配置"、"Transiglobal API"、"配置传米 API"、"trapi 添加模型"、"trapi add model"，或涉及 GLM-5-Turbo / GLM-5.1 / GLM-5.2 / MiniMax-M2.7 / kimi-for-coding / deepseek-v4-pro / deepseek-v4-flash / mimo-v2.5-pro / mimo-v2.5 / claude-opus-4.7 / GLM-5V-Turbo / PaddleOCR-VL-1.5 / qwen3.7-max / qwen3.6-plus 的 trapi 配置。也可在 trapi 已存在时用于添加新模型。
+name: "openclaw-trapi-config"
+description: "配置传米 trapi Provider、模型、别名与图像模型；用于安装、增量更新、验证和排障，包括 MiniMax-M3 与 GPT-5.6。"
 ---
 
-# trapi Provider 配置指南
+# trapi 配置
 
-在任意 OpenClaw 实例上配置 `trapi` 自定义 Provider，使用 Anthropic Messages API 格式。
+为 OpenClaw 配置传米科技 trapi Provider。trapi 允许不同模型使用不同 API 适配器；不要假设所有模型都使用同一种协议。
 
-## 服务信息
+详细模型参数和别名见 [references/custom-provider-config.md](references/custom-provider-config.md)。配置前必须读取该文件。
 
-- **Provider 名称**：`trapi`
-- **Base URL**：`https://lapi.transiglobal.com`
-- **API 格式**：`anthropic-messages`
-- **运营方**：传米科技（Transiglobal）
+## 固定信息
 
-## 步骤 -1：检查 OpenClaw 版本
+- Provider ID：`trapi`
+- Base URL：`https://lapi.transiglobal.com`
+- API Key 环境变量：`TRAPI_API_KEY`
+- 默认适配器：`anthropic-messages`
+- GPT 模型按目录使用 `openai-responses`
 
-**在执行任何配置操作前，必须先检查 OpenClaw 版本**，以确定正确的配置格式。
+## 安全原则
 
-### 检查方法
+1. 先读取并校验现有配置，再提出变更。
+2. 只做增量写入；不得用不完整对象覆盖 Provider、模型数组、别名表或 imageModel。
+3. 不在聊天、命令参数、日志或文档中回显 API Key。
+4. 优先使用环境变量 SecretRef；不要把真实 Key 明文写入 `openclaw.json`。
+5. 任何持久配置变更前，列出将新增、更新、保留和跳过的项目，并等待用户确认。
+6. 不自动删除现有模型或别名。删除或替换必须由用户明确指定。
+7. 不自动覆盖现有默认模型、imageModel 或 fallback 链。
+8. 不使用 Agent 侧 `gateway config.patch` 写入 `models.providers` 等受保护路径。优先使用当前主机上的 OpenClaw CLI。
+9. 不默认执行付费模型调用。实时验证前说明调用范围并征得确认。
+
+## 工作流
+
+### 1. 检查版本和 Schema
+
+执行：
 
 ```bash
 openclaw --version
+openclaw config validate
+openclaw config schema
 ```
 
-### 版本分支
+要求当前版本支持：
 
-| 版本 | 别名配置位置 | 说明 |
-|------|-------------|------|
-| **>= 2026.5.0** | `agents.defaults.models."provider/model"` → `{"alias": "xxx"}` | 新版格式（本技能默认采用） |
-| **< 2026.5.0** | 同样使用 `agents.defaults.models` 格式 | 向下兼容 |
+- `openclaw config set ... --merge`
+- `openclaw models aliases add`
+- `openclaw models set-image`
+- `openclaw models image-fallbacks`
 
-> **注意**：如果 OpenClaw < 2026.3.0，建议先升级 OpenClaw 再配置 trapi。
+如命令或 Schema 不支持这些字段，停止配置并建议使用 `openclaw update --yes` 升级。不要自行升级。
 
-### 前置条件
+### 2. 检查现有状态
 
-1. 用户**必须提供自己的 API Key** —— 绝不使用默认或硬编码的密钥
-2. 如用户未提供 API Key，**立即停止**并要求提供；不可继续执行
-3. OpenClaw 必须已安装并运行
+读取以下路径，不输出凭据值：
 
-## 步骤 0：检查已有配置
+```bash
+openclaw config get models.providers.trapi.models
+openclaw config get agents.defaults.models
+openclaw config get agents.defaults.imageModel
+openclaw models list --provider trapi --json
+openclaw models aliases list --json
+openclaw models status --json
+```
 
-**在执行任何配置操作前，必须先检查当前 OpenClaw 配置中是否已有 trapi provider 或部分模型/别名。** 避免重复配置，只补齐缺失部分。
+对照参考目录，按模型 ID 生成差异：
 
-### 检查流程
+- 新增：目录有、当前没有
+- 更新：模型已存在，但 api、input、contextWindow 或 maxTokens 不一致
+- 保留：现有配置与目录一致
+- 额外：当前存在、目录没有；只报告，不自动删除
+- 别名缺失或冲突：单独列出
 
-1. 使用 `gateway config.get` 获取当前 `models.providers.trapi` 配置
-2. 使用 `gateway config.get` 获取当前 `agents.defaults.models` 中的 trapi 别名
-3. 对比下表，列出三列状态：
+`GLM-5.1` 不再属于预置目录。若现有实例仍配置它，只列为额外项，不自动删除。
 
-| 模型 | 别名 | Provider 已有 | 别名已有 |
-|------|------|:---:|:---:|
-| GLM-5-Turbo | glm5t | ✅/❌ | ✅/❌ |
-| GLM-5.1 | glm51 | ✅/❌ | ✅/❌ |
-| GLM-5.2 | glm52 | ✅/❌ | ✅/❌ |
-| GLM-4.5-Air | glm45a | ✅/❌ | ✅/❌ |
-| MiniMax-M2 | mxm2 | ✅/❌ | ✅/❌ |
-| MiniMax-M2.7 | mxm27 | ✅/❌ | ✅/❌ |
-| kimi-for-coding | kimi | ✅/❌ | ✅/❌ |
-| deepseek-v4-pro | dsv4p | ✅/❌ | ✅/❌ |
-| deepseek-v4-flash | dsv4f | ✅/❌ | ✅/❌ |
-| gpt-5.5 | gpt55 | ✅/❌ | ✅/❌ |
-| mimo-v2.5-pro | mimo25p | ✅/❌ | ✅/❌ |
-| mimo-v2.5 | mimo25 | ✅/❌ | ✅/❌ |
-| claude-opus-4.7 | opus47 | ✅/❌ | ✅/❌ |
-| GLM-5V-Turbo | glm5v | ✅/❌ | ✅/❌ |
-| PaddleOCR-VL-1.5 | pocr | ✅/❌ | ✅/❌ |
-| qwen3.7-max | qwn37 | ✅/❌ | ✅/❌ |
-| qwen3.6-plus | qwn36 | ✅/❌ | ✅/❌ |
+### 3. 处理认证
 
-### 检查结果处理
+如果现有 trapi 认证可解析并且用户没有要求换 Key，保留现有认证，不再索要 Key。
 
-- **全部已有**（Provider + 所有模型 + 所有别名）：告知用户已完整配置，无需操作
-- **Provider 已有，部分模型缺失**：只 patch 缺失的模型，不覆盖已有配置
-- **Provider 缺失**：按步骤 1-6 完整配置
-- **模型已有但别名缺失**：只 patch 缺失的别名
-- **API Key 需要更新**：即使用户提供了新 Key，也要先确认旧 Key 是否仍有效
-
-### 操作原则
-
-1. **绝不覆盖已有配置** — `config.patch` 是合并操作，但新模型如果 ID 与已有不同则追加
-2. **只补齐缺失部分** — 精确对比已有 vs 缺失，只 patch 差集
-3. **向用户展示补齐方案** — 明确列出将要添加/跳过的内容，等用户确认后再执行
-
-## 步骤 1：要求 API Key
-
-进行任何配置前，先向用户索要 `trapi` API Key。接受形式：
-- 直接粘贴 Key 字符串
-- 通过环境变量引用
-
-如用户拒绝或无法提供，以明确信息终止流程：*"trapi provider 配置需要 API Key，未提供无法继续。请获取 Key 后重新运行。"*
-
-## 步骤 2：配置 Provider
-
-使用 `gateway config.patch` 将 `trapi` provider 添加到 `models.providers`。
+首次配置或认证失效时，引导用户在 Gateway 服务环境中设置 `TRAPI_API_KEY`，然后使用 SecretRef：
 
 ```json
 {
-  "models": {
-    "providers": {
-      "trapi": {
-        "baseUrl": "https://lapi.transiglobal.com",
-        "apiKey": "<用户提供的API_KEY>",
-        "api": "anthropic-messages",
-        "models": [
-          {
-            "id": "GLM-5-Turbo",
-            "name": "GLM-5-Turbo (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 64000
-          },
-          {
-            "id": "GLM-5.1",
-            "name": "GLM-5.1 (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 64000
-          },
-          {
-            "id": "GLM-5.2",
-            "name": "GLM-5.2 (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 64000
-          },
-          {
-            "id": "GLM-4.5-Air",
-            "name": "GLM-4.5-Air (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 64000
-          },
-          {
-            "id": "MiniMax-M2",
-            "name": "MiniMax-M2 (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 64000
-          },
-          {
-            "id": "MiniMax-M2.7",
-            "name": "MiniMax-M2.7 (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 64000
-          },
-          {
-            "id": "kimi-for-coding",
-            "name": "kimi-for-coding (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text", "image"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 262144,
-            "maxTokens": 32768
-          },
-          {
-            "id": "GLM-5V-Turbo",
-            "name": "GLM-5V-Turbo (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": true,
-            "input": ["text", "image"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 64000
-          },
-          {
-            "id": "PaddleOCR-VL-1.5",
-            "name": "PaddleOCR-VL-1.5 (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text", "image"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 131072,
-            "maxTokens": 8192
-          },
-          {
-            "id": "deepseek-v4-pro",
-            "name": "DeepSeek V4 Pro (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 1000000,
-            "maxTokens": 384000
-          },
-          {
-            "id": "deepseek-v4-flash",
-            "name": "DeepSeek V4 Flash (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 1000000,
-            "maxTokens": 384000
-          },
-          {
-            "id": "gpt-5.5",
-            "name": "GPT-5.5 (Transiglobal)",
-            "api": "openai-responses",
-            "reasoning": false,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 65536
-          },
-          {
-            "id": "mimo-v2.5-pro",
-            "name": "MiMo 2.5 Pro (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": true,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 64000
-          },
-          {
-            "id": "mimo-v2.5",
-            "name": "MiMo 2.5 (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": true,
-            "input": ["text", "image", "video", "audio"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 64000
-          },
-          {
-            "id": "claude-opus-4.7",
-            "name": "claude-opus-4.7 (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": true,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 300000,
-            "maxTokens": 64000
-          },
-          {
-            "id": "qwen3.7-max",
-            "name": "Qwen 3.7 Max (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 1000000,
-            "maxTokens": 100000
-          },
-          {
-            "id": "qwen3.6-plus",
-            "name": "Qwen 3.6 Plus (Transiglobal)",
-            "api": "anthropic-messages",
-            "reasoning": false,
-            "input": ["text", "image"],
-            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 1000000,
-            "maxTokens": 100000
-          }
-        ]
-      }
-    }
-  }
+  "source": "env",
+  "provider": "default",
+  "id": "TRAPI_API_KEY"
 }
 ```
 
-## 步骤 3：配置模型别名
+配置前确认该环境变量对 Gateway 服务进程可见。不得要求用户把 Key 直接粘贴到群聊；私聊中也优先让用户在主机端设置。
 
-### ⚠️ 关键：别名只能放在 agents.defaults.models 中
+### 4. 展示变更方案并确认
 
-**绝对不要**把别名放在以下位置（会导致配置无效）：
-- ❌ `agents.defaults.model.aliases` — 错误！
-- ❌ `agents.modelAliases` — 错误！
-- ✅ `agents.defaults.models."provider/model"` — **正确！**
+至少展示：
 
-使用 `gateway config.patch` 添加别名到 `agents.defaults.models`：
+- Provider 是否新建
+- 将新增和更新的模型
+- 将新增或调整的别名
+- 当前目录外模型
+- imageModel 是否保持不变
+- 是否需要 Gateway 重载或重启
+- 是否计划进行实时模型调用
 
-```json
-{
-  "agents": {
-    "defaults": {
-      "models": {
-        "trapi/GLM-5-Turbo": { "alias": "glm5t" },
-        "trapi/GLM-5.1": { "alias": "glm51" },
-        "trapi/GLM-5.2": { "alias": "glm52" },
-        "trapi/GLM-4.5-Air": { "alias": "glm45a" },
-        "trapi/MiniMax-M2": { "alias": "mxm2" },
-        "trapi/MiniMax-M2.7": { "alias": "mxm27" },
-        "trapi/kimi-for-coding": { "alias": "kimi" },
-        "trapi/GLM-5V-Turbo": { "alias": "glm5v" },
-        "trapi/PaddleOCR-VL-1.5": { "alias": "pocr" },
-        "trapi/deepseek-v4-pro": { "alias": "dsv4p" },
-        "trapi/deepseek-v4-flash": { "alias": "dsv4f" },
-        "trapi/gpt-5.5": { "alias": "gpt55" },
-        "trapi/mimo-v2.5-pro": { "alias": "mimo25p" },
-        "trapi/mimo-v2.5": { "alias": "mimo25" },
-        "trapi/claude-opus-4.7": { "alias": "opus47" },
-        "trapi/qwen3.7-max": { "alias": "qwn37" },
-        "trapi/qwen3.6-plus": { "alias": "qwn36" }
-      }
-    }
-  }
-}
+用户未确认时不得写入。
+
+### 5. 安全增量写入
+
+使用参考文件中的 Provider 和模型目录。
+
+优先使用 CLI 的合并写入：
+
+```bash
+openclaw config set models.providers.trapi '<provider-json>' --strict-json --merge
+openclaw config set models.providers.trapi.models '<model-array-json>' --strict-json --merge
 ```
 
-### 别名格式说明
+规则：
 
-- key 为完整模型引用 `<provider>/<model>`（如 `trapi/GLM-5-Turbo`）
-- value 为 `{ "alias": "短别名" }`
-- **注意**：设置 `agents.defaults.models` 后它会成为 allowlist，只有列表中的模型可用
+- Provider 已存在时保留未请求修改的字段。
+- `models.providers.trapi.models` 只提交完整的新条目或明确更新的条目，并使用 `--merge`。
+- 如 CLI 检测到会删除条目并拒绝写入，重新读取配置并修正差异；不要改用 `--replace` 绕过保护。
+- 不直接编辑 `openclaw.json`。
+- 不使用全量 `config.apply`。
 
-## 步骤 4：配置图像模型（imageModel）
+逐个注册缺失别名：
 
-trapi 提供了多个支持图像输入的模型。OpenClaw 的 `agents.defaults.imageModel` 用于指定当主模型不支持图像时的图像识别模型。
-
-使用 `gateway config.patch`（如路径受保护则直接编辑 `openclaw.json`）配置：
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "imageModel": {
-        "primary": "trapi/kimi-for-coding",
-        "fallbacks": [
-          "trapi/qwen3.6-plus",
-          "trapi/mimo-v2.5",
-          "trapi/GLM-5V-Turbo",
-          "zai/glm-4.6v",
-          "xiaomi/mimo-v2-omni"
-        ]
-      }
-    }
-  }
-}
+```bash
+openclaw models aliases add <alias> trapi/<model-id>
 ```
 
-### imageModel 配置说明
+如别名被其他模型占用，报告冲突并让用户决定；不要自动重定向已有别名。
 
-| 项目 | 模型 | 说明 |
-|------|------|------|
-| **Primary** | `trapi/kimi-for-coding` | 默认图像识别模型，性价比最优 |
-| Fallback 1 | `trapi/qwen3.6-plus` | 1M 上下文，支持图像 |
-| Fallback 2 | `trapi/mimo-v2.5` | 全模态（文本+图片+视频+音频） |
-| Fallback 3 | `trapi/GLM-5V-Turbo` | 智谱视觉模型 |
-| Fallback 4 | `zai/glm-4.6v` | 智谱官方 API 备选 |
-| Fallback 5 | `xiaomi/mimo-v2-omni` | 小米多模态备选 |
+### 6. 可选配置 imageModel
 
-> **注意**：`imageModel` 是受保护路径，`config.patch` 可能无法修改。如遇此情况，需直接编辑 `openclaw.json` 文件中的 `agents.defaults.imageModel` 字段。
+只有用户明确要求，或现有 imageModel 为空且用户接受建议时才配置。
 
-## 步骤 5：应用配置
+建议链仅引用已配置且认证可用的 trapi 图像模型：
 
-使用 `gateway config.patch` 并附带 `note` 参数说明变更内容。Gateway 会自动热加载或重启。
+1. `trapi/kimi-for-coding`
+2. `trapi/qwen3.6-plus`
+3. `trapi/mimo-v2.5`
+4. `trapi/GLM-5V-Turbo`
+5. `trapi/MiniMax-M3`
 
-**重要**：配置完成后用 `openclaw gateway status` 确认 Gateway 正常运行，无 `Invalid input` 错误。
+使用：
 
-## 步骤 6：逐个验证模型
-
-配置生效后，使用 subagent 逐个验证模型：
-
-```
-sessions_spawn(
-  model: "trapi/<模型ID>",
-  task: "Reply with exactly: OK",
-  runtime: "subagent"
-)
+```bash
+openclaw models set-image trapi/kimi-for-coding
+openclaw models image-fallbacks add trapi/qwen3.6-plus
 ```
 
-验证顺序：
-1. `trapi/GLM-5-Turbo`（别名：glm5t）
-2. `trapi/GLM-5.1`（别名：glm51）
-3. `trapi/GLM-5.2`（别名：glm52）
-4. `trapi/GLM-4.5-Air`（别名：glm45a）
-5. `trapi/MiniMax-M2`（别名：mxm2）
-6. `trapi/MiniMax-M2.7`（别名：mxm27）
-7. `trapi/kimi-for-coding`（别名：kimi）
-8. `trapi/GLM-5V-Turbo`（别名：glm5v）
-9. `trapi/PaddleOCR-VL-1.5`（别名：pocr）
-10. `trapi/deepseek-v4-pro`（别名：dsv4p）
-11. `trapi/deepseek-v4-flash`（别名：dsv4f）
-12. `trapi/gpt-5.5`（别名：gpt55）
-13. `trapi/claude-opus-4.7`（别名：opus47）
-14. `trapi/qwen3.7-max`（别名：qwn37）
-15. `trapi/qwen3.6-plus`（别名：qwn36）
+后续 fallback 逐个添加。已有 imageModel 时默认保持原样，不加入未认证的其他 Provider 模型。
 
-### 验证标准
+### 7. 静态验证
 
-每个模型验证通过的条件：
-- subagent 返回正常响应（非错误/超时）
-- 响应包含文本输出
+写入后执行：
 
-### 验证报告
-
-所有模型验证完成后，输出汇总表：
-
-| 模型 | 别名 | 状态 |
-|------|------|------|
-| GLM-5-Turbo | glm5t | ✅/❌ |
-| GLM-5.1 | glm51 | ✅/❌ |
-| GLM-5.2 | glm52 | ✅/❌ |
-| GLM-4.5-Air | glm45a | ✅/❌ |
-| MiniMax-M2 | mxm2 | ✅/❌ |
-| MiniMax-M2.7 | mxm27 | ✅/❌ |
-| kimi-for-coding | kimi | ✅/❌ |
-| GLM-5V-Turbo | glm5v | ✅/❌ |
-| PaddleOCR-VL-1.5 | pocr | ✅/❌ |
-| deepseek-v4-pro | dsv4p | ✅/❌ |
-| deepseek-v4-flash | dsv4f | ✅/❌ |
-| gpt-5.5 | gpt55 | ✅/❌ |
-| mimo-v2.5-pro | mimo25p | ✅/❌ |
-| mimo-v2.5 | mimo25 | ✅/❌ |
-| claude-opus-4.7 | opus47 | ✅/❌ |
-| qwen3.7-max | qwn37 | ✅/❌ |
-| qwen3.6-plus | qwn36 | ✅/❌ |
-
-## 步骤 7：使用指引
-
-配置完成并通过验证后，向用户展示快捷切换模型的使用方式：
-
-```
-/glm45a   → 切换到 GLM-4.5-Air（轻量）
-/glm5t    → 切换到 GLM-5-Turbo（高性价比）
-/glm51    → 切换到 GLM-5.1（旗舰）
-/glm52    → 切换到 GLM-5.2（最新旗舰）
-/mxm2     → 切换到 MiniMax-M2
-/mxm27    → 切换到 MiniMax-M2.7
-/kimi     → 切换到 kimi-for-coding（支持图片）
-/dsv4p    → 切换到 DeepSeek V4 Pro（1M上下文）
-/dsv4f    → 切换到 DeepSeek V4 Flash（1M上下文，快速）
-/gpt55    → 切换到 GPT-5.5
-/mimo25p   → 切换到 MiMo 2.5 Pro
-/mimo25    → 切换到 MiMo 2.5（全模态）
-/glm5v    → 切换到 GLM-5V-Turbo（支持图片）
-/pocr     → 切换到 PaddleOCR-VL-1.5（OCR识别）
-/opus47    → 切换到 Claude Opus 4.7（最新旗舰）
-/qwn37     → 切换到 Qwen 3.7 Max（1M上下文，纯文本）
-/qwn36     → 切换到 Qwen 3.6 Plus（1M上下文，支持图片）
+```bash
+openclaw config validate
+openclaw models list --provider trapi --json
+openclaw models aliases list --json
+openclaw models status --json
+openclaw gateway status
 ```
 
-提示用户在对话中直接输入 `/alias` 即可快速切换模型。
+静态验证通过条件：
 
-## 添加新模型（trapi 已配置时）
+- 配置 Schema 有效
+- 新增模型出现在 trapi 列表
+- 别名指向正确模型
+- Gateway 探针正常
+- 没有凭据、模型或 imageModel 缺失警告
 
-当 trapi Provider 已存在，用户需要添加新模型时使用此流程。
+`models list` 的 `available: true` 只表示配置和认证状态可用，不等于已完成真实推理验证。
 
-### 用户需提供的信息
+### 8. 可选实时验证
 
-| 字段 | 是否必填 | 默认值 |
-|------|---------|--------|
-| 模型 ID（全称） | ✅ 必填 | — |
-| contextWindow | 选填 | 200000（200K） |
-| maxTokens | 选填 | 64000（64K） |
-| input 类型 | 选填 | `["text"]`（可加 `"image"`） |
+获得用户确认后，只验证本次新增或更新的模型，不默认全量测试。
 
-### 别名生成规则
+文本模型使用最小请求：
 
-生成 **≤ 5 字符**的别名，按以下优先级：
+```text
+Reply with exactly: OK
+```
 
-1. **已知模式** — 从常见缩写推导：
-   - `GLM-` → `glm`，`MiniMax-` → `mxm`，`kimi-for-coding` → `kimi`，`mimo` → `mimo`
-2. **去除分隔符** — 去掉 `-`、`.`、空格：`GLM-5-Turbo` → `GLM5Turbo`
-3. **取前 5 字符**：`GLM5T`
-4. **转小写**：`glm5t`
-5. **冲突处理**：如与已有别名冲突，追加数字后缀：`glm5t2`
+图像模型还需用一张无敏感信息的测试图片验证图片输入。需要工具能力时，再单独做一次最小工具调用测试。
 
-### 已有别名（不可重复）
+并发数控制在 2–3。记录成功、超时、认证失败、模型不存在和协议不兼容。不要把“返回任意文本”当作所有能力均验证通过。
 
-| 模型 | 别名 |
-|------|------|
-| GLM-4.5-Air | glm45a |
-| GLM-5-Turbo | glm5t |
-| GLM-5.1 | glm51 |
-| GLM-5.2 | glm52 |
-| MiniMax-M2 | mxm2 |
-| MiniMax-M2.7 | mxm27 |
-| kimi-for-coding | kimi |
-| deepseek-v4-pro | dsv4p |
-| deepseek-v4-flash | dsv4f |
-| gpt-5.5 | gpt55 |
-| mimo-v2.5-pro | mimo25p |
-| mimo-v2.5 | mimo25 |
-| claude-opus-4.7 | opus47 |
-| GLM-5V-Turbo | glm5v |
-| PaddleOCR-VL-1.5 | pocr |
-| qwen3.7-max | qwn37 |
-| qwen3.6-plus | qwn36 |
+### 9. 报告结果
 
-### 支持图片输入的模型
+输出以下内容：
 
-以下模型支持图片输入（`input` 包含 `"image"`）：
-- **kimi-for-coding**（别名：kimi）
-- **GLM-5V-Turbo**（别名：glm5v）
-- **PaddleOCR-VL-1.5**（别名：pocr）
-- **qwen3.6-plus**（别名：qwn36）
+- 已新增和更新的模型
+- 已注册的别名
+- 保留的现有配置
+- 未处理的额外模型
+- 静态验证结果
+- 实时验证结果或“未执行”
+- 失败项、原因和建议
+- 正确切换方式：`/model <alias>`
 
-### 操作流程
-
-1. 向用户询问**模型 ID**（全称）
-2. 询问是否需要自定义 contextWindow、maxTokens 或 input 类型
-3. 按上述规则生成别名
-4. 向用户展示拟配置方案并确认
-5. `gateway config.patch` 添加模型到 `models.providers.trapi.models`
-6. `gateway config.patch` 添加别名到 `agents.defaults.models`（格式：`{"trapi/<模型ID>":{"alias":"<别名>"}}`）
-7. subagent 验证：`sessions_spawn(model: "trapi/<模型ID>", task: "Reply with exactly: OK", runtime: "subagent")`
-8. 报告结果
-
-### 示例：添加 "Qwen-3-Plus"
-
-用户说："给 trapi 加一个 Qwen-3-Plus"
-
-1. 模型 ID：`Qwen-3-Plus`
-2. 默认参数：contextWindow 200K，maxTokens 64K，input `["text"]`
-3. 别名：清理为 `Qwen3Plus` → `qwen3`（无冲突）→ 别名：`qwen3`
-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 无效或过期 — 请用户核实
-- **连接超时**：检查到 `lapi.transiglobal.com` 的网络连通性
-- **Model not found**：模型 ID 可能已变更 — 联系传米科技确认
-- **`Invalid input` 错误**：别名放错了位置！确认别名只在 `agents.defaults.models."provider/model"` 中，没有放到 `agents.defaults.model.aliases` 或 `agents.modelAliases`
-- **config.patch 冲突**：trapi provider 已存在时 patch 会合并；别名冲突时警告用户
-- **别名冲突**：重新生成带数字后缀的别名并与用户确认
+不要声称可以直接输入 `/<alias>` 切换模型。
diff --git a/references/custom-provider-config.md b/references/custom-provider-config.md
index ef34a3b..136cd21 100644
--- a/references/custom-provider-config.md
+++ b/references/custom-provider-config.md
@@ -1,91 +1,157 @@
-# Custom Provider 配置参考
+# trapi 模型与配置参考
 
-> 来源：OpenClaw 官方文档
-> - https://docs.openclaw.ai/concepts/models
-> - https://docs.openclaw.ai/concepts/model-providers
+## 目录
 
-## Custom Provider 配置方式
+- [Provider 配置](#provider-配置)
+- [预置模型](#预置模型)
+- [别名](#别名)
+- [图像模型](#图像模型)
+- [当前 OpenClaw 写入方式](#当前-openclaw-写入方式)
+- [故障排查](#故障排查)
 
-在 `openclaw.json` 的 `models.providers` 中添加自定义 provider：
+## Provider 配置
+
+trapi 使用混合模型适配器。Provider 级 `api` 只是默认值；模型级 `api` 优先。
 
 ```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
-          }
-        ]
-      }
-    }
-  }
+  "baseUrl": "https://lapi.transiglobal.com",
+  "apiKey": {
+    "source": "env",
+    "provider": "default",
+    "id": "TRAPI_API_KEY"
+  },
+  "api": "anthropic-messages"
 }
 ```
 
-## API 格式（api 字段）
+不要在配置示例中放真实 API Key。
 
-| 值 | 说明 |
-|----|------|
-| `anthropic-messages` | Anthropic Messages API 格式 |
-| `openai-completions` | OpenAI Chat Completions 格式 |
-| `openai-responses` | OpenAI Responses API 格式 |
+## 预置模型
 
-## 模型字段说明
+所有模型暂时保留零费用元数据。不要给任何模型写 `reasoning` 字段，让 OpenClaw 和上游按模型默认行为处理。
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `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 数 |
+| 模型 ID | API | 输入 | contextWindow | maxTokens |
+|---|---|---|---:|---:|
+| GLM-5-Turbo | anthropic-messages | text | 200000 | 64000 |
+| GLM-5.2 | anthropic-messages | text | 200000 | 64000 |
+| GLM-4.5-Air | anthropic-messages | text | 200000 | 64000 |
+| MiniMax-M2 | anthropic-messages | text | 200000 | 64000 |
+| MiniMax-M2.7 | anthropic-messages | text | 200000 | 64000 |
+| MiniMax-M3 | anthropic-messages | text, image | 1000000 | 131072 |
+| kimi-for-coding | anthropic-messages | text, image | 262144 | 32768 |
+| GLM-5V-Turbo | anthropic-messages | text, image | 200000 | 64000 |
+| PaddleOCR-VL-1.5 | anthropic-messages | text, image | 131072 | 8192 |
+| deepseek-v4-pro | anthropic-messages | text | 1000000 | 384000 |
+| deepseek-v4-flash | anthropic-messages | text | 1000000 | 384000 |
+| gpt-5.5 | openai-responses | text | 200000 | 65536 |
+| gpt-5.6-sol | openai-responses | text, image | 372000 | 128000 |
+| gpt-5.6-terra | openai-responses | text, image | 372000 | 128000 |
+| gpt-5.6-luna | openai-responses | text, image | 372000 | 128000 |
+| mimo-v2.5-pro | anthropic-messages | text | 200000 | 64000 |
+| mimo-v2.5 | anthropic-messages | text, image, video, audio | 200000 | 64000 |
+| claude-opus-4.7 | anthropic-messages | text | 300000 | 64000 |
+| qwen3.7-max | anthropic-messages | text | 1000000 | 100000 |
+| qwen3.6-plus | anthropic-messages | text, image | 1000000 | 100000 |
 
-## 模型别名配置
-
-在 `agents.defaults.models` 中注册别名：
+完整模型数组：
 
 ```json
-{
-  "agents": {
-    "defaults": {
-      "models": {
-        "trapi/GLM-5-Turbo": { "alias": "glm5t" },
-        "trapi/GLM-5.1": { "alias": "glm51" }
-      }
-    }
-  }
-}
+[
+  {"id":"GLM-5-Turbo","name":"GLM-5-Turbo (Transiglobal)","api":"anthropic-messages","input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":200000,"maxTokens":64000},
+  {"id":"GLM-5.2","name":"GLM-5.2 (Transiglobal)","api":"anthropic-messages","input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":200000,"maxTokens":64000},
+  {"id":"GLM-4.5-Air","name":"GLM-4.5-Air (Transiglobal)","api":"anthropic-messages","input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":200000,"maxTokens":64000},
+  {"id":"MiniMax-M2","name":"MiniMax M2 (Transiglobal)","api":"anthropic-messages","input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":200000,"maxTokens":64000},
+  {"id":"MiniMax-M2.7","name":"MiniMax-M2.7 (Transiglobal)","api":"anthropic-messages","input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":200000,"maxTokens":64000},
+  {"id":"MiniMax-M3","name":"MiniMax M3 (Transiglobal)","api":"anthropic-messages","input":["text","image"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":1000000,"maxTokens":131072},
+  {"id":"kimi-for-coding","name":"kimi-for-coding (Transiglobal)","api":"anthropic-messages","input":["text","image"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":262144,"maxTokens":32768},
+  {"id":"GLM-5V-Turbo","name":"GLM-5V-Turbo (Transiglobal)","api":"anthropic-messages","input":["text","image"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":200000,"maxTokens":64000},
+  {"id":"PaddleOCR-VL-1.5","name":"PaddleOCR-VL-1.5 (Transiglobal)","api":"anthropic-messages","input":["text","image"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":131072,"maxTokens":8192},
+  {"id":"deepseek-v4-pro","name":"DeepSeek V4 Pro (Transiglobal)","api":"anthropic-messages","input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":1000000,"maxTokens":384000},
+  {"id":"deepseek-v4-flash","name":"DeepSeek V4 Flash (Transiglobal)","api":"anthropic-messages","input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":1000000,"maxTokens":384000},
+  {"id":"gpt-5.5","name":"GPT-5.5 (Transiglobal)","api":"openai-responses","input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":200000,"maxTokens":65536},
+  {"id":"gpt-5.6-sol","name":"GPT-5.6 Sol (Transiglobal)","api":"openai-responses","input":["text","image"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":372000,"maxTokens":128000},
+  {"id":"gpt-5.6-terra","name":"GPT-5.6 Terra (Transiglobal)","api":"openai-responses","input":["text","image"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":372000,"maxTokens":128000},
+  {"id":"gpt-5.6-luna","name":"GPT-5.6 Luna (Transiglobal)","api":"openai-responses","input":["text","image"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":372000,"maxTokens":128000},
+  {"id":"mimo-v2.5-pro","name":"MiMo 2.5 Pro (Transiglobal)","api":"anthropic-messages","input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":200000,"maxTokens":64000},
+  {"id":"mimo-v2.5","name":"MiMo 2.5 (Transiglobal)","api":"anthropic-messages","input":["text","image","video","audio"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":200000,"maxTokens":64000},
+  {"id":"claude-opus-4.7","name":"Claude Opus 4.7 (Transiglobal)","api":"anthropic-messages","input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":300000,"maxTokens":64000},
+  {"id":"qwen3.7-max","name":"Qwen 3.7 Max (Transiglobal)","api":"anthropic-messages","input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":1000000,"maxTokens":100000},
+  {"id":"qwen3.6-plus","name":"Qwen 3.6 Plus (Transiglobal)","api":"anthropic-messages","input":["text","image"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":1000000,"maxTokens":100000}
+]
 ```
 
-别名注册后可通过 `/alias` 快速切换模型。
+## 别名
 
-## 注意事项
+| 模型 ID | 别名 |
+|---|---|
+| GLM-5-Turbo | glm5t |
+| GLM-5.2 | glm52 |
+| GLM-4.5-Air | glm45a |
+| MiniMax-M2 | mxm2 |
+| MiniMax-M2.7 | mxm27 |
+| MiniMax-M3 | mxm3 |
+| kimi-for-coding | kimi |
+| GLM-5V-Turbo | glm5v |
+| PaddleOCR-VL-1.5 | pocr |
+| deepseek-v4-pro | dsv4p |
+| deepseek-v4-flash | dsv4f |
+| gpt-5.5 | gpt55 |
+| gpt-5.6-sol | g56s |
+| gpt-5.6-terra | g56t |
+| gpt-5.6-luna | g56l |
+| mimo-v2.5-pro | mimo25p |
+| mimo-v2.5 | mimo25 |
+| claude-opus-4.7 | opus47 |
+| qwen3.7-max | qwn37 |
+| qwen3.6-plus | qwn36 |
 
-- `agents.defaults.models` 设置后成为 **allowlist**，只有列表中的模型才可用
-- Provider 配置会写入 `models.json`，合并模式（merge）下不会覆盖已有配置
-- API Key 会从 `models.providers` 和 auth profiles 两处解析
-- 模型引用格式：`provider/model`（如 `trapi/GLM-5-Turbo`）
+别名没有强制五字符限制。优先简短、清晰、稳定，不自动改动用户已有别名。
 
-## 相关 CLI 命令
+对话中使用：
+
+```text
+/model glm5t
+/model mxm3
+/model g56s
+```
+
+## 图像模型
+
+支持图片输入：
+
+- MiniMax-M3
+- kimi-for-coding
+- GLM-5V-Turbo
+- PaddleOCR-VL-1.5
+- gpt-5.6-sol
+- gpt-5.6-terra
+- gpt-5.6-luna
+- mimo-v2.5
+- qwen3.6-plus
+
+imageModel 仅用于图像理解，不等同于图像生成模型。
+
+## 当前 OpenClaw 写入方式
+
+优先使用：
 
 ```bash
-openclaw models list           # 查看已配置模型
-openclaw models status         # 查看当前模型和认证状态
-openclaw models aliases list   # 查看所有别名
-openclaw models aliases add <alias> <provider/model>  # 添加别名
+openclaw config set models.providers.trapi '<provider-json>' --strict-json --merge
+openclaw config set models.providers.trapi.models '<model-array-json>' --strict-json --merge
+openclaw models aliases add <alias> trapi/<model-id>
+openclaw models set-image trapi/<model-id>
+openclaw models image-fallbacks add trapi/<model-id>
 ```
+
+不要把模型或别名更新写成 Agent 侧 `gateway config.patch`。当前 OpenClaw 会保护全局模型配置路径，且 Patch 中数组不是按模型 ID 自动追加。
+
+## 故障排查
+
+- 401/403：检查 Gateway 服务是否能解析 `TRAPI_API_KEY` SecretRef。
+- Model not found：核对模型 ID 大小写及 trapi 实际开放目录。
+- 协议错误：核对模型级 `api`，GPT 模型使用 `openai-responses`，其余目录条目使用各自声明值。
+- 别名冲突：执行 `openclaw models aliases list --json`，由用户决定保留或重定向。
+- 配置写入被拒绝：重新读取目标路径并使用 `--merge`；不要直接改用 `--replace`。
+- 图像未传入模型：确认模型 `input` 包含 `image`，并检查 imageModel 配置。
+- `available: true` 但调用失败：该状态不证明上游推理可用，需要经用户确认后做最小实时请求。
\ No newline at end of file