xiaoxue_admin
/
xiaowei-system
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
xiaowei-system/skills/devops/llm-gateway-ops/SKILL.md

28 KiB
Raw Blame History

name version date description
llm-gateway-ops 1.0.1 2026-09-10 LLM 网关运维 — OmniRoute/NewAPI 类 AI 网关的评估、部署、API 调用、观测体系、cron 切换。含网关选型方法论、npm 安装坑、urllib 不兼容、SSE 读取模式、systemd 常驻、看门狗接入。

LLM 网关运维（OmniRoute / NewAPI 类）

触发场景

  • 用户分享新 AI 网关/路由项目（如 OmniRoute、OneAPI 类）→ 评估是否替代现有 NewAPI
  • 用户问"X 网关是否有必要保留/关停"→ 拉真实调用量做决策（不只是看进程在不在）→ 决策后看 references/gateway-shutdown-procedure-20260902.md 走 6 步标准流程
  • 部署/试跑网关、做 systemd 常驻、接入看门狗
  • 写脚本调网关 API（chat/completions）遇超时/挂起
  • 把 cron 任务从 NewAPI 切换到其他网关 provider
  • 需要持续观测网关稳定性、为"是否全面切换"提供数据
  • 周期性自检网关使用率（cron 0 9 1 * *）

核心方法论：评估是否替代现有网关

  1. 不急着替代：新网关（尤其 young 项目 <6 个月）不碰生产链路
  2. 并行第二网关：新网关跑不同端口（如 :3001），现有网关不动
  3. 生产链路绝不动：付费主模型（如 deepseek-v4-flash 走官方 API）不切
  4. 观测 2-4 周再决定是否迁移——必须有量化数据支撑，不拍脑袋
  5. 评估维度：稳定性/免费模型供给/路由能力/成本控制/国内网络兼容/生态成熟度
  6. logs 表 0 调用 ≠ 服务僵尸（2026-09-02 教训）：logs 是写日志表，不代表服务可用。判断"僵尸"必跑 3 步——L1 进程活 + L2 直连 200 + L3 provider_models_cache.json 列了模型。三步全过才认活（详细见 references/gateway-real-usage-evaluation-20260901.md 的"修正版"章节）
  7. 进程内存要算子进程总和（2026-09-02 教训）：OmniRoute 主进程 46MB + 子进程 394MB = 441MB 总占用，只看主进程会少算 90%
  8. HTTP 410/404 ≠ key 失效（2026-09-02 教训）：NVIDIA 端下架特定模型（410 "has retired"）≠ API key 废了——同一个 key 通常能跑多个模型，重测 minimaxai/minimax-m3 或 google/gemma-4-31b-it 等常用模型验证。9 个 NIM key 8 个模型下架 的判断是错的——9/9 全部活跃，只是测错了模型。
  9. 不要相信 abilities 表的可用性，必须真实 HTTP 调用（2026-09-02 实测）：abilities 表里有 1242 条记录，但实际跑 24 个配置模型只有 3 个 200（minimax-m3 / gemma-4-31b / gpt-oss-120b）+ 2 个 sensenova-free 通道（deepseek-v4-flash / glm-5.2）。15 个模型返回 410 Gone（NVIDIA 端下架），7 个返回 404（NVIDIA 端没部署）。任何"model 在 NewAPI 列表" 的判断都必须实测 curl 验证 200，否则批量配置会全挂。
  10. 评估完成后如何安全关停（2026-09-02 OmniRoute 实战）：6 步标准流程——①备份 4 件套（脚本/服务/配置/状态）②先写替代观测脚本（不能只关停就跑，否则 cron 一直报错）③改 cron 任务（no_agent script 字段必须相对路径）④systemctl stop + disable ⑤验证替代品 + 内存释放 ⑥归档不删原可执行文件。详见 references/gateway-shutdown-procedure-20260902.md。patch 工具拒绝改 config.yaml——provider 段留着不动通常没事（端口已死不会触发）。

OmniRoute 部署（npm 全局）

# 国内必须用镜像源（官方 Cloudflare 源卡死）
npm install -g omniroute --registry=https://registry.npmmirror.com --no-audit --no-fund
# 大包 3GB + postinstall 编译原生模块（better-sqlite3/@swc/core/onnxruntime），需 10+ 分钟
# ⚠️ 中途 kill 会导致 package.json 损坏 → 必须等完整跑完

PATH 坑：node bin 目录不在默认 PATH（如 /home/muc/nodejs/node-v24.16.0-linux-x64/bin）， 运行时 export PATH=/path/to/node/bin:$PATH 或 systemd 里写 Environment=PATH。

systemd 常驻（~/.config/systemd/user/omniroute.service）：

[Unit]
Description=...
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
Environment=PATH=/home/muc/nodejs/node-v24.16.0-linux-x64/bin:/usr/local/bin:/usr/bin:/bin
Environment=HOME=/home/muc
ExecStart=/home/muc/nodejs/node-v24.16.0-linux-x64/bin/omniroute serve --port 3001 --no-open
Restart=on-failure
RestartSec=10
CPUQuota=50%
MemoryMax=1.5G
[Install]
WantedBy=default.target

systemctl --user daemon-reload && systemctl --user enable --now omniroute.service

看门狗接入（health-watchdog.sh）：

  • 在 PROC_ALIVE=()/PROC_DEAD=() 初始化之后加 systemd 状态检测（bash 数组必须先初始化）
  • 自愈 case 映射加 omniroute) svc="omniroute.service" ;;
  • ⚠️ 避免 pkill -f "omniroute serve"——会匹配到包含该字符串的 shell 自身（自伤），用精确 PID 或 pgrep -f "bin/omniroute serve" 先查

API 调用三大坑（2026-08-01 实测）

坑 现象 解决
Python urllib 不兼容 urllib 连响应头都收不到（30s 超时），curl 却 2ms 必须用 requests 库
显式 stream:false 挂起 请求挂死 用默认流式（SSE），不传 stream 或传 true
SSE 连接不关闭 r.read() 等 EOF 挂到超时 iter_lines() 逐行读，遇 [DONE] break

正确调用模式（requests + SSE）：

r = requests.post(f"{API}/chat/completions",
                  json={"model": model, "messages": [{"role": "user", "content": "ping"}]},
                  headers={"Authorization": f"Bearer {KEY}"},
                  timeout=45, stream=True)
routed = "unknown"
for line in r.iter_lines():
    s = line.decode("utf-8", "ignore") if isinstance(line, bytes) else (line or "")
    s = s.strip()
    if s.startswith("data:") and "[DONE]" in s:
        break
    if s.startswith("data:"):
        # json.loads(s[5:].strip()) → 取 model 字段

观测体系（为评估提供数据）

采集脚本（每 6h，no_agent cron）：

  • 测服务健康（systemd + /models API）+ 多组合真实请求（auto/chat、auto/best-free 等）
  • 记录：延迟/路由模型/成本（x-omniroute-response-cost）/provider（x-omniroute-provider）/cron 运行状态
  • 正常 → 静默写 JSONL；异常 → 输出报警（no_agent 非空 stdout 自动推送）
  • 连续 3 次异常 → 提示回滚

周度评估（每周日，no_agent cron）：

  • 汇总 7 天：成功率/平均延迟/P95/累计成本/路由分布/cron 运行
  • 给明确结论：✅ 稳定继续扩大切换 OR ❌ 回滚

关键配置：~/.hermes/omniroute-observe/observations.jsonl + state.json

脚本位置（2026-08-01 已部署）：

  • ~/.hermes/scripts/omniroute-observe.py — 采集脚本（cron 02d005860762，每 6h，no_agent）
  • ~/.hermes/scripts/omniroute-weekly-report.py — 周度评估（cron dc85f9a3bfc3，每周日 18:00，no_agent，始终输出报告）
  • 异常判定：连续 3 次失败（state.json 的 consecutive_failures）→ 提示人工检查或回滚 cron 到 newapi-local

cron 切换 provider

  1. config.yaml providers 段加自定义 provider（base_url 指向网关 /v1）：
providers:
  omniroute-local:
    api_key: local-test-key
    base_url: http://127.0.0.1:3001/v1
    cost_factor: 0.0
    default_model: auto/chat
    models:
    - auto/chat
    - auto/best-free
    rate_limit: 1000
    timeout: 30
  1. cronjob action=update job_id=XXX model={"model": "auto/chat", "provider": "omniroute-local"}
  2. cronjob action=run job_id=XXX 手动触发验证 execution_success: true
  3. 先切 1-2 个低风险任务，验证稳定再铺开

⚠️ 网关 auto/chat 路由的 cron 会 504（2026-08-02 实测）

最近观察（2026-08-04）

  • 今日 Cron (ID b46f060eb16b_20260804_220054) 记录 OmniRoute 在 auto/chat、auto/best-free、auto/coding、auto/best-reasoning 四个路由上出现 HTTPConnectionPool 超时（≈45 s）导致任务失败。
  • 复盘确认根因：这些 auto/* 路由会随机挑选慢模型（如 big-pickle），在无交互式超时容忍的 cron 环境下触发 504 错误。
  • 采用的 立即修复：将受影响的 cron 任务模型从 auto/chat 钉死 到已验证的稳定模型（如 openai/gpt-oss-120b）或直接使用 NewAPI 本地 provider。
  • 新增 监控脚本 omniroute-cron-failure-watchdog.py（已放置于 ~/.hermes/scripts/），每 5 min 检查最近的 Cron 日志，若检测到相同超时模式，自动发送飞书报警并建议模型钉死。
  • 已更新 references/2026-08-04-omniroute-cron-failure.md 记录详案（见下）。

现象：每日复盘 cron（provider=omniroute-local, model=auto/chat）执行失败：RuntimeError: Stream produced no non-ping SSE event within 95000ms [oc/big-pickle (504)]——auto/chat 路由把请求派给了慢模型（big-pickle），SSE 95s 内无事件，cron 失败。

根因：auto/chat 是"路由通配"——网关替 cron 选模型，选中慢/不稳定的模型就超时。cron 无人值守，失败是静默的（除非看 last_status: error），比交互式调用更怕路由抖动。

修复：把 cron 的模型从 auto/chat 钉死到网关里的稳定模型：

cronjob action=update job_id=XXX model={"model": "openai/gpt-oss-120b", "provider": "newapi-local"}

（实测 newapi-local 的 gpt-oss-120b 稳定；如果仍想走网关，选网关里实测延迟低的具名模型，别用 auto/*）

教训：

  • cron 任务钉具名稳定模型，不用 auto/chat 路由通配——交互式可以容忍慢，cron 不能
  • 修完 cron 后验证：cronjob action=run job_id=XXX → execution_success: true，或等下一个调度周期看 last_status
  • 排查 cron 失败第一动作：cronjob action=list 找 last_status: error，再读 ~/.hermes/cron/output/{job_id}/{date}*.md 的 Error 段——504 类 SSE 超时一眼可见

⚠️ 免费模型池会整体过期，skill 白名单记录会 stale（2026-08-02 实测）

模型池会整体大换血：2026-07-27 当天 m2.7/step-flash/qwen3.5 全部 EOL，m3 空响应，gpt-oss 是 reasoning 模型。skill/文档里的"可用模型"记录会过期——任何模型判断都必须实测，不能信旧白名单。

蒸馏任务 vs 对话任务的判定标准不同：

  • 对话任务：choices[0].message.content 非空即可
  • 蒸馏任务：content 必须是非空且可解析的 JSON（剥离 ```json code fence 后）——"能对话 ≠ 能蒸馏"
  • reasoning 模型（gpt-oss 系）排除：content=null，答案全在 reasoning/reasoning_content 字段——除非调用方显式读取该字段，否则 distill 永远 parse 失败降级 keyword

模型验证命令（候选模型上线前必跑）：

KEY=$(grep -oP 'LLM_API_KEY=\K.*' ~/.config/systemd/user/zhiyid.service)
curl -s -m 30 http://127.0.0.1:3000/v1/chat/completions -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KEY" -d '{"model":"<候选>","messages":[{"role":"system","content":"输出严格JSON"},{"role":"user","content":"提取实体：牧尘喜欢简洁。输出 {\"entities\":[],\"decisions\":[],\"conclusions\":[]} 格式"}],"max_tokens":150}'
# 期望: content 是纯 JSON（或可剥离的 code fence），且非空
# 失败特征: content=null（reasoning 模型）/ 400 EOL / No available channel / system_cpu_overloaded / 空响应

蒸馏模型双层看门狗（2026-08-02 上线，解决"免费模型挂了没人换"）

免费模型经常挂，单层 6h 巡检太慢 + 探针类型不对（测对话不测 JSON）。方案：双层：

  1. 30min 轻量探针（no-agent cron）：只测当前蒸馏模型的 JSON 输出能力（剥离 code fence 后可解析才算通过）→ 挂了立即按候选池切换 + 更新配置 + 重启 + 飞书报警
    • 参考实现：~/.hermes/scripts/distill-model-watchdog.py（cron 89de35dc35a7）
  2. 6h 深度巡检（model-health.py 的 _heal_distill_models）：同步守护蒸馏配置，识别 reasoning 模型

候选池设计：按优先级排序的可用模型列表（实测 JSON 可用），挂了顺序测下一个。当前蒸馏候选池（2026-08-17 更新：Agnes 优先，NewAPI 兜底）：agnes-2.0-flash > agnes-2.5-flash > google/gemma-4-31b-it > mistralai/mistral-nemotron > nvidia/llama-3.3-nemotron-super-49b-v1.5 > meta/llama-3.1-8b-instruct > nvidia/nemotron-mini-4b-instruct

⚠️ 切换模型时端点/key 必须联动（2026-08-17）：蒸馏模型从 NewAPI 切到 Agnes（或反切）时，zhiyid.service 的 LLM_ENDPOINT/LLM_API_BASE/LLM_API_KEY 必须跟着 model 一起改——只改 LLM_MODEL 会让 agnes 模型走 NewAPI 端点（401/模型不存在）。_update_zhiyid 已改为按模型前缀路由：agnes- → Agnes 端点/key，其他 → NewAPI 端点/key。同理 tdai-gateway.yaml 只改 llm: 段 model，memory.embedding.model 永远保持 bge-m3（全局正则替换会把 embedding 也改掉）。

⚠️ 自愈机制必须实测"失败路径"（牧尘"都测试过了吧？"教训）：

  • 手动 cronjob run <id> 触发一次确认 execution_success: true
  • 模拟失败场景（把配置改成已知坏模型）→ 跑机制 → 确认切换+配置更新+服务重启+通知全链路
  • dry-run 单测判断逻辑（好模型判健康、坏模型判需替换、原文件未动）
  • 陷阱：模型不在测试列表 ≠ 模型挂了。探针主判（content 非空+JSON 可解析），巡检结果仅作辅助覆盖（明确 dead 才覆盖探针）——否则会把健康模型误替换（gemma 不在 ALL_MODELS → found=None → 误判需替换，2026-08-02 抓到并修复）
  • 陷阱：探针硬编码端点会自我破坏（2026-08-17）：_heal_distill_models 当前模型探针若硬编码走 NewAPI 端点，当 zhiyid 已切 agnes 时会误判"挂了"并自动切回 NewAPI——当前模型探针和替补复核都必须用 _get_endpoint(model) 按模型名路由端点
  • 陷阱：推理模型 JSON 截断误判（2026-08-17）：Agnes 2.0-flash 是推理模型（reasoning_tokens 占大头，150 里 114 是推理），max_tokens: 150 时正文被截断（finish_reason=length）→ 看门狗误判"挂了"触发无谓切换。蒸馏 JSON 探针 max_tokens 必须 ≥500

⚠️ auxiliary.compression 压缩模型配置（2026-08-09 实测）

症状：上下文压缩报 Context compression timed out after 30.0s with no output from the summary model，或 gateway 日志 Session hygiene compression ... made no progress for 30.0s; continuing without compression。

根因：config.yaml 的 auxiliary.compression 段是 provider: auto + model: ''——Hermes 找不到可用的总结模型。vision 段配了 newapi-local 所以正常，compression 段漏配就 30s 超时。

修复（主配置 + 每个 profile 的分身配置都要改，~/.hermes/config.yaml 和 ~/.hermes/profiles/prof-b/config.yaml）：

auxiliary:
  compression:
    provider: newapi-local
    model: nvidia/nemotron-3-super-120b-a12b
    base_url: http://127.0.0.1:3000/v1
    api_key: <newapi-local 裸 token>
    timeout: 120

⚠️ reasoning 模型不能做压缩总结：实测候选模型（newapi-local）：

  • ✅ nvidia/nemotron-3-super-120b-a12b：2.2s 正常总结（选定）
  • ✅ meta/llama-3.1-8b-instruct：0.3s（备用）
  • ❌ openai/gpt-oss-120b、nvidia/nvidia-nemotron-nano-9b-v2：content=null（答案在 reasoning 字段），choices[0].message.content 取值直接 'NoneType' object is not subscriptable——与蒸馏任务同样的坑（见上「蒸馏 vs 对话判定」）

候选验证脚本：/tmp/test_compression_models.py 模式（urllib 直连 newapi-local 测 summary prompt，看 content 非空 + 延迟）。改完重启 gateway 生效。

重启 gateway 使配置生效：gateway 内部不能 systemctl restart 自己，用 systemd-run 独立执行（见 hermes-debug 重启节）：

systemd-run --user --unit=gw-compression-restart --collect bash /tmp/restart_gw_compression.sh

MCP server 接入 Hermes（2026-08-10 实测）

验证 MCP server 可独立运行（连接前必做）

ConnectionClosed("initialize request") 是正常行为，不是错误——stdio MCP server 启动后等待客户端发 initialize 请求，无客户端就退出。用 --version 测 MCP server 会看到这个"错误"，别被骗。

真正验证（MCP SDK 握手 + 列工具）——用固化脚本 scripts/verify_mcp_stdio.py（本 skill 自带，可复用）：

python3 ~/.hermes/skills/devops/llm-gateway-ops/scripts/verify_mcp_stdio.py "npx" "-y" "@dbx-app/mcp-server"
# 输出: ✅ MCP 连接成功，发现 N 个工具: dbx_list_connections, ...

config.yaml 是安全保护文件（patch 工具拒绝写）

Hermes 的 patch/write_file 工具拒绝写 ~/.hermes/config.yaml（报 Refusing to write to Hermes config file / Agent cannot modify security-sensitive configuration）。改 config.yaml 必须用：

# 方案 A（推荐）：hermes config CLI
hermes config set providers.newapi-local.api_key <token>
# 方案 B：python yaml 脚本（注意会丢注释 + 重排格式，先备份）
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak
python3 -c "
import yaml, os
cfg = yaml.safe_load(open(os.path.expanduser('~/.hermes/config.yaml')))
cfg.setdefault('mcp_servers', {})['dbx'] = {'command': 'npx', 'args': ['-y', '@dbx-app/mcp-server'], 'enabled': True, 'timeout': 120, 'connect_timeout': 60}
yaml.safe_dump(cfg, open(os.path.expanduser('~/.hermes/config.yaml'), 'w'), allow_unicode=True, sort_keys=False, default_flow_style=False)
"
# 验证：hermes config check

MCP server 接入后必须重启 gateway 才生效

MCP tools 在 gateway 启动时 discovery，改 mcp_servers 后必须重启 gateway。gateway 内部不能 systemctl restart 自己（被安全块拦截），用 systemd-run 独立执行：

# /tmp/restart_gw.sh：sleep 2 && systemctl --user restart hermes-gateway
systemd-run --user --unit=gw-restart /tmp/restart_gw.sh

⚠️ gateway 优雅关闭可能很慢（TimeoutStopUSec=3min 30s，MCP 子进程拖住 SIGTERM 处理），deactivating 状态持续 2-3 分钟是正常的，到点 systemd 强制 kill 后自动重启。重启期间当前会话会短暂中断，属预期。

验证接入成功

新会话里 tool_search 能看到 mcp__<server>__* 工具 = 加载成功（如 mcp__dbx__dbx_list_connections）。

Agnes 备用 provider 接入（2026-08-17 实测：NewAPI 不稳时的稳定第三腿）

场景：NewAPI 免费模型不稳（gpt-oss-120b 3 次 1 次空响应 NoneType），cron/distill 需要稳定替代。Agnes（免费、中文正常、JSON 可用、3/3 稳定）是比 NewAPI 更稳的选择。完整三处迁移流程：

1. config.yaml 加 provider（patch 被安全墙挡，用 python）

# 备份后插入（在 fallback_providers 前）：
agnes_block = """  agnes:
    key_env: AGNES_API_KEY
    base_url: https://apihub.agnes-ai.com/v1
    cost_factor: 0.0
    default_model: agnes-2.5-flash
    models:
      - agnes-2.5-flash
      - agnes-2.5-flash
    rate_limit: 1000
    timeout: 60
"""
content = open('config.yaml').read()
idx = content.find("fallback_providers:")
content = content[:idx] + agnes_block + content[idx:]
open('config.yaml','w').write(content)
# 验证：hermes config get providers | grep agnes

⚠️ key 用 key_env: AGNES_API_KEY（从 .env 读），不写明文 token。

2. cron 批量切换（cron/jobs.json 直接 python 改）

cron 存于 ~/.hermes/cron/jobs.json（不是逐个 cronjob update）。批量替换 provider/model：

import json
d = json.load(open('~/.hermes/cron/jobs.json'))  # 先 cp 备份
jobs = d if isinstance(d, list) else d.get('jobs', [])
for j in jobs:
    if 'newapi' in (j.get('provider') or '') or 'gpt-oss' in (j.get('model') or ''):
        j['provider'] = 'agnes'; j['model'] = 'agnes-2.5-flash'
json.dump(d, open('~/.hermes/cron/jobs.json','w'), ensure_ascii=False, indent=2)

改完 cronjob list 确认生效（model/provider 字段变化），再 cronjob run <id> 实测一个任务（投研简报实测通过）。

3. zhiyid distill 切换（三个 LLM_ env 必须一起改）

Environment=LLM_ENDPOINT=https://apihub.agnes-ai.com/v1/chat/completions
Environment=LLM_MODEL=agnes-2.5-flash
Environment=LLM_API_KEY=<AGNES 完整 key>

⚠️ 只改 MODEL 会 401（endpoint 还指着 NewAPI）。改后 systemctl --user daemon-reload && systemctl --user restart zhiyid，验证 /api/v1/health + cat /proc/$(pgrep -f zhiyid-new)/environ | tr '\0' '\n' | grep LLM_。

4. model-health.py 多端点优先巡检（2026-08-17 牧尘指示）

  • 加 AGNES_API/AGNES_KEY（从 .env 读）+ AGNES_MODELS + CONTEXT_LENGTHS_AGNES
  • _get_endpoint(model)：agnes- 前缀走 Agnes，其余走 NewAPI——test_model/_run_quality_probe/_verify_model_usable 三处都用它（不要硬编码 API/HEADERS）
  • ALL_MODELS = AGNES_MODELS + _OTHER_MODELS（Agnes 前置优先测）
  • ⚠️ 过滤坑：if m not in AGNES_MODELS 写在整个 listcomp 上会把 Agnes 自己也过滤掉——正确是只对非 agnes 部分去重
  • 实测：agnes-2.0-flash 1203ms/2-2/探针100，与 nemotron/gpt-oss 并列满分

5. Agnes 文本输出坑

  • JSON 输出带 markdown 包裹（json ... ），裸 json.loads 失败 → 用 extract_json（正则剥 code fence + 截 {} 区间）
  • 中文输入正常（2026-08-17 实测 3/3）
  • 图像：agnes-image-2.0-flash 比 2.1 稳；大场景效果好，适合小红书素材
  • 详见 provider-tiering skill 的 Tier 0.75 章节（更完整的模型对比表）

何时绕过网关直接调用 API（2026-08-20 决策）

不是所有 provider 都该走 NewAPI 路由。 以下情况直接用 provider 原生 API key：

条件 示例 做法
provider 有免费额度且 API 稳定 Agnes（agnes-2.5-flash） 直接用 AGNES_API_KEY 调 apihub.agnes-ai.com
provider 的 API 格式与 OpenAI 不完全兼容 某些国内模型 直调避免兼容层损失
网关路由可能选错模型/超时 自动路由 cron 504 问题 钉死到 provider 原生端点
需要推理模型的 reasoning_content 字段 gpt-oss 系列 网关可能吞掉该字段

决策记录（牧尘 2026-08-20）：Agnes 不接入 NewAPI，直接用 key 调用。zhiyid 蒸馏 / cron 任务已通过 zhiyid.service 的 LLM_ENDPOINT / LLM_API_KEY 环境变量直连 Agnes。

⚠️ NewAPI base_url 铁律（2026-08-21 实测踩坑）

NewAPI 自动追加 /v1 到 channel base_url。配置渠道时：

场景 正确 base_url 错误 base_url
NewAPI channel https://token.sensenova.cn https://token.sensenova.cn/v1 → 404
Hermes config provider https://token.sensenova.cn/v1 —
curl 直调 https://token.sensenova.cn/v1/chat/completions —
OpenClaw provider https://token.sensenova.cn/v1 —

排查信号：channel error (channel #N, status code: 404): NOT_FOUND → 先查 base_url 是否多了 /v1。

多组件 Provider 迁移（2026-08-21 实战）

当需要把多个组件（prof-b / opencode / DSH / OpenClaw）统一迁移到新 provider 时：

迁移清单

组件 配置路径 base_url 格式 key 来源 重启方式
prof-b ~/.hermes/profiles/prof-b/config.yaml 带 /v1 .env 的 key_env cron one-shot systemctl --user restart hermes-gateway-prof-b.service（不能从 gateway 内部重启）
opencode ~/.config/opencode/opencode.json 带 /v1 provider.options.apiKey 明文 按需启动，改完自动生效
DSH ~/.dsh/settings.yaml 带 /v1 apiKey 明文 systemd-run --user --setenv=PATH=... dsh web（PATH 必须含 node）
OpenClaw ~/.openclaw/openclaw.json 带 /v1 apiKey 明文 systemd-run --user systemctl --user restart openclaw-gateway.service

铁律

  1. prof-b .env 必须加新 key：echo "KEY=value" >> ~/.hermes/profiles/prof-b/.env
  2. 主 .env 也要加：echo "KEY=value" >> ~/.hermes/.env
  3. 从 gateway 内部不能重启自己：用 systemd-run --user 或 cron one-shot
  4. DSH 用 systemd-run 时 PATH 必须含 node：--setenv=PATH="/home/muc/nodejs/.../bin:/usr/local/bin:/usr/bin:/bin"
  5. OpenClaw 服务名是 openclaw-gateway.service（不是 openclaw.service）
  6. 删旧 provider 前先测新 provider：curl 直调确认 200 → 再切配置 → 再重启
  7. 全部重启后逐个验证：每个组件独立测一次 API 调用
  8. prof-b 不能从 gateway 内部重启：创建 one-shot cron job（systemctl --user restart hermes-gateway-prof-b.service），30秒后自动执行
  9. OpenClaw 子 agent 不要漏：agents.list 里 main + a02 + a03 + a04 + a05 全部都要改，否则未改的子 agent 继续用旧模型
  10. Sensenova 模型是 reasoning 模型：deepseek-v4-flash 和 glm-5.2 响应里 content 可能为空，答案在 reasoning_content——蒸馏/压缩任务不能用

NewAPI 渠道管理（SQLite 直改 + Web UI）

找到 NewAPI 数据库路径

NEWAPI_PID=$(pgrep -f "new-api --port")
DB_PATH=$(readlink -f /proc/$NEWAPI_PID/cwd)/one-api.db
# 通常: /var/lib/new-api/one-api.db（不是 ~/.hermes/newapi.db）

⚠️ ~/.hermes/newapi.db 是旧路径/空文件。真实路径看进程 cwd。

SQLite 直改三大坑

NewAPI 添加渠道有两种方式：API（会 panic，版本 bug）和 Web UI（推荐）。直接改 SQLite 也可以但必须注意：

  • channel_info JSON 必须有全部 5 个子字段（is_multi_key/multi_key_size/multi_key_status_list/multi_key_polling_index/multi_key_mode）
  • settings JSON 必须完整（含 allow_service_tier 等 9 个字段，不能部分截断）
  • other 必须是 {} 而非 NULL

任何 JSON 不完整会导致 channel_upstream_update.go:551 报 unexpected end of JSON input，渠道加载静默失败——distributor 找不到该渠道。

⚠️ models 表（SQLite one-api.db）和 channels 表的 models 列是独立的。channels 有 models 不代表 /v1/models 能返回——API 读的是 models 表。需要 INSERT INTO models 才能让 API 返回。

⚠️ abilities 表必须显式 INSERT：路由读 abilities 表匹配 model→channel_id。光有 channel 不加 abilities = No available channel for model。删渠道时也要 DELETE FROM abilities WHERE channel_id=<id> 联动清理。

⚠️ SQLite reserved word group：group 是 SQL 保留字。INSERT/SELECT 中必须用双引号 "group" 包裹，否则 near "group": syntax error。同理 setting 列名虽然不报错但建议也加引号保安全。

⚠️ 列名是 created_time 不是 created_at：NewAPI schema 用 created_time（unix timestamp），写 created_at 会报 no column named。

完整参考：references/newapi-channel-management-20260820.md（含 SQLite reserved word 坑、abilities 表联动、Sensenova 免费 provider 接入模板）

参考

  • references/omniroute-notes.md — 本次部署/踩坑细节
  • references/agnes-switch-20260817.md — Agnes 全面替换 NewAPI 排查记录：切换清单 + 3 个联动 bug（自愈端点硬编码/embedding 误改/推理模型 JSON 截断）+ 全面排查方法论
  • references/newapi-channel-management-20260820.md — NewAPI 渠道管理坑：SQLite 直改完整性、API panic bug、Web UI 替代方案
  • references/newapi-sensenova-channel-20260821.md — Sensenova Token Plan 免费接入：5 模型 + abilities 联动 + reserved word 坑
  • references/openclaw-config-validation-pitfalls-20260821.md — OpenClaw openclaw.json 配置验证坑：defaultModel/defaultProvider 非法、output 字段不合法、models 数组必填
  • references/gateway-real-usage-evaluation-20260901.md — 评估方法论：3 步框架（L1 进程/L2 配置/L3 调用）+ 决策树 + 410 ≠ key 失效陷阱
  • references/gateway-shutdown-procedure-20260902.md — 关停标准流程：6 步（备份→写替代脚本→改 cron→systemctl stop+disable→验证→归档）+ 4 个 cron/patch 陷阱
  • references/gmi-m3-to-newapi-nim-pool-20260902.md — 2026-09-02 新增：GMI-M3 到期后改用 NewAPI 9 NIM key 池方案（含观测脚本、cron 更新、决策记录）
  • references/2026-08-04-omniroute-cron-failure.md — OmniRoute cron 504 失败案例（auto/chat 路由慢模型）