Profile Model Manager

查看、更换和管理 Hermes 各 profile 的大模型配置（主模型、辅助模型、delegation 模型）。支持单个/批量操作、切换 provider、全 profile 一览。

Install

openclaw skills install @youbuwei/hermes-profile-model-manager

Profile Model Manager

管理 Hermes 各 profile 的全部模型配置——主模型、辅助模型（vision / compression / web_extract / session_search）、delegation 模型。支持查看、切换、批量操作。

适用场景： 需要查看或切换 Hermes 各 profile 的大模型时使用本 skill。 不适用场景： 安装新 provider、配置 API Key（参见 hermes-agent skill）；管理 MCP 模型（参见 native-mcp skill）。

🤖 Agent 智能触发指引

当用户说以下任何一种话时，Agent 应自动加载并使用本 skill：

用户意图	触发关键词示例
查看当前模型	"现在用的什么模型"、"模型配置"、"看看模型"、"model 配置"
切换模型	"换成 xxx 模型"、"切到 xxx"、"用 glm-5"、"换 provider"
批量操作	"所有 profile 都换成"、"统一切换"、"批量改模型"
诊断问题	"模型报错了"、"API key 找不到"、"切换不生效"、"context too small"
辅助模型	"vision 模型"、"compression"、"web_extract"、"session_search 模型"
delegation	"子 agent 用什么模型"、"delegation 模型"、"delegate 便宜点"

Agent 使用流程：

用户表达意图 → 加载本 skill
先用 bash ~/.hermes/scripts/profile-model-overview.sh 展示当前状态
根据意图执行对应操作
操作后验证结果（见 §3 操作效果示例）
如需重启 Gateway，主动提醒用户

0. 快速开始

30 秒上手：

bash

# 查看所有 profile 模型全景
bash ~/.hermes/scripts/profile-model-overview.sh

# 查看单个 profile 详情
bash ~/.hermes/scripts/profile-model-overview.sh reasoner

# 预览切换到智谱的效果（不修改任何配置）
bash ~/.hermes/scripts/profile-model-overview.sh reasoner zhipu

# 确认执行：一键切换所有模型 + 自动重启 Gateway
bash ~/.hermes/scripts/profile-model-overview.sh reasoner --apply zhipu

前置条件：

Hermes Agent 已安装（hermes --version 可用）
目标 provider 的 API Key 已配置在对应 profile 的 .env 中
切换后必须重启 Gateway 才能生效

1. 模型配置架构

每个 profile 的 config.yaml 中有三个模型相关配置块：

yaml

model:          ← 主模型（对话用）
auxiliary:      ← 辅助模型（vision / compression / web_extract / session_search）
delegation:     ← 子 agent 模型（delegate_task 时使用）

1.1 主模型 `model:`

yaml

model:
  default: mimo-v2.5-pro        # 模型名称
  provider: xiaomi               # provider 名称
  base_url: https://...          # API 端点（部分 provider 可省略）
  api_key: xxx                   # 可选，也可放 .env
  context_length: 200000         # 上下文窗口大小
  api_mode: chat_completions     # API 模式

1.2 辅助模型 `auxiliary:`

yaml

auxiliary:
  vision:                        # 图片分析、截图识别
    provider: xiaomi
    model: mimo-v2-omni
    base_url: https://...
    timeout: 120
  compression:                   # 上下文压缩
    provider: xiaomi
    model: mimo-v2.5
    base_url: https://...
    timeout: 120
  web_extract:                   # 网页内容提取
    provider: xiaomi
    model: mimo-v2.5
    base_url: https://...
    timeout: 360
  session_search:                # 历史会话搜索
    provider: xiaomi
    model: mimo-v2.5
    base_url: https://...
    timeout: 30
    max_concurrency: 3

1.3 Delegation 模型 `delegation:`

yaml

delegation:
  model: mimo-v2.5               # 空则继承主模型
  provider: xiaomi
  base_url: ''                   # 空则继承主模型 base_url
  reasoning_effort: ''
  max_iterations: 50
  max_concurrent_children: 3

2. 查看模型配置

bash

# 查看 default profile 的完整配置
hermes config show

# 查看指定 profile 的主模型
cat ~/.hermes/profiles/<name>/config.yaml | grep -A5 "^model:"

# 查看指定 profile 的辅助模型
cat ~/.hermes/profiles/<name>/config.yaml | grep -A20 "^auxiliary:"

# 查看指定 profile 的 delegation 模型
cat ~/.hermes/profiles/<name>/config.yaml | grep -A10 "^delegation:"

# 一键查看所有 profile 模型全景
bash ~/.hermes/scripts/profile-model-overview.sh

hermes config show 预期输出（片段）：

yaml

model:
  default: mimo-v2.5-pro
  provider: xiaomi
  base_url: https://token-plan-cn.xiaomimimo.com/v1
  context_length: 200000
  api_mode: chat_completions
auxiliary:
  vision:
    provider: xiaomi
    model: mimo-v2-omni
  compression:
    provider: xiaomi
    model: mimo-v2.5
  ...

⚠️ 注意： 如果 cat 命令返回空，说明 config.yaml 中没有该配置块。此时需要检查是否使用了正确的 profile 路径：~/.hermes/profiles/<name>/config.yaml（注意 default profile 的路径是 ~/.hermes/config.yaml）。

3. 切换模型

3.1 切换单个 profile 的主模型

bash

# 对 default profile（不加 -p 参数）
hermes config set model.default <model_name>
hermes config set model.provider <provider>
hermes config set model.base_url <base_url>

# 对其他 profile（必须加 -p <name>）
hermes -p <profile> config set model.default <model_name>
hermes -p <profile> config set model.provider <provider>
hermes -p <profile> config set model.base_url <base_url>

操作效果示例：

bash

$ hermes -p reasoner config set model.default glm-5.1
✅ Set model.default = glm-5.1

$ hermes -p reasoner config set model.provider zhipu
✅ Set model.provider = zhipu

切换后必须重启：

bash

hermes -p <profile> gateway restart

重启效果：

bash

$ hermes -p reasoner gateway restart
🔄 Restarting gateway for profile 'reasoner'...
✅ Gateway restarted successfully

3.2 切换辅助模型

bash

hermes config set auxiliary.vision.provider <provider>
hermes config set auxiliary.vision.model <model>
hermes config set auxiliary.vision.base_url <url>

hermes config set auxiliary.compression.provider <provider>
hermes config set auxiliary.compression.model <model>

hermes config set auxiliary.web_extract.provider <provider>
hermes config set auxiliary.web_extract.model <model>

hermes config set auxiliary.session_search.provider <provider>
hermes config set auxiliary.session_search.model <model>

Per-profile 用法同理加 -p <name>。

3.3 切换 Delegation 模型

bash

hermes -p <profile> config set delegation.model <model>
hermes -p <profile> config set delegation.provider <provider>

设为空字符串即回到继承主模型的行为：

bash

hermes -p <profile> config set delegation.model ""
hermes -p <profile> config set delegation.provider ""

3.4 批量操作所有 profile

bash

# 切换所有 profile 主模型
for p in default cto diary genshin reasoner scout qian-duoduo; do
  if [ "$p" = "default" ]; then
    hermes config set model.default glm-5-turbo
    hermes config set model.provider zhipu
  else
    hermes -p "$p" config set model.default glm-5-turbo
    hermes -p "$p" config set model.provider zhipu
  fi
done

3.5 批量重启 Gateway

bash

# 重启所有运行中的 profile
hermes profile list 2>/dev/null | grep "running" | awk '{print $1}' | sed 's/◆//' | while read p; do
  hermes -p "$p" gateway restart
done

3.6 操作后验证（重要！）

每次切换后，务必执行验证确认生效：

bash

# 方法 1：查看配置是否写入成功
hermes -p <profile> config show | grep "default:" -A1

# 预期输出：
#   default: glm-5.1      ← 看到这里是新模型名就对了

# 方法 2：发送测试消息确认模型实际响应
hermes -p <profile> chat -q "你是什么模型？回答模型名称即可" -Q

# 方法 3：确认 Gateway 状态
hermes -p <profile> gateway status

# 预期输出：
# ◆ reasoner: running     ← 必须是 running

⚠️ 如果验证方法 2 的回答仍是旧模型，说明 Gateway 没有成功重启，请重新执行 hermes -p <profile> gateway restart。

4. Provider 速查表

Provider	Env 变量	Base URL	说明
`xiaomi`	`XIAOMI_API_KEY`	`https://token-plan-cn.xiaomimimo.com/v1`	小米 MiMo
`zhipu`	`ZHIPU_API_KEY`	`https://open.bigmodel.cn/api/coding/paas/v4`	智谱 Coding Plan（国内，订阅制）
`zhipu-direct`	`ZHIPU_API_KEY`	`https://open.bigmodel.cn/api/paas/v4`	智谱 Direct API（国内，按量计费）
`zai`	`ZAI_API_KEY`	`https://api.z.ai/api/coding/paas/v4`	智谱 Coding Plan（国际版，订阅制）
`zai-direct`	`ZAI_API_KEY`	`https://api.z.ai/api/paas/v4`	智谱 Direct API（国际版，按量计费）

智谱四通道说明：

zhipu — 国内 Coding Plan，订阅制，仅限 Coding 工具环境，端点 open.bigmodel.cn
zhipu-direct — 国内通用 Direct API，按量计费，无使用场景限制，可访问全部模型（含 glm-5.1）
zai — 国际版 Coding Plan，订阅制，端点 api.z.ai
zai-direct — 国际版通用 Direct API，按量计费，端点 api.z.ai

国内版和国际版使用不同的 API Key（ZHIPU_API_KEY vs ZAI_API_KEY），切换时需确认 .env 中有对应 key。

自定义 Provider 在 config.yaml 的 custom_providers: 中定义：

yaml

custom_providers:
- name: zhipu
  base_url: https://open.bigmodel.cn/api/coding/paas/v4
  api_key: xxx
  api_mode: chat_completions

⚠️ Base URL 规则：

内置 provider（xiaomi/zhipu/openrouter 等）：base_url 可省略，Hermes 自动填充
自定义 provider：base_url 必须显式指定，否则报错
切换 provider 时如果两个 provider 的 base_url 不同，必须同时设置 base_url

5. 模型参考

智谱（国内 `zhipu` / 国际 `zai`）

以下模型同时适用于 zhipu / zhipu-direct / zai / zai-direct 四个 provider。

Coding Plan 可用模型：

模型	上下文	最大输出	适用场景
`glm-5-turbo`	200K	128K	通用对话，高性价比
`glm-4.7`	200K	128K	通用推理，支持 thinking 模式
`glm-4.5-air`	200K	8K	辅助模型专用，极致性价比

Direct API 额外可用模型：

| 模型 | 上下文 | 最大输出 | 适用场景 | | glm-5.1 | 200K | 128K | 复杂推理，最强能力 | | glm-5 | 200K | 128K | 通用推理 |

端点差异：

Provider	Base URL	可用模型
`zhipu`	`open.bigmodel.cn/api/coding/paas/v4`	Coding Plan 模型
`zhipu-direct`	`open.bigmodel.cn/api/paas/v4`	全部模型
`zai`	`api.z.ai/api/coding/paas/v4`	Coding Plan 模型
`zai-direct`	`api.z.ai/api/paas/v4`	全部模型
文档：https://docs.bigmodel.cn/cn/guide/start/model-overview

小米 MiMo

模型	上下文	适用场景
`mimo-v2.5-pro`	1M	通用对话、长上下文
`mimo-v2.5`	1M	辅助模型、高性价比
`mimo-v2-omni`	—	多模态（vision）

6. 典型工作流

场景 1：临时切换测试模型

bash

# 切到测试模型
hermes -p reasoner config set model.default glm-5.1
hermes -p reasoner config set model.provider zhipu
hermes -p reasoner gateway restart

# ✅ 验证切换成功
hermes -p reasoner config show | grep "default:" -A1
# 预期输出：
#   default: glm-5.1

# 测试模型是否正常响应
hermes -p reasoner chat -q "你好，请确认你的模型名称" -Q
# 预期输出应提到 glm-5.1 或智谱

# 测试完毕后切回
hermes -p reasoner config set model.default mimo-v2.5-pro
hermes -p reasoner config set model.provider xiaomi
hermes -p reasoner gateway restart

# ✅ 验证切回成功
hermes -p reasoner config show | grep "default:" -A1
# 预期输出：
#   default: mimo-v2.5-pro

场景 2：所有 profile 统一切换

bash

# 批量切换
for p in default cto diary genshin reasoner scout qian-duoduo; do
  if [ "$p" = "default" ]; then
    hermes config set model.default glm-5-turbo
    hermes config set model.provider zhipu
  else
    hermes -p "$p" config set model.default glm-5-turbo
    hermes -p "$p" config set model.provider zhipu
  fi
done

# 批量重启
hermes profile list 2>/dev/null | grep "running" | awk '{print $1}' | sed 's/◆//' | while read p; do
  hermes -p "$p" gateway restart
done

# ✅ 验证全景
bash ~/.hermes/scripts/profile-model-overview.sh
# 预期：所有 profile 的 Model 列都显示 glm-5-turbo

场景 3：只改辅助模型

bash

# 换一个更强的 vision 模型（主模型不变）
hermes config set auxiliary.vision.provider zhipu
hermes config set auxiliary.vision.model glm-5.1
hermes gateway restart

# ✅ 验证
hermes config show | grep -A3 "vision:"
# 预期输出：
#   vision:
#     provider: zhipu
#     model: glm-5.1

场景 4：Delegation 用便宜模型省钱

bash

# delegation 用轻量模型，主模型保持强模型
hermes config set delegation.model glm-5-turbo
hermes config set delegation.provider zhipu
hermes gateway restart

# ✅ 验证 delegation 和主模型分离
hermes config show | grep -E "(default:|delegation)" -A2
# 预期：主模型仍为原模型，delegation 显示 glm-5-turbo

7. 异常处理与排错指南

🔴 错误 1："no API key found"

症状： 切换 provider 后发消息报错 RuntimeError: no API key found for provider <name>

原因： 每个 profile 有独立的 .env 文件，切换 provider 后目标 profile 中缺少对应 key。

修复步骤：

bash

# Step 1: 确认哪个 profile 缺 key
grep "API_KEY\|_KEY=" ~/.hermes/profiles/<name>/.env

# Step 2: 检查目标 key 是否存在
grep "ZHIPU_API_KEY" ~/.hermes/profiles/<name>/.env
# 如果没有输出 → 缺少该 key

# Step 3: 添加缺失的 key（以智谱国内版为例）
echo "ZHIPU_API_KEY=your_key_here" >> ~/.hermes/profiles/<name>/.env

# Step 4: 重启 Gateway
hermes -p <profile> gateway restart

预防： 切换 provider 前先检查目标 profile 的 .env：

bash

# 快速检查：目标 profile 是否有目标 provider 的 key
grep -l "ZHIPU_API_KEY" ~/.hermes/profiles/<name>/.env && echo "✅ 有智谱 key" || echo "❌ 缺智谱 key"

🔴 错误 2："context too small"

症状： compression 或 session_search 报错 context too small 或类似上下文不足的错误。

原因： compression 模型的 context_length 至少需要 16K，session_search 建议 32K+。

修复步骤：

bash

# Step 1: 确认当前 compression 模型
hermes config show | grep -A5 "compression:"

# Step 2: 换成上下文足够的模型
hermes config set auxiliary.compression.model mimo-v2.5
hermes config set auxiliary.compression.provider xiaomi

# Step 3: 重启
hermes gateway restart

🔴 错误 3：切换不生效（模型仍是旧的）

症状： 执行了 config set 但发消息仍用旧模型。

原因： Gateway 未重启，或重启失败。

排查步骤：

bash

# Step 1: 确认配置已写入
hermes -p <profile> config show | grep "default:"
# 如果显示的仍是旧模型 → config set 没成功，检查命令是否有报错

# Step 2: 确认 Gateway 状态
hermes -p <profile> gateway status
# 如果不是 running → Gateway 没启动，需要 start 而不是 restart

# Step 3: 强制重启
hermes -p <profile> gateway restart

# Step 4: 再次验证
hermes -p <profile> chat -q "你是什么模型？" -Q

🔴 错误 4：config set 报 YAML 格式错误

症状： hermes config set 返回 YAML parse error。

原因： config.yaml 中已有语法错误（缩进不对、特殊字符等）。

修复步骤：

bash

# Step 1: 找到有问题的 profile
cat ~/.hermes/profiles/<name>/config.yaml | python3 -c "import sys,yaml; yaml.safe_load(sys.stdin)" 2>&1
# 会报出具体行号

# Step 2: 检查该行附近内容
sed -n '<行号-2>,<行号+2>p' ~/.hermes/profiles/<name>/config.yaml

# Step 3: 手动修复 YAML 语法后重新 config set

预防： 批量操作前备份配置：

bash

cp ~/.hermes/profiles/<name>/config.yaml ~/.hermes/profiles/<name>/config.yaml.bak

🔴 错误 5：profile 名称不对

症状： hermes -p <name> config set ... 报错 profile not found。

原因： profile 名称区分大小写，或拼写错误。

排查：

bash

# 列出所有 profile
hermes profile list

# 预期输出示例：
# ◆ default
# ◆ cto
# ◆ diary
# ◆ genshin
# ◆ reasoner
# ◆ scout
# ◆ qian-duoduo

🟡 错误 6：辅助模型设为空后行为异常

症状： 辅助模型字段留空后，某些功能（如图片识别）不工作。

原因： Hermes 会尝试 auto 模式自动匹配，但可能失败或选到不合适的模型。

建议： 始终显式配置所有辅助模型，尤其是 vision 和 compression。

🔴 错误 8：脚本全景模式只输出表头就退出（set -euo pipefail + awk 陷阱）

症状： bash ~/.hermes/scripts/profile-model-overview.sh 只输出表头和分隔线就退出（exit code 2），没有任何 profile 数据。

原因： 脚本使用 set -euo pipefail。yaml_get() 函数中的 awk 在 YAML 中找不到匹配行时返回 exit code 2。在 set -e 下，var=$(awk ...) 非零退出会导致整个脚本立即终止。

修复： 在 yaml_get() 函数的 awk 调用末尾添加 || true：

bash

# 修复前（会因 awk exit 2 导致脚本退出）
main_model=$(awk '...' "$file" 2>/dev/null)

# 修复后（无匹配时返回空字符串）
main_model=$(awk '...' "$file" 2>/dev/null || true)

通用教训： 在 set -euo pipefail 脚本中，所有解析类命令（awk/grep/sed 从文件提取值）的 command substitution 必须加 || true，因为"没找到"是正常语义，不是错误。只有操作类命令（写文件、执行配置变更）的失败才应该触发 set -e 退出。

🔴 错误 9：awk 变量名 `sub` 与 gawk 内置函数冲突（3 层 YAML 解析失败）

症状： 详情模式中辅助模型全部显示 (auto)，即使 config.yaml 中已显式配置了 provider 和 model。

原因： yaml_get() 的 3 层嵌套版本使用 sub 作为 awk 变量名传入 -v sub="^ vision:"。sub 是 gawk 的内置函数名（用于字符串替换），gawk 拒绝将其作为变量名，报 fatal: cannot use gawk builtin 'sub' as variable name。由于这个错误被 2>/dev/null || true 吞掉了，脚本不会崩溃，但所有 3 层解析（auxiliary.vision.model 等）静默返回空。

修复： 将变量名从 sub 改为 subsec：

bash

# 修复前（gawk 报错，静默返回空）
awk -v sub="^  vision:" '... $0 ~ sub ...'

# 修复后（正常匹配）
awk -v subsec="^  vision:" '... $0 ~ subsec ...'

通用教训： awk 中不要使用以下变量名，它们是 gawk 内置函数：sub, gsub, match, split, sprintf, substr, tolower, toupper, close, system, fflush, delete, typeof, isarray。安全做法是加后缀或前缀，如 subsec、sub_pattern。

🟡 错误 7：base_url 未设置导致请求发错地址

症状： 切换 provider 后请求发到了错误的 API 端点，返回 401 或连接超时。

原因： 自定义 provider 必须显式指定 base_url。

修复：

bash

hermes -p <profile> config set model.base_url https://open.bigmodel.cn/api/coding/paas/v4
hermes -p <profile> gateway restart

8. 常见问题 (FAQ)

Q1: 切换模型后为什么没生效？

A: 模型配置只对新 session 生效，已运行的 Gateway 必须重启：

bash

hermes -p <profile> gateway restart

验证方法：hermes -p <profile> gateway status 确认状态为 running。

Q2: 切换 provider 后报 "no API key found"？

A: 每个 profile 有独立的 .env 文件，需要确保目标 profile 的 .env 中有对应 key：

bash

# 检查 key 是否存在
grep "ZHIPU\|XIAOMI\|DEEPSEEK" ~/.hermes/profiles/<name>/.env

# 如果没有，手动添加
echo "ZHIPU_API_KEY=your_key_here" >> ~/.hermes/profiles/<name>/.env

Q3: 辅助模型设为空会怎样？

A: Hermes 会尝试 auto 模式自动匹配，但可能失败或选到不合适的模型。建议显式配置所有辅助模型，特别是 vision 和 compression。

Q4: `hermes config set` 会覆盖其他字段吗？

A: 不会。config set 是逐字段 YAML merge，只修改指定的字段，不影响其他配置。

Q5: compression 模型报错 "context too small"？

A: compression 模型的 context_length 至少需要 16K，否则压缩会失败。选择模型时注意其上下文窗口大小。

Q6: default profile 的 `-p` 参数写法？

A: default profile 不加 -p 参数，其他 profile 必须加 -p <name>。这是最常见的错误。

Q7: 如何确认切换后的模型实际生效了？

bash

# 方法 1：查看配置
hermes -p <profile> config show | grep "default:" -A1

# 方法 2：发送测试消息
hermes -p <profile> chat -q "你是什么模型？回答模型名称即可" -Q

# 方法 3：查看 Gateway 状态
hermes -p <profile> gateway status

Q8: 批量切换后发现切错了，怎么回滚？

A: 如果操作前备份了配置：

bash

# 恢复备份
cp ~/.hermes/profiles/<name>/config.yaml.bak ~/.hermes/profiles/<name>/config.yaml
hermes -p <profile> gateway restart

预防： 批量操作前务必执行备份命令（见 §3.4）。

Q9: 自定义 provider 和内置 provider 的区别？

内置 provider（xiaomi/zhipu/openrouter 等）：base_url 和 api_key 的 env 变量名由 Hermes 自动识别，只需设置 provider 名即可
自定义 provider：在 custom_providers 中定义，切换时必须同时设置 base_url

Q10: Gateway restart 和 start 的区别？

restart：停止后重新启动，适用于已运行的 profile
start：首次启动或停止后的启动
如果 restart 报错说没有运行中的进程，改用 start

9. 反模式与边界条件

❌ 反模式 1：只改 model 不改 provider

bash

# ❌ 错误：模型名和 provider 不匹配
hermes config set model.default glm-5.1
# 但 provider 仍是 xiaomi → 请求会发到小米的 API 找 glm-5.1 → 报错

# ✅ 正确：同时切换
hermes config set model.default glm-5.1
hermes config set model.provider zhipu

❌ 反模式 2：切了 provider 不重启

bash

# ❌ 错误：改了配置就以为生效了
hermes config set model.provider zhipu
# ...直接发消息 → 仍用旧 provider

# ✅ 正确：改完必须重启
hermes config set model.provider zhipu
hermes gateway restart

❌ 反模式 3：切换 provider 不检查 API Key

bash

# ❌ 错误：直接切 provider
hermes -p diary config set model.provider zhipu

# ✅ 正确：先检查 key 存在
grep "ZHIPU_API_KEY" ~/.hermes/profiles/diary/.env && \
  hermes -p diary config set model.provider zhipu || \
  echo "❌ 先添加 ZHIPU_API_KEY 到 .env"

❌ 反模式 4：default profile 加了 -p 参数

bash

# ❌ 错误
hermes -p default config set model.default glm-5.1
# 可能报错或行为不可预期

# ✅ 正确
hermes config set model.default glm-5.1

❌ 反模式 5：用 `sed ... | bash` 测试脚本

bash

# ❌ 错误：管道执行时 $0 变成 'bash'，dirname "$0" 返回 /usr/bin
sed '14a\echo DEBUG' ~/.hermes/scripts/profile-model-overview.sh | bash

# ✅ 正确：直接执行
bash ~/.hermes/scripts/profile-model-overview.sh
# 或加 debug 用 bash -x
bash -x ~/.hermes/scripts/profile-model-overview.sh 2>&1 | head -50

原因： 管道传入 bash 时，$0 是 bash 而非脚本路径。脚本中 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" 会解析到 /usr/bin，导致 PRESETS_FILE 路径错误。

⚠️ 边界条件 1：批量操作中某个 profile 失败

for 循环批量切换时，如果某个 profile 的 config.yaml 格式有误，该 profile 会失败但不影响其他。批量操作后必须检查所有 profile 的结果：

bash

bash ~/.hermes/scripts/profile-model-overview.sh
# 逐行检查 Model 列是否全部正确

⚠️ 边界条件 2：compression 模型上下文不足

compression 和 session_search 对上下文大小有要求：

compression：至少 16K
session_search：建议 32K+
如果模型上下文太小，这些功能会静默失败或报错

⚠️ 边界条件 3：delegation 设为空字符串 vs 删除字段

bash

# 设为空字符串 → 回到继承主模型的行为
hermes config set delegation.model ""

# 直接编辑 config.yaml 删除 delegation 整块 → 可能导致解析问题
# ❌ 不推荐直接编辑，用 config set

⚠️ 边界条件 4：.env 中有同名 key 时取最后一个

如果 .env 中有多行同一个 key（如两行 ZHIPU_API_KEY=xxx），Hermes 取最后一个。这可能是预期行为，也可能造成困惑。

10. 限制与注意事项

API Key 隔离：每个 profile 有独立 .env，切换 provider 前务必确认目标 key 存在
Gateway 重启必须：所有模型修改只对新 session 生效，已运行的 gateway 必须 restart
辅助模型 context_length：compression 至少需要 16K，session_search 建议 32K+
批量操作不可逆：批量切换前建议备份配置：cp ~/.hermes/profiles/<name>/config.yaml ~/.hermes/profiles/<name>/config.yaml.bak
自定义 Provider 需要 base_url：使用自定义 provider 时必须在 config set 中指定 base_url
profile 名称区分大小写：Profile ≠ profile，使用 hermes profile list 确认准确名称
default profile 不加 -p：对 default profile 操作时不加 -p 参数，这是最常见的错误

11. Profile Model Manager 脚本

脚本支持三种模式：

脚本部署

脚本源文件在 skill 目录中：~/.hermes/profiles/<profile>/skills/profile-model-manager/scripts/。使用前需部署到 ~/.hermes/scripts/：

bash

# 首次部署或更新脚本
SKILL_DIR="$HOME/.hermes/profiles/cto/skills/profile-model-manager/scripts"
cp "$SKILL_DIR/profile-model-overview.sh" ~/.hermes/scripts/
cp "$SKILL_DIR/provider-presets.json" ~/.hermes/scripts/
chmod +x ~/.hermes/scripts/profile-model-overview.sh

⚠️ 脚本版本同步： ~/.hermes/scripts/ 里的脚本是独立副本，不会随 skill 更新自动同步。每次更新 skill 后需要重新部署。检查版本是否同步：

bash

# 比较文件大小即可快速判断
wc -c ~/.hermes/scripts/profile-model-overview.sh \
      ~/.hermes/profiles/cto/skills/profile-model-manager/scripts/profile-model-overview.sh

11.1 全景模式（无参数）

bash

bash ~/.hermes/scripts/profile-model-overview.sh

显示所有 profile 的模型配置表格（主模型、Provider、Vision、Compression、WebExtract、Delegation）。

11.2 详情模式（单个 profile）

bash

bash ~/.hermes/scripts/profile-model-overview.sh <profile>

显示指定 profile 的完整模型配置，包括主模型、所有辅助模型、delegation 的每个字段（provider / model / timeout / context_length 等）。

11.3 智能切换模式（一键配全）

bash

# 预览模式：只显示变更对比，不修改任何配置
bash ~/.hermes/scripts/profile-model-overview.sh <profile> <provider>

# 执行模式：应用所有配置 + 重启 Gateway
bash ~/.hermes/scripts/profile-model-overview.sh <profile> --apply <provider>

脚本会根据 provider 预设，自动为所有角色分配合适的模型：

角色	说明
主模型	对话用，选该 provider 最强的通用模型
vision	图片识别，选多模态模型（无原生多模态则用主模型）
compression	上下文压缩，选轻量高速模型
web_extract	网页内容提取，选轻量高速模型
session_search	历史会话搜索，选轻量高速模型
delegation	子 agent，选性价比高的模型

预览输出示例：

text

╔══════════════════════════════════════════════════════════╗
║  Profile: reasoner              Provider: zhipu           ║
╚══════════════════════════════════════════════════════════╝

  角色             当前值                    → 新值                     变更
  ──────────────────────────────────────────────────────────────────────────
  主模型           mimo-v2.5-pro             → glm-5-turbo              ✅
  provider         xiaomi                    → zhipu                      ✅
  vision           mimo-v2-omni              → glm-5-turbo              ✅
  compression      mimo-v2.5                 → glm-5-turbo              ✅
  web_extract      mimo-v2.5                 → glm-5-turbo              ✅
  session_search   mimo-v2.5                 → glm-5-turbo              ✅
  delegation       mimo-v2.5                 → glm-5-turbo              ✅

📋 以上为预览，未做任何修改。
💡 确认执行：bash $0 reasoner --apply zhipu

发布到 SkillHub

参见 references/skillhub-and-github-publishing.md（含 SkillHub Web 发布 + GitHub 仓库管理流程）。

脚本调试记录

参见 references/script-debugging-log.md（profile-model-overview.sh 的 bug 发现与修复过程）。

Profile Model Manager

Install

Profile Model Manager

🤖 Agent 智能触发指引

0. 快速开始

1. 模型配置架构

1.1 主模型 model:

1.2 辅助模型 auxiliary:

1.3 Delegation 模型 delegation:

2. 查看模型配置

3. 切换模型

3.1 切换单个 profile 的主模型

3.2 切换辅助模型

3.3 切换 Delegation 模型

3.4 批量操作所有 profile

3.5 批量重启 Gateway

3.6 操作后验证（重要！）

4. Provider 速查表

5. 模型参考

智谱（国内 zhipu / 国际 zai）

小米 MiMo

6. 典型工作流

场景 1：临时切换测试模型

场景 2：所有 profile 统一切换

场景 3：只改辅助模型

场景 4：Delegation 用便宜模型省钱

7. 异常处理与排错指南

🔴 错误 1："no API key found"

🔴 错误 2："context too small"

🔴 错误 3：切换不生效（模型仍是旧的）

🔴 错误 4：config set 报 YAML 格式错误

🔴 错误 5：profile 名称不对

🟡 错误 6：辅助模型设为空后行为异常

🔴 错误 8：脚本全景模式只输出表头就退出（set -euo pipefail + awk 陷阱）

🔴 错误 9：awk 变量名 sub 与 gawk 内置函数冲突（3 层 YAML 解析失败）

🟡 错误 7：base_url 未设置导致请求发错地址

8. 常见问题 (FAQ)

Q1: 切换模型后为什么没生效？

Q2: 切换 provider 后报 "no API key found"？

Q3: 辅助模型设为空会怎样？

Q4: hermes config set 会覆盖其他字段吗？

Q5: compression 模型报错 "context too small"？

Q6: default profile 的 -p 参数写法？

Q7: 如何确认切换后的模型实际生效了？

Q8: 批量切换后发现切错了，怎么回滚？

Q9: 自定义 provider 和内置 provider 的区别？

Q10: Gateway restart 和 start 的区别？

9. 反模式与边界条件

❌ 反模式 1：只改 model 不改 provider

❌ 反模式 2：切了 provider 不重启

❌ 反模式 3：切换 provider 不检查 API Key

❌ 反模式 4：default profile 加了 -p 参数

❌ 反模式 5：用 sed ... | bash 测试脚本

⚠️ 边界条件 1：批量操作中某个 profile 失败

⚠️ 边界条件 2：compression 模型上下文不足

⚠️ 边界条件 3：delegation 设为空字符串 vs 删除字段

⚠️ 边界条件 4：.env 中有同名 key 时取最后一个

10. 限制与注意事项

11. Profile Model Manager 脚本

脚本部署

11.1 全景模式（无参数）

11.2 详情模式（单个 profile）

11.3 智能切换模式（一键配全）

发布到 SkillHub

脚本调试记录

Related skills

1.1 主模型 `model:`

1.2 辅助模型 `auxiliary:`

1.3 Delegation 模型 `delegation:`

智谱（国内 `zhipu` / 国际 `zai`）

🔴 错误 9：awk 变量名 `sub` 与 gawk 内置函数冲突（3 层 YAML 解析失败）

Q4: `hermes config set` 会覆盖其他字段吗？

Q6: default profile 的 `-p` 参数写法？

❌ 反模式 5：用 `sed ... | bash` 测试脚本