OpenClaw 自定义模型排查：为什么 alias 配了、网关重启了，模型选择器里还是没有？

本文记录一次真实的 OpenClaw 自定义 provider 排查过程。现象很迷惑：配置写进去了，别名也有了，网关也重启过好几次，但 webchat 的模型选择器里始终看不到新加的模型。最终定位到 OpenClaw 模型可见性的第三层控制——modelPolicy.allow 白名单。

现象：一切看起来都"配好了"

在 openclaw.json 里加了一个自定义 provider：

"providers": {
  "sapiens": {
    "baseUrl": "https://apihub.agnes-ai.com/v1",
    "api": "openai-completions",
    "apiKey": "<SECRET_9e6b62f3>",
    "models": [
      {
        "id": "agnes-3.0-flash",
        "name": "Agnes 3.0 Flash (Custom Provider)",
        "contextWindow": 524288,
        "contextTokens": 524288,
        "maxTokens": 65536,
        "input": ["text", "image"],
        "reasoning": true
      }
    ]
  }
}

还配了别名：

"agents": {
  "defaults": {
    "models": {
      "sapiens/agnes-3.0-flash": {
        "alias": "sapiens/agnes-3.0-flash"
      }
    }
  }
}

重启网关，跑 openclaw doctor 验证，配置 validate 全过。结果 webchat 的模型下拉框里，sapiens 下面只有 agnes-2.5-flash 和 agnes-2.5-pro-alpha，就是没有 agnes-3.0-flash。

换机器、重启电脑、重启网关，试了好几天，现象不变。

排查：分层定位，别急着怀疑配置没写进去

排查时第一反应容易是"配置没生效"。先用只读检查把分层看清楚：

第一层：provider 注册（providers.sapiens.models）

这一层定义的是模型元数据：API 端点（baseUrl）、鉴权方式（apiKey）、上下文窗口（contextWindow）、输出上限（maxTokens）、输入模态（input）。它决定的是"这个模型能不能被调用"。

查配置发现这一层是完整的，sapiens/agnes-3.0-flash 的元数据都在，validate 也过了。所以问题不在"有没有注册"。

第二层：模型别名（agents.defaults.models）

这一层给模型起短名，方便在会话里用 /model 或直接引用。它决定的是"这个模型叫什么"。

查配置发现别名也配了，sapiens/agnes-3.0-flash 的 alias 就在。

到这里，前两层都正常，但选择器里就是没有这个模型。说明还有第三层在控制可见性。

第三层：模型白名单（agents.defaults.modelPolicy.allow）

这是最容易被忽略的一层。它决定的是"哪些模型能在会话模型选择器里被选到"。即使前两层都配好，只要 allow 白名单里没有这个模型，选择器里就不会出现它。

查配置发现，modelPolicy.allow 里只有：

• sapiens/agnes-2.5-flash
• sapiens/agnes-2.5-pro-alpha

唯独没有 sapiens/agnes-3.0-flash。这就是根因。

三层机制：一张表说清楚

三层各管一件事，互相独立。缺任何一层，模型就"不可见"。

本次排查中，前两层都齐了，唯独第三层漏了。所以现象是：配置 validate 全过、别名也在、但选择器里看不到。

修复：把模型加进白名单，再重启网关

修复本身很简单，就是把 sapiens/agnes-3.0-flash 加进 modelPolicy.allow：

"modelPolicy": {
  "allow": [
    "sapiens/agnes-2.5-flash",
    "sapiens/agnes-2.5-pro-alpha",
    "sapiens/agnes-3.0-flash"
  ]
}

改完先备份配置（openclaw.json.bak.202609141002），再跑 openclaw doctor 验证通过，然后重启网关。

网关重启过程中 webchat 会话会收到一条系统消息，提示"上一个回合被网关重启打断"，这是正常的，不是报错。重启完成后，在 webchat 里输入 /models，sapiens/agnes-3.0-flash 就出现在列表里了。

踩坑复盘

这次排查最大的教训是：“配置 validate 全过"不等于"功能可见”。OpenClaw 的模型系统是分层的，validate 只检查配置本身语法和注册完整性，不检查 modelPolicy.allow 这类白名单。所以出现"validate 全过但选择器里没有"时，应该直接去查白名单层，而不是反复重启网关怀疑缓存。

另一个容易混淆的点：agents.defaults.models（别名）和 agents.defaults.modelPolicy.allow（白名单）是独立的两个配置，改别名不会自动进白名单，改白名单也不会自动配别名。三层都要配齐，模型才真正可用。

参考来源

• OpenClaw 配置文档：docs/gateway/configuration.md
• 自定义 provider 配置示例：docs/gateway/configuration-reference.md

FAQ

Q: OpenClaw 配置 validate 全过但模型选择器看不到新模型？ A: 检查 agents.defaults.modelPolicy.allow 白名单，三层配置缺一不可。

Q: providers.sapiens.models 和 agents.defaults.modelPolicy.allow 有什么区别？ A: 前者定义模型元数据（API端点、上下文窗口等），后者控制模型在会话选择器中的可见性。

Q: 修改 modelPolicy.allow 后需要重启网关吗？ A: 需要，配置修改后重启网关生效。