🧭 灵犀路由 v2.2.0 — 模型路由 & 参数管理 & 持久化 & 一键自检+自修复 & 快速切换

> 面向小艺Claw用户。提供模型API接入、模型切换、参数修改并持久化、一键自检+自修复脚本、快速切换(Reply-Before-Switch)、子代理独立模型、重启安全协议。

> 切换命令秒回！说「模型参数」可查看和修改全局默认模型。说「自检模型」一键跑 selfcheck.py --fix 出报告+自动修复。

零、使用说明

这个技能适合谁？

• ✅ 有小艺Claw / OpenClaw 环境
• ✅ 有自己的外部 API Key（DeepSeek、OpenAI 等）
• ✅ 想自由切换模型：Flash快省、Pro深度推理
• ✅ 想自由调模型参数：上下文窗口、最大输出、推理开关、思考深度
• ✅ 会基本的命令行操作

什么情况下用？

一、安装

> ✅ 安装/覆盖安装已统一封装为脚本。

> 新用户 → 无残留，直接写入全新配置

> 老用户 → 先彻底清干净旧版所有痕迹，再写入全新配置

> 两场景走同一脚本，幂等安全。

交互流程

① 用户说「安装灵犀路由」
         ↓
② AI 读 SKILL.md → 安装 skill → 需要 API Key
         ↓
③ AI 问 ➡️ 「老大，要装灵犀路由需要 DeepSeek API Key，按下面步骤获取后发给我就行👇」
         ↓
         ╔══════════════════════════════════════════════════════════╗
         ║  🔑 DeepSeek API Key 获取流程                          ║
         ╠══════════════════════════════════════════════════════════╣
         ║                                                          ║
         ║  ① 打开浏览器，访问 platform.deepseek.com               ║
         ║     （DeepSeek 开放平台）                                ║
         ║                                                          ║
         ║  ② 登录账号                                              ║
         ║     已有账号 → 直接登录                                  ║
         ║     没有账号 → 点「注册」用手机/邮箱注册                 ║
         ║                                                          ║
         ║  ③ 登录后，在左侧菜单点「API Keys」                      ║
         ║     （或访问 platform.deepseek.com/api_keys）             ║
         ║                                                          ║
         ║  ④ 点击「创建 API Key」                                  ║
         ║                                                          ║
         ║  ⑤ 给 Key 取个名字（比如「灵犀路由」）→ 确认创建         ║
         ║                                                          ║
         ║  ⑥ 复制生成的 Key（以 sk- 开头的一串字符）               ║
         ║     ⚠️ 关掉页面后 Key 不再完整显示，务必立即复制          ║
         ║                                                          ║
         ║  ⑦ 把 Key 发给我就行（像这样：sk-abc123...）              ║
         ║                                                          ║
         ╚══════════════════════════════════════════════════════════╝
         ↓
④ 用户把 Key 发给 AI
         ↓
         ↓
⑤ AI 执行：bash setup.sh "sk-xxx..."
         ↓
   脚本内部自动完成：
   ├─ 清理旧备份 → 保留最近3份，其余删除
   ├─ 清理模型偏好文件
   ├─ 清理无引用的 model_manager.py
   ├─ 删除旧 .last-good（后续重建）
   ├─ 新用户 → 无文件，直接跳过
         ↓
   ┌─ 写入全新配置 ────────────────────────────────────┐
   │  DeepSeek Provider（Flash + Pro）                │
   │  模型白名单 + 全局默认模型 = 小艺                 │
   │  思考深度 = high + 模型偏好文件                   │
   │  compaction: reserveTokens=200k + reserveTokensFloor=25k  │
   │  .last-good 同步 + 输出引导块                     │
   └──────────────────────────────────────────────────┘
         ↓
⑤b AI 执行：bash skills/lingxi-router/scripts/setup.sh "sk-你的DeepSeekAPIKey"
         ↓
⑥ AI 执行重启（三步安全协议，不可跳过）

   **Step 1：【发预告】** 告知用户不要发消息
   **Step 2：【等 3 秒 + 重启 + 轮询直到就绪（30 秒超时）】**
   **Step 3：【报平安】** ✅ 通知用户

---

## 二、前置检查

which openclaw

python3 --version

curl --version

python3 -m supervisor.supervisorctl status openclaw-gateway

---

## 三、快速入门

安装完成后：
- 说「**切换Pro**」切深度推理，说「**切换V4**」切快省模式
- 说「**模型参数**」查看/修改所有参数（含全局默认模型、compaction等19项）
- 说「**自检模型**」一键检测+修复配置问题

---

## 四、核心概念

### 路由架构

| 触发方式 | 标签 | 模型 | 说明 |
|:--------:|:----|:----|:------|
| `切换V4` | 💠[Flash] | deepseek-v4-flash | 快省 |
| `切换Pro` | 🔷[Pro] | deepseek-v4-pro | 深度推理 |
| `切换小艺` | 🎐[小艺] | 小艺 | 回系统默认 |

### 模型参数（模型参数 命令）

说 `模型参数` → AI 执行。

#### 展示阶段

读取所有模型

openclaw config get models.providers | python3 -m json.tool

读取全局思考深度

openclaw config get agents.defaults.thinkingDefault

读取 contextPruning/compaction 等（路径是 agents.defaults.*，不是根级）

openclaw config get agents.defaults.contextPruning 2>/dev/null | python3 -c 'import json,sys;d=json.load(sys.stdin);print(json.dumps({"ttl":d.get("ttl"),"mode":d.get("mode"),"softTrimRatio":d.get("softTrimRatio"),"keepLastAssistants":d.get("keepLastAssistants")},ensure_ascii=False))'

openclaw config get agents.defaults.compaction 2>/dev/null | python3 -c 'import json,sys;d=json.load(sys.stdin);print(json.dumps({"reserveTokens":d.get("reserveTokens"),"reserveTokensFloor":d.get("reserveTokensFloor"),"mode":d.get("mode"),"recentTurnsPreserve":d.get("recentTurnsPreserve")},ensure_ascii=False))'

展示时每个参数标注：**英文名 — 中文名 — 当前值 — 作用说明**

输出示例：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

① xiaoyiprovider（小艺通道）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚡ LLM_DeepSeekV4_Thinking（不支持外部修改）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

② deepseek（api.deepseek.com）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🧠 deepseek-v4-flash

├─ contextWindow — 上下文窗口 — 1,000,000 — 模型一次能看的文本量，越大越贵

├─ maxTokens — 最大输出长度 — 384,000 — 限制回复长度，超了会被截断

├─ reasoning — 推理开关 — True — 开则输出思考链，关则直接回答（更快更省）

├─ thinking — 思考深度 — high — 控制推理深度: off低/medium中/high高/max最高

├─ temperature — 温度(0-2) — 0.3 — 控制随机性: 越低越确定/越高越有创意

├─ top_p — 采样范围(0-1) — 0.5 — 控制词汇选择范围: 越低越保守

├─ presence_penalty — 重复惩罚(-2~2) — 0.1 — 越高越避免重复话题

├─ seed — 随机种子 — None — 固定值可复现相同结果，调试用

├─ maxTokensField — 字段名 — 未设 — ⚠️ DeepSeek V4 须用 max_completion_tokens

└─ thinkingFormat — 思考格式 — deepseek — deepseek/openai 格式

🧠 deepseek-v4-pro（同上）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

③ Provider 级

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⏱ timeoutSeconds — API超时时间 — 120s — 超时未响应则报错，调大治标

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

④ 全局设置

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🤖 model.primary — 全局默认模型 — xiaoyiprovider/LLM_DeepSeekV4_Thinking — 所有新会话默认走的模型

🧠 thinkingDefault — 默认思考深度 — high — 所有模型的默认值

📐 contextPruning:

├─ mode — 裁剪模式 — cache-ttl — cache-ttl/safeguard/none

├─ ttl — 裁剪TTL — 300s — 超过时间自动裁剪旧内容

├─ softTrimRatio — 软裁剪比例 — 0.06 (6%) — 每次裁剪多少比例

└─ keepLastAssistants — 保留最近助手回复 — 5 — 不被裁剪的最少回复条数

📦 compaction:

├─ mode — 压缩模式 — safeguard — safeguard/compact/none

├─ reserveTokens — 保留Token数 — 200,000 — 压缩后保留多少内容

├─ reserveTokensFloor — 最低保留数 — 25,000 — ⚠️ Pro+max建议≥200k，低于此值强制保留

└─ recentTurnsPreserve — 保留最近对话轮数 — 2 — 最近N轮不被压缩

> **⚠️ 高风险提示**：修改模型参数会影响模型的行为和稳定性。
> 修改前建议先备份 `openclaw.json`，修改后需重启 Gateway 生效。
> 请只修改你理解用途的参数。

展示后询问：
> 「老大，参数全在这了。想改什么直接说~」
>   💬 比如：
>     「Flash 温度降到 0.3」
>     「Pro 思考拉满」
>     「Flash 关推理」
>     「改超时 120」
>     「全局默认改成 Flash」  ← 改所有新会话默认模型
>     「compaction 调大到 300k」 ← 防止 Pro max 上下文超限
>     「软裁剪比例调到 10%」  ← 调大 contextual 裁剪
>     「不改了」

#### 修改阶段（统一流程）

用户说了修改意图后，按以下流程执行（每步不可跳过）：

① 接收指令 → 解析（模型名 + 参数名 + 新值）

② 校验

├─ 模型名存在 openclaw.json（models.providers.*）中？→ 不存在则告知「没找到模型 xxx」→ 回询问

├─ 参数名合法？→ 不在支持列表中则告知「参数 yyy 不支持」→ 回询问

└─ 值在合理范围？→ 超出范围则告知「值 xxx 不对，建议范围是...」→ 回询问

③ 询问备份

→「需要修改前先备份吗？备份好了告诉我「继续」」

→ 用户说「继续」→ 执行

→ 用户说「不了/不备份」→ 也执行（尊重用户决定）

④ 执行修改

> 🚨 【持久化铁律】不要改 models.json！不要改 models.json！不要改 models.json！

> Gateway 启动时用 openclaw.json 覆盖 models.json，改 models.json 重启就丢。

> 正确操作：所有 Provider 级修改走 openclaw config set models.providers. → 持久化到 openclaw.json → 重启保留。

按参数类型映射到具体修改位置：

| 参数 | 修改位置 | 命令参考 |

|:----|:--------|:---------|

| contextWindow / maxTokens / reasoning | openclaw.json models.providers.xxx | openclaw config set [models.providers.xxx]（全量写入） |

| temperature / top_p / presence_penalty / seed | openclaw.json models.providers.xxx | openclaw config set [models.providers.xxx]（全量写入） |

| maxTokensField / thinkingFormat | openclaw.json models.providers.xxx | openclaw config set [models.providers.xxx]（全量写入） |

| thinking | ① openclaw.json models.providers.xxx compat ② config | ①全量写入 ② config set agents.defaults.thinkingDefault |

| timeoutSeconds | openclaw.json models.providers.xxx | openclaw config set [models.providers.xxx]（全量写入） |

| contextPruning.ttl | openclaw.json agents.defaults | openclaw config set agents.defaults.contextPruning.ttl |

| contextPruning.mode | openclaw.json agents.defaults | openclaw config set agents.defaults.contextPruning.mode |

| contextPruning.softTrimRatio | openclaw.json agents.defaults | openclaw config set agents.defaults.contextPruning.softTrimRatio |

| contextPruning.keepLastAssistants | openclaw.json agents.defaults | openclaw config set agents.defaults.contextPruning.keepLastAssistants |

| compaction.reserveTokens | openclaw.json agents.defaults | openclaw config set agents.defaults.compaction.reserveTokens |

| compaction.reserveTokensFloor | openclaw.json agents.defaults | openclaw config set agents.defaults.compaction.reserveTokensFloor |

| compaction.mode | openclaw.json agents.defaults | openclaw config set agents.defaults.compaction.mode |

| compaction.recentTurnsPreserve | openclaw.json agents.defaults | openclaw config set agents.defaults.compaction.recentTurnsPreserve |

| model.primary（全局默认模型） | openclaw.json agents.defaults.model | openclaw config set agents.defaults.model.primary "xxx" |

修改操作示例（以改 Flash temperature 为例）：

1. 读取当前 Provider 配置：openclaw config get models.providers.deepseek
2. 用 Python 脚本修改 JSON 中的对应参数
3. 全量写回：openclaw config set models.providers.deepseek '修改后的JSON'

思考深度两步骤示例（以 DeepSeek Pro 改 thinking=high 为例）：

```bash

# 步骤一：Provider 兼容性声明（让 API 端知道支持什么档位）

# 在 Provider JSON 的对应模型 compat 中确认以下字段：

# "compat": {

# "supportsReasoningEffort": true,

# "supportedReasoningEfforts": ["off","low","medium","high","max"],

# "reasoningEffortMap": {"off":"off","low":"low","medium":"high","high":"high","max":"max"},

# "thinkingFormat": "deepseek"

# }

# 然后全量写回：

openclaw config set models.providers.deepseek '修改后的完整JSON'

# 步骤二：Agent 默认思考等级（让新会话默认走这个深度）

openclaw config set agents.defaults.thinkingDefault high

# 两步都完成 → 同步 .last-good → 重启 Gateway 生效

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.last-good

python3 -m supervisor.supervisorctl restart openclaw-gateway

```

⑤ 写入后验证 → 读回 openclaw.json（不是 models.json），确认值已按预期写入

```bash

openclaw config get models.providers.deepseek | python3 -c '

import json,sys; d=json.load(sys.stdin)

for m in d["models"]: print(f"{m["id"]}: params={json.dumps(m.get("params",{}))}")

print(f"timeout: {d.get("timeoutSeconds")}s")

'

```

├─ 一致 → 进入下一步

└─ 不一致 → 告知用户「写入失败，请检查文件权限或手动修改」

⑥ 同步 .last-good 备份 → Gateway 重启可能从 .last-good 恢复，必须确保它是最新版本

```bash

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.last-good

```

├─ 成功 → 「✅ .last-good 已同步，重启不会丢配置」

└─ 失败 → 警告但继续

⑦ 执行重启（走 §一第⑥步的三步安全协议）

同 §一第⑥步的完整三步协议：发预告 → 等3秒+重启+轮询就绪 → 报平安

> ⚠️ 所有修改 `openclaw.json` 或 config 的操作，修改后必须重启 Gateway 才能生效。

> 🚨 **⚠️ 高风险操作警告 ⚠️**
> **修改模型参数会影响模型的行为和 Gateway 的稳定性**，错误的参数可能导致模型无法运行、会话损坏甚至 Gateway 崩溃。
> **修改前请务必自行备份** `openclaw.json`，修改后如有异常可通过回滚 SOP 恢复（见 §七）。
> 建议只修改自己理解用途的参数。

#### 参数速查表（含中文名+作用）

| 参数 | 中文名 | 作用 | 修改位置 | 风险 |
|:----|:------|:----|:--------|:---:|
| contextWindow | 上下文窗口 | 模型一次能看多少文本，越大越贵 | openclaw.json models.providers.xxx | 中 |
| maxTokens | 最大输出长度 | 限制回复长度，超了被截断 | openclaw.json models.providers.xxx | 低 |
| reasoning | 推理开关 | 开则输出思考链，关则更快更省 | openclaw.json models.providers.xxx | 低 |
| temperature | 温度 | 控制随机性：低→确定，高→创意(0-2) | openclaw.json models.providers.xxx | 中 |
| top_p | 采样范围 | 控制词汇选择范围：低→保守(0-1) | openclaw.json models.providers.xxx | 中 |
| presence_penalty | 重复惩罚 | 越高越避免重复话题(-2~2) | openclaw.json models.providers.xxx | 低 |
| seed | 随机种子 | 固定值可复现相同结果，调试用 | openclaw.json models.providers.xxx | 低 |
| thinking | 思考深度 | off/med/high/max 控制推理深度 | openclaw.json compat + config | 低 |
| **model.primary** | **全局默认模型** | **所有新会话默认走哪个模型** | **openclaw.json agents.defaults** | **低** |
| maxTokensField | 字段名 | ⚠️ 配错则 maxTokens 不生效 | openclaw.json models.providers.xxx | 高 |
| thinkingFormat | 思考格式 | deepseek/openai 格式选择 | openclaw.json models.providers.xxx | 中 |
| timeoutSeconds | API超时 | 超时未响应报错，调大治标 | openclaw.json models.providers.xxx | 低 |
| contextPruning.mode | 裁剪模式 | cache-ttl/safeguard/none | openclaw.json agents.defaults.* | 低 |
| contextPruning.ttl | 裁剪TTL | 超过时间自动裁剪旧内容 | openclaw.json agents.defaults.* | 中 |
| contextPruning.softTrimRatio | 软裁剪比例 | 每次裁剪多少比例(0-1) | openclaw.json agents.defaults.* | 中 |
| contextPruning.keepLastAssistants | 保留助手回复 | 不被裁剪的最少回复条数 | openclaw.json agents.defaults.* | 低 |
| compaction.mode | 压缩模式 | safeguard/compact/none | openclaw.json agents.defaults.* | 低 |
| compaction.reserveTokens | 保留Token | 压缩后保留多少内容，⚠️ Pro+max建议≥200k | openclaw.json agents.defaults.* | 中 |
| compaction.reserveTokensFloor | 最低保留数 | 低于此值强制保留，防Context超限 | openclaw.json agents.defaults.* | 中 |
| compaction.recentTurnsPreserve | 保留最近轮数 | 最近N轮对话不被压缩 | openclaw.json agents.defaults.* | 低 |

---

## 五、模型参数自检+自修复

> 推荐方案：一键运行 `python3 ~/.openclaw/workspace/skills/lingxi-router/selfcheck.py --fix`
> 自动检测 16 项配置问题 + 自动修复（.last-good 同步、白名单注册、偏好文件生成等）

快速查看关键配置：

| 查看项 | 命令 |
|:------|:-----|
| Provider | `openclaw config get models.providers` |
| 白名单 | `openclaw config get agents.defaults.models` |
| 思考深度 | `openclaw config get agents.defaults.thinkingDefault` |
| 上下文裁剪 | `openclaw config get agents.defaults.contextPruning` |

------

## 六、注意事项

### 安全
- API Key 明文 → `chmod 600`，不提交 Git

### 多 Provider 场景
- 配置多个 Provider（如 OpenAI + DeepSeek）时，模型 ID 格式为 `provider/model`：
  - `deepseek/deepseek-v4-flash` ✓
  - `openai/gpt-4o` ✓
- 修改参数时需确认目标模型所在的 Provider 名
- `openclaw config set models.providers.<name>` 的 `<name>` 要区分不同 Provider

### 陷阱
| 陷阱 | 级别 | 说明 |
|:----|:----:|:------|
| 没重启不生效 | 🔴 | 改 openclaw.json（通过 config set）或 thinkingDefault 后必须重启 |
| 思考深度因模型而异 | 🟡 | DeepSeek V4 原生 high/max 两档，off/low 可能降级 |
| 重启后 App 报异常 | 🟢 | 正常，10-15秒恢复 |
| 子代理报 401 | 🔴 | Key 被 Secret Guardian 加密 | AI 自动兜底：读 Key → 若加密 → 重写原始 Key → 重试子代理 |
| .last-good 不同步 | 🟡 | 改配置后 .last-good 没同步，重启可能从旧版恢复 | 每次改配置后自动 `cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.last-good` |
| 重启窗口期发消息 | 🟡 | Gateway 重启 → WebSocket 断开 → 用户消息 → session 损坏 → "Something went wrong" | AI 走重启安全协议（§一第⑥步）；用户发 `/new` 自救 |
| Pro+max Context超限 | 🟡 | Pro max 输出量大 → compaction.reserveTokens 不够 → Context limit exceeded | 调大 reserveTokens 到 200k+ 或降 thinking 档位 |

### AI 操作规则：子代理 401 兜底
> 派子代理指定模型后，若收到 401 失败回传，按以下顺序自动处理：
> 1. `openclaw config get models.providers.xxx` 读 Key
> 2. 若 Key 格式含 `__OPENCLAW__` 标记，重写原始 Key
> 3. 重新派子代理
> 4. 告知用户「Key 已修复，已重试成功」

### 思考深度档位参考
| 档位 | OpenClaw 行为 | DeepSeek V4 映射 |
|:----|:-------------|:----------------:|
| off | 关思考 | off |
| minimal | 极简 | low |
| low | 低 | low |
| medium | 中 | high |
| high | 高级 | high |
| xhigh | 极限 | max |
| max | 最大 | max |

### 成本参考
| 模型 | 输入/M | 输出/M |
|:----|:------|:------|
| 小艺 | AI点 | AI点 |
| Flash | $0.14 | $0.28 |
| Pro | $0.435 | $0.87 |

---

## 七、回滚 SOP

从 .last-good（上次成功的完整配置）恢复

cp ~/.openclaw/openclaw.json.last-good ~/.openclaw/openclaw.json

或从手动备份恢复

cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

python3 -m supervisor.supervisorctl restart openclaw-gateway

> ⚠️ **回滚后请检查：** `model.primary`（全局默认模型）可能回退到旧值，说「模型参数」查看，如需恢复说「全局默认改成 xxx」重新设置。

---

## 八、全局默认模型

### 概念
- **全局默认模型** `agents.defaults.model.primary`：影响**所有新创建的会话**默认走哪个模型
- **会话覆盖** `session_status model=xxx`：只影响**当前这一个会话**，优先级高于全局默认
- **偏好自恢复** `user-model-preference.md`：重启后首轮自恢复时恢复「上次用的模型」

三层优先级：会话覆盖 > 偏好自恢复 > 全局默认

### 和切换命令的关系
| 命令 | 效果 | 说明 |
|:----|:----|:------|
| 「切换V4」 | 当前会话 → Flash | 不影响全局默认 |
| 「切换小艺」 | 当前会话 → 小艺 | 永远有效，不受全局默认影响 |
| 「模型参数」→ 说「全局默认改成 Flash」 | 所有新会话 → Flash | 修改后走重启安全协议生效 |
| 先切Pro → 再设全局默认Flash → 重启 | 当前会话继续用Pro，新会话用Flash | 两者独立，互不影响 |
| 全局默认Flash → 重启 → 说「切换小艺」 | 当前会话切回小艺 ✅ | 切换命令覆盖全局默认 |

### 子代理默认模型
子代理的默认模型也走 `agents.defaults.model.primary`
- 设全局默认后，新派子代理自动走新模型
- 不想走则创建子代理时指定 model=xxx 覆盖

---

## 九、错误诊断指南

### 「Something went wrong」排查

| 现象 | 原因 | 解决 |
|:----|:----|:-----|
| 刚改完参数重启后发消息报错 | session 连接未就绪 | 发 `/new` 开启新会话 |
| 重启后切换模型报错 | 同上，非切换本身问题 | 发 `/new` 再试 |
| 重启后一直报错 | Gateway 未完全启动 / 配置损坏 | `/new` → 等15秒 → 说「紧急恢复」 |
| 参数值写错导致运行时异常 | 参数超出模型支持范围 | 说「自检模型」一键修复 |
| Pro+max → Context limit exceeded | Pro max 输出量大，compaction.reserveTokens 不够 | 调大到 200k+，或降低 thinking 档位 |

### 用户自救流程
用户遇到报错时，按顺序试：
1. 发 `/new`（最快，90% 解决）
2. 等 15 秒再发一次
3. 说「紧急恢复」→ 自动触发 .last-good 回滚

---

> **灵犀路由 · 2026-06-08 · v2.2.0**
> 更新内容：重启安全协议（三步协议）/ 全局默认模型展示与修改（模型参数内） / 新增6项全局参数展示与修改 / compaction 默认值优化 / 高风险操作警告 / 错误诊断指南
> 此路或有蹉跎，君莫忘 必有灵犀相佐 😊