openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-28 22:40:11 +00:00
parent 5c0105d993
commit 7bc580e19e
2 changed files with 125 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
docs/zh-CN/channels/troubleshooting.md
View File

@ -1,21 +1,21 @@
---
read_when:
- 渠道传输协议显示已连接，但回复失败
- 在深入查看提供商文档之前，你需要先进行渠道特定检查
summary: 快速的渠道级故障排除，包含各渠道故障特征和修复方法
- 在深入阅读提供商文档前，你需要进行渠道特定检查
summary: 渠道级快速故障排除，包含各渠道的失败特征和修复方法
title: 渠道故障排除
x-i18n:
generated_at: "2026-04-28T11:46:19Z"
generated_at: "2026-04-28T22:39:13Z"
model: gpt-5.5
provider: openai
source_hash: 5f1d6821924972e7fe91c98a57e35e23281a440a400d5bbd6eee1bb5550e05c1
source_hash: 6024f2ae0a058b2296758c237c912a5cd8ea6bbafea33cc201690cc081efcbee
source_path: channels/troubleshooting.md
workflow: 16
---
当渠道已连接但行为异常时，请使用本页。
当渠道连接成功但行为异常时，使用本页。
## 命令阶梯
## 命令排查顺序
先按顺序运行这些命令：
@ -32,18 +32,18 @@ openclaw channels status --probe
- `Runtime: running`
- `Connectivity probe: ok`
- `Capability: read-only`、`write-capable` 或 `admin-capable`
- 渠道探测显示传输已连接，并且在支持的位置显示 `works` 或 `audit ok`
- 渠道探测显示传输协议已连接，并且在支持的情况下显示 `works` 或 `audit ok`
## WhatsApp
### WhatsApp 故障特征
| 现象 | 最快检查 | 修复 |
| ------------------------------- | --------------------------------------------------- | -------------------------------------------------------- |
| 已连接但没有私信回复 | `openclaw pairing list whatsapp` | 批准发送者，或切换私信策略/允许列表。 |
| 群组消息被忽略 | 检查配置中的 `requireMention` 和提及模式 | 提及机器人，或放宽该群组的提及策略。 |
| 二维码登录超时并显示 408 | 检查 Gateway 网关的 `HTTPS_PROXY` / `HTTP_PROXY` 环境变量 | 设置可访问的代理；仅将 `NO_PROXY` 用于绕过。 |
| 随机断开/重新登录循环 | `openclaw channels status --probe` + 日志 | 重新登录并确认凭证目录健康。 |
| 现象 | 最快检查 | 修复 |
| ------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 已连接但没有私信回复 | `openclaw pairing list whatsapp` | 批准发送者，或切换私信策略/允许列表。 |
| 群组消息被忽略 | 检查配置中的 `requireMention` 和提及模式 | 提及机器人，或放宽该群组的提及策略。 |
| 二维码登录超时并返回 408 | 检查 Gateway 网关的 `HTTPS_PROXY` / `HTTP_PROXY` 环境变量 | 设置可访问的代理；仅将 `NO_PROXY` 用于绕过代理。 |
| 随机断开连接/重新登录循环 | `openclaw channels status --probe` + 日志 | 即使当前已连接，最近的重连也会被标记；观察日志，重启 Gateway 网关，如果仍然反复抖动，再重新链接。 |
完整故障排除：[WhatsApp 故障排除](/zh-CN/channels/whatsapp#troubleshooting)
@ -51,15 +51,15 @@ openclaw channels status --probe
### Telegram 故障特征
| 现象 | 最快检查 | 修复 |
| ------------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `/start` 后没有可用的回复流程 | `openclaw pairing list telegram` | 批准配对或更改私信策略。 |
| 机器人在线但群组保持静默 | 验证提及要求和机器人隐私模式 | 禁用隐私模式以便群组可见，或提及机器人。 |
| 发送失败并出现网络错误 | 检查日志中的 Telegram API 调用失败 | 修复到 `api.telegram.org` 的 DNS/IPv6/代理路由。 |
| 启动报告 `getMe returned 401` | 检查配置的令牌来源 | 重新复制或重新生成 BotFather 令牌，并更新 `botToken`、`tokenFile` 或默认账户 `TELEGRAM_BOT_TOKEN`。 |
| 轮询停滞或重连缓慢 | 用 `openclaw logs --follow` 查看轮询诊断 | 升级；如果重启是误报，请调优 `pollingStallThresholdMs`。持续停滞仍然指向代理/DNS/IPv6 问题。 |
| 启动时 `setMyCommands` 被拒绝 | 检查日志中的 `BOT_COMMANDS_TOO_MUCH` | 减少插件/skill/自定义 Telegram 命令，或禁用原生命令菜单。 |
| 升级后允许列表阻止你 | `openclaw security audit` 和配置允许列表 | 运行 `openclaw doctor --fix`，或将 `@username` 替换为数字发送者 ID。 |
| 现象 | 最快检查 | 修复 |
| ------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `/start` 后没有可用的回复流程 | `openclaw pairing list telegram` | 批准配对，或更改私信策略。 |
| 机器人在线但群组保持静默 | 验证提及要求和机器人隐私模式 | 禁用隐私模式以获得群组可见性，或提及机器人。 |
| 发送失败并伴随网络错误 | 检查日志中的 Telegram API 调用失败 | 修复到 `api.telegram.org` 的 DNS/IPv6/代理路由。 |
| 启动时报 `getMe returned 401` | 检查配置的令牌来源 | 重新复制或重新生成 BotFather 令牌，并更新 `botToken`、`tokenFile` 或默认账户的 `TELEGRAM_BOT_TOKEN`。 |
| 轮询卡住或重连缓慢 | 使用 `openclaw logs --follow` 查看轮询诊断 | 升级；如果重启是误报，调整 `pollingStallThresholdMs`。持续卡住仍然指向代理/DNS/IPv6 问题。 |
| 启动时 `setMyCommands` 被拒绝 | 检查日志中的 `BOT_COMMANDS_TOO_MUCH` | 减少插件/Skills/自定义 Telegram 命令，或禁用原生命令菜单。 |
| 升级后允许列表阻止了你 | `openclaw security audit` 和配置允许列表 | 运行 `openclaw doctor --fix`，或将 `@username` 替换为数字发送者 ID。 |
完整故障排除：[Telegram 故障排除](/zh-CN/channels/telegram#troubleshooting)
@ -67,11 +67,11 @@ openclaw channels status --probe
### Discord 故障特征
| 现象 | 最快检查 | 修复 |
| ---------------------------- | ---------------------------------- | ---------------------------------------------------------- |
| 机器人在线但没有服务器回复 | `openclaw channels status --probe` | 允许服务器/渠道并验证消息内容意图。 |
| 群组消息被忽略 | 检查日志中的提及门控丢弃 | 提及机器人，或设置服务器/渠道 `requireMention: false`。 |
| 私信回复缺失 | `openclaw pairing list discord` | 批准私信配对或调整私信策略。 |
| 现象 | 最快检查 | 修复 |
| ---------------------------- | ----------------------------------- | ---------------------------------------------------------- |
| 机器人在线但没有服务器回复 | `openclaw channels status --probe` | 允许服务器/渠道，并验证消息内容意图。 |
| 群组消息被忽略 | 检查日志中的提及门控丢弃记录 | 提及机器人，或设置服务器/渠道 `requireMention: false`。 |
| 缺少私信回复 | `openclaw pairing list discord` | 批准私信配对，或调整私信策略。 |
完整故障排除：[Discord 故障排除](/zh-CN/channels/discord#troubleshooting)
@ -79,11 +79,11 @@ openclaw channels status --probe
### Slack 故障特征
| 现象 | 最快检查 | 修复 |
| ---------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Socket mode 已连接但没有响应 | `openclaw channels status --probe` | 验证应用令牌 + 机器人令牌以及所需范围；在基于 SecretRef 的设置中留意 `botTokenStatus` / `appTokenStatus = configured_unavailable`。 |
| 私信被阻止 | `openclaw pairing list slack` | 批准配对或放宽私信策略。 |
| 渠道消息被忽略 | 检查 `groupPolicy` 和渠道允许列表 | 允许该渠道，或将策略切换为 `open`。 |
| 现象 | 最快检查 | 修复 |
| ------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Socket mode 已连接但没有响应 | `openclaw channels status --probe` | 验证应用令牌 + 机器人令牌和所需作用域；在 SecretRef 支持的设置中留意 `botTokenStatus` / `appTokenStatus = configured_unavailable`。 |
| 私信被阻止 | `openclaw pairing list slack` | 批准配对，或放宽私信策略。 |
| 渠道消息被忽略 | 检查 `groupPolicy` 和渠道允许列表 | 允许该渠道，或将策略切换为 `open`。 |
完整故障排除：[Slack 故障排除](/zh-CN/channels/slack#troubleshooting)
@ -91,11 +91,11 @@ openclaw channels status --probe
### iMessage 和 BlueBubbles 故障特征
| 现象 | 最快检查 | 修复 |
| -------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------ |
| 没有入站事件 | 验证 webhook/服务器可访问性和应用权限 | 修复 webhook URL 或 BlueBubbles 服务器状态。 |
| 在 macOS 上可以发送但无法接收 | 检查 Messages 自动化的 macOS 隐私权限 | 重新授予 TCC 权限并重启渠道进程。 |
| 私信发送者被阻止 | `openclaw pairing list imessage` 或 `openclaw pairing list bluebubbles` | 批准配对或更新允许列表。 |
| 现象 | 最快检查 | 修复 |
| --------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------ |
| 没有入站事件 | 验证 webhook/服务器可达性和应用权限 | 修复 webhook URL 或 BlueBubbles 服务器状态。 |
| macOS 上可以发送但无法接收 | 检查 macOS Messages 自动化的隐私权限 | 重新授予 TCC 权限并重启渠道进程。 |
| 私信发送者被阻止 | `openclaw pairing list imessage` 或 `openclaw pairing list bluebubbles` | 批准配对，或更新允许列表。 |
完整故障排除：
@ -106,11 +106,11 @@ openclaw channels status --probe
### Signal 故障特征
| 现象 | 最快检查 | 修复 |
| ---------------------------- | ----------------------------------------- | -------------------------------------------------------- |
| 守护进程可访问但机器人静默 | `openclaw channels status --probe` | 验证 `signal-cli` 守护进程 URL/账户和接收模式。 |
| 私信被阻止 | `openclaw pairing list signal` | 批准发送者或调整私信策略。 |
| 群组回复未触发 | 检查群组允许列表和提及模式 | 添加发送者/群组，或放宽门控。 |
| 现象 | 最快检查 | 修复 |
| ---------------------------- | ------------------------------------------ | --------------------------------------------------------- |
| 守护进程可达但机器人静默 | `openclaw channels status --probe` | 验证 `signal-cli` 守护进程 URL/账户和接收模式。 |
| 私信被阻止 | `openclaw pairing list signal` | 批准发送者，或调整私信策略。 |
| 群组回复未触发 | 检查群组允许列表和提及模式 | 添加发送者/群组，或放宽门控。 |
完整故障排除：[Signal 故障排除](/zh-CN/channels/signal#troubleshooting)
@ -118,12 +118,12 @@ openclaw channels status --probe
### QQ Bot 故障特征
| 现象 | 最快检查 | 修复 |
| ------------------------------ | ------------------------------------------- | --------------------------------------------------------------- |
| 机器人回复“gone to Mars” | 验证配置中的 `appId` 和 `clientSecret` | 设置凭证或重启 Gateway 网关。 |
| 没有入站消息 | `openclaw channels status --probe` | 在 QQ Open Platform 上验证凭证。 |
| 语音未转写 | 检查 STT 提供商配置 | 配置 `channels.qqbot.stt` 或 `tools.media.audio`。 |
| 主动消息未到达 | 检查 QQ 平台交互要求 | 如果近期没有交互，QQ 可能会阻止机器人发起的消息。 |
| 现象 | 最快检查 | 修复 |
| ------------------------------- | ------------------------------------------- | --------------------------------------------------------------- |
| 机器人回复“gone to Mars” | 验证配置中的 `appId` 和 `clientSecret` | 设置凭证或重启 Gateway 网关。 |
| 没有入站消息 | `openclaw channels status --probe` | 在 QQ Open Platform 上验证凭证。 |
| 语音未转写 | 检查 STT 提供商配置 | 配置 `channels.qqbot.stt` 或 `tools.media.audio`。 |
| 主动消息未到达 | 检查 QQ 平台交互要求 | 如果近期没有交互，QQ 可能会阻止机器人发起的消息。 |
完整故障排除：[QQ Bot 故障排除](/zh-CN/channels/qqbot#troubleshooting)
@ -131,17 +131,17 @@ openclaw channels status --probe
### Matrix 故障特征
| 现象 | 最快检查 | 修复 |
| -------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------- |
| 已登录但忽略房间消息 | `openclaw channels status --probe` | 检查 `groupPolicy`、房间允许列表和提及门控。 |
| 私信不处理 | `openclaw pairing list matrix` | 批准发送者或调整私信策略。 |
| 加密房间失败 | `openclaw matrix verify status` | 重新验证设备，然后检查 `openclaw matrix verify backup status`。 |
| 备份恢复处于待处理/损坏状态 | `openclaw matrix verify backup status` | 运行 `openclaw matrix verify backup restore`，或使用恢复密钥重新运行。 |
| 交叉签名/bootstrap 看起来异常 | `openclaw matrix verify bootstrap` | 一次性修复密钥存储、交叉签名和备份状态。 |
| 现象 | 最快检查 | 修复 |
| ----------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
| 已登录但忽略房间消息 | `openclaw channels status --probe` | 检查 `groupPolicy`、房间允许列表和提及门控。 |
| 私信不处理 | `openclaw pairing list matrix` | 批准发送者，或调整私信策略。 |
| 加密房间失败 | `openclaw matrix verify status` | 重新验证设备，然后检查 `openclaw matrix verify backup status`。 |
| 备份恢复处于待处理/损坏状态 | `openclaw matrix verify backup status` | 运行 `openclaw matrix verify backup restore`，或带恢复密钥重新运行。 |
| 交叉签名/bootstrap 看起来异常 | `openclaw matrix verify bootstrap` | 一次性修复秘密存储、交叉签名和备份状态。 |
完整设置和配置：[Matrix](/zh-CN/channels/matrix)
## 相关内容
## 相关
- [配对](/zh-CN/channels/pairing)
- [渠道路由](/zh-CN/channels/channel-routing)

133
docs/zh-CN/concepts/models.md
View File

@ -2,22 +2,22 @@
read_when:
- 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks）
- 更改模型回退行为或选择体验
- 更新模型扫描探针（工具/图像）
- 更新模型扫描探针（工具/图片）
sidebarTitle: Models CLI
summary: Models CLI：列出、设置、别名、回退、扫描、状态
summary: Models CLI：列出、设置、别名、回退、扫描、Status
title: Models CLI
x-i18n:
generated_at: "2026-04-28T11:50:00Z"
generated_at: "2026-04-28T22:39:17Z"
model: gpt-5.5
provider: openai
source_hash: 1d7ac971cf8e7b713a48c917eb4a95382372bf08afacff3e1cbb62d3da97965d
source_hash: 4fde5131ee4bde7d22f2423124420704cc0cd5ab0daa04d7c091baa74f0fcc61
source_path: concepts/models.md
workflow: 16
---
<CardGroup cols={2}>
<Card title="模型故障转移" href="/zh-CN/concepts/model-failover">
凭证配置文件轮换、冷却时间，以及它们如何与回退交互。
凭证配置轮换、冷却时间，以及它如何与后备模型交互。
</Card>
<Card title="模型提供商" href="/zh-CN/concepts/model-providers">
快速提供商概览和示例。
@ -32,7 +32,7 @@ x-i18n:
模型引用会选择提供商和模型。它们通常不会选择底层智能体运行时。例如，`openai/gpt-5.5` 可以通过常规 OpenAI provider 路径运行，也可以通过 Codex 应用服务器运行时运行，具体取决于 `agents.defaults.agentRuntime.id`。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
## 模型选择如何工作
## 模型选择的工作方式
OpenClaw 按以下顺序选择模型：
@ -40,43 +40,43 @@ OpenClaw 按以下顺序选择模型：
<Step title="主模型">
`agents.defaults.model.primary`（或 `agents.defaults.model`）。
</Step>
<Step title="回退">
<Step title="后备模型">
`agents.defaults.model.fallbacks`（按顺序）。
</Step>
<Step title="提供商凭证故障转移">
凭证故障转移会在提供商内部发生，然后才会移动到下一个模型。
凭证故障转移发生在提供商内部，然后才会切换到下一个模型。
</Step>
</Steps>
<AccordionGroup>
<Accordion title="相关模型表面">
- `agents.defaults.models` 是 OpenClaw 可以使用的模型允许列表/目录（外加别名）。
- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（以及别名）。
- `agents.defaults.imageModel` **仅在**主模型无法接受图像时使用。
- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后是已解析的会话/默认模型。
- `agents.defaults.imageGenerationModel` 由共享图像生成能力使用。如果省略，`image_generate` 仍可推断有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试剩余已注册的图像生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API 密钥。
- `agents.defaults.musicGenerationModel` 由共享音乐生成能力使用。如果省略，`music_generate` 仍可推断有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试剩余已注册的音乐生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API 密钥。
- `agents.defaults.videoGenerationModel` 由共享视频生成能力使用。如果省略，`video_generate` 仍可推断有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试剩余已注册的视频生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API 密钥。
- 单个智能体的默认值可以通过 `agents.list[].model` 加绑定覆盖 `agents.defaults.model`（参见 [多智能体路由](/zh-CN/concepts/multi-agent)）。
- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后回退到已解析的会话/默认模型。
- `agents.defaults.imageGenerationModel` 由共享的图像生成能力使用。如果省略，`image_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API 密钥。
- `agents.defaults.musicGenerationModel` 由共享的音乐生成能力使用。如果省略，`music_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API 密钥。
- `agents.defaults.videoGenerationModel` 由共享的视频生成能力使用。如果省略，`video_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API 密钥。
- 每个智能体的默认值可以通过 `agents.list[].model` 加绑定来覆盖 `agents.defaults.model`（参见[多智能体路由](/zh-CN/concepts/multi-agent)）。
</Accordion>
</AccordionGroup>
## 选择来源和回退行为
## 选择来源和后备行为
同一个 `provider/model` 可能因来源不同而含义不同：
同一个 `provider/model` 可能会根据来源代表不同含义：
- 已配置的默认值（`agents.defaults.model.primary` 和智能体专属主模型）是常规起点，并使用 `agents.defaults.model.fallbacks`。
- 自动回退选择是临时恢复状态。它们会以 `modelOverrideSource: "auto"` 存储，因此后续轮次可以继续使用回退链，而无需先探测已知不可用的主模型。
- 自动后备选择是临时恢复状态。它们会以 `modelOverrideSource: "auto"` 存储，这样后续轮次可以继续使用后备链，而无需先探测已知不可用的主模型。
- 用户会话选择是精确的。`/model`、模型选择器、`session_status(model=...)` 和 `sessions.patch` 会存储 `modelOverrideSource: "user"`；如果所选提供商/模型不可达，OpenClaw 会显式失败，而不是继续落到另一个已配置模型。
- Cron `--model` / 载荷 `model` 是每个作业的主模型。除非作业提供显式载荷 `fallbacks`，否则它仍使用已配置回退（使用 `fallbacks: []` 可进行严格的 cron 运行）。
- CLI 默认模型和允许列表选择器会尊重 `models.mode: "replace"`，列出显式 `models.providers.*.models`，而不是加载完整内置目录。
- Control UI 模型选择器会向 Gateway 网关请求其已配置的模型视图：存在时使用 `agents.defaults.models`，否则使用显式 `models.providers.*.models`，否则使用完整目录，这样全新安装不会显示为空。
- Cron `--model` / 载荷 `model` 是每个作业的主模型。除非作业提供显式载荷 `fallbacks`，否则它仍会使用已配置的后备模型（使用 `fallbacks: []` 可进行严格 cron 运行）。
- CLI 默认模型和允许列表选择器会遵循 `models.mode: "replace"`，列出显式的 `models.providers.*.models`，而不是加载完整内置目录。
- Control UI 模型选择器会向 Gateway 网关请求其已配置的模型视图：存在 `agents.defaults.models` 时使用它，否则使用显式的 `models.providers.*.models`，否则使用完整目录，避免新安装显示为空。
## 快速模型策略
- 将主模型设置为你可用的最强最新一代模型。
- 对成本/延迟敏感任务和低风险聊天使用回退。
- 对启用工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。
- 将主模型设置为你可用的最强新一代模型。
- 对成本/延迟敏感任务和较低风险聊天使用后备模型。
- 对启用工具的智能体或不受信任输入，避免使用较旧/较弱的模型层级。
## 新手引导（推荐）
@ -106,22 +106,22 @@ openclaw onboard
### 安全编辑允许列表
手动更新 `agents.defaults.models` 时使用追加写入：
手动更新 `agents.defaults.models` 时使用增量写入：
```bash
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
```
<AccordionGroup>
<Accordion title="覆盖保护规则">
`openclaw config set` 会保护模型/提供商映射，防止意外覆盖。当普通对象赋值会移除现有条目时，对 `agents.defaults.models`、`models.providers` 或 `models.providers.<id>.models` 的赋值会被拒绝。使用 `--merge` 进行追加更改；仅在所提供的值应成为完整目标值时使用 `--replace`。
<Accordion title="防覆盖保护规则">
`openclaw config set` 会保护模型/提供商映射，避免意外覆盖。当对 `agents.defaults.models`、`models.providers` 或 `models.providers.<id>.models` 的普通对象赋值会移除现有条目时，该操作会被拒绝。使用 `--merge` 进行增量更改；仅当提供的值应成为完整目标值时，才使用 `--replace`。
交互式提供商设置和 `openclaw configure --section model` 也会将提供商范围的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商不会丢弃无关模型条目。重新应用提供商凭证时，configure 会保留现有的 `agents.defaults.model.primary`。显式默认值设置命令，例如 `openclaw models auth login --provider <id> --set-default` 和 `openclaw models set <model>`，仍会替换 `agents.defaults.model.primary`。
交互式提供商设置和 `openclaw configure --section model` 也会将提供商作用域内的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商不会删除无关模型条目。重新应用提供商凭证时，Configure 会保留现有的 `agents.defaults.model.primary`。显式默认值设置命令，例如 `openclaw models auth login --provider <id> --set-default` 和 `openclaw models set <model>`，仍会替换 `agents.defaults.model.primary`。
</Accordion>
</AccordionGroup>
## “模型不被允许”（以及回复为何停止）
## “Model is not allowed”（以及回复为什么停止）
如果设置了 `agents.defaults.models`，它会成为 `/model` 和会话覆盖的**允许列表**。当用户选择不在该允许列表中的模型时，OpenClaw 会返回：
@ -130,14 +130,19 @@ Model "provider/model" is not allowed. Use /model to list available models.
```
<Warning>
这发生在正常回复生成**之前**，所以这条消息可能让人感觉它“没有响应”。修复方式是：
这发生在生成常规回复**之前**，因此消息可能让人感觉像是“没有响应”。修复方法是：
- 将该模型添加到 `agents.defaults.models`，或
- 清除允许列表（移除 `agents.defaults.models`），或
- 将模型添加到 `agents.defaults.models`，或
- 清空允许列表（移除 `agents.defaults.models`），或
- 从 `/model list` 选择一个模型。
</Warning>
对于本地/GGUF 模型，请在允许列表中存储完整的带提供商前缀引用，
例如 `ollama/gemma4:26b`、`lmstudio/Gemma4-26b-a4-it-gguf`，或
`openclaw models list --provider <provider>` 显示的确切提供商/模型。
允许列表启用时，仅使用本地文件名或显示名称是不够的。
允许列表示例配置：
```json5
@ -154,7 +159,7 @@ Model "provider/model" is not allowed. Use /model to list available models.
## 在聊天中切换模型（`/model`）
你可以无需重启即可为当前会话切换模型：
你可以在不重启的情况下切换当前会话的模型：
```
/model
@ -166,28 +171,28 @@ Model "provider/model" is not allowed. Use /model to list available models.
<AccordionGroup>
<Accordion title="选择器行为">
- `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型族 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，包含提供商和模型下拉菜单以及提交步骤。
- `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开带有提供商和模型下拉菜单以及提交步骤的交互式选择器。
- `/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。
- `/model <#>` 会从该选择器中选择。
</Accordion>
<Accordion title="持久化和实时切换">
- `/model` 会立即持久化新的会话选择。
- 如果智能体处于空闲状态，下一次运行会立即使用新模型。
- 如果某次运行已处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会保持排队，直到后续重试机会或下一次用户轮次。
- 用户选择的 `/model` 引用对该会话是严格的：如果所选提供商/模型不可达，回复会显式失败，而不是静默地从 `agents.defaults.model.fallbacks` 回答。这不同于已配置默认值和 cron 作业主模型，后者仍可使用回退链。
- `/model status` 是详细视图（凭证候选项，以及配置时的提供商端点 `baseUrl` + `api` 模式）。
- 如果智能体空闲，下一次运行会立即使用新模型。
- 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续重试机会或下一轮用户输入。
- 用户选择的 `/model` 引用对该会话是严格的：如果所选提供商/模型不可达，回复会显式失败，而不是静默地从 `agents.defaults.model.fallbacks` 回答。这不同于已配置默认值和 cron 作业主模型，它们仍可使用后备链。
- `/model status` 是详细视图（凭证候选项，以及配置后显示的提供商端点 `baseUrl` + `api` 模式）。
</Accordion>
<Accordion title="引用解析">
- 模型引用通过按**第一个** `/` 拆分来解析。输入 `/model <ref>` 时使用 `provider/model`。
- 模型引用通过按**第一个** `/` 拆分进行解析。输入 `/model <ref>` 时使用 `provider/model`。
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。
- 如果省略提供商，OpenClaw 会按以下顺序解析输入：
1. 别名匹配
2. 对该精确未加前缀模型 ID 的唯一已配置提供商匹配
3. 已弃用的回退到已配置默认提供商 —— 如果该提供商不再暴露已配置的默认模型，OpenClaw 会改为回退到第一个已配置提供商/模型，以避免暴露过时的已移除提供商默认值。
2. 针对该精确无前缀模型 ID 的唯一已配置提供商匹配
3. 已弃用的回退到已配置默认提供商 — 如果该提供商不再公开已配置默认模型，OpenClaw 会改为回退到第一个已配置提供商/模型，以避免暴露陈旧的已移除提供商默认值。
</Accordion>
</AccordionGroup>
@ -223,13 +228,13 @@ openclaw models image-fallbacks clear
默认显示已配置模型。实用标志：
<ParamField path="--all" type="boolean">
完整目录。包括在配置凭证之前由内置提供商拥有的静态目录行，因此仅设备发现视图可以显示在添加匹配提供商凭证前不可用的模型。
完整目录。包含配置凭证前内置的提供商自有静态目录行，因此仅用于设备发现的视图也可以显示模型；这些模型在添加匹配的提供商凭证前不可用。
</ParamField>
<ParamField path="--local" type="boolean">
仅本地提供商。
</ParamField>
<ParamField path="--provider <id>" type="string">
按提供商 ID 过滤，例如 `moonshot`。不接受交互式选择器中的显示标签。
按提供商 ID 筛选，例如 `moonshot`。不接受交互式选择器中的显示标签。
</ParamField>
<ParamField path="--plain" type="boolean">
每行一个模型。
@ -240,21 +245,21 @@ openclaw models image-fallbacks clear
### `models status`
显示已解析的主模型、回退、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内警告）。`--plain` 仅打印已解析的主模型。
显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会展示在凭证存储中找到的配置文件的 OAuth 过期 Status（默认在 24 小时内发出警告）。`--plain` 只打印已解析的主模型。
<AccordionGroup>
<Accordion title="Auth and probe behavior">
- OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印 **缺少认证** 部分。
- JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效认证，包括由环境变量支持的凭证）。`auth.oauth` 只表示 auth-store 配置文件健康状态；仅使用环境变量的提供商不会出现在那里。
- 将 `--check` 用于自动化（缺失/过期时退出 `1`，即将过期时退出 `2`）。
- 将 `--probe` 用于实时认证检查；探测行可以来自认证配置文件、环境变量凭证或 `models.json`。
- 如果显式的 `auth.order.<provider>` 省略了已存储的配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果存在认证但无法为该提供商解析出可探测的模型，探测会报告 `status: no_model`。
<Accordion title="凭证和探测行为">
- OAuth Status 始终显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印 **缺少凭证** 部分。
- JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效凭证，包括环境变量支持的凭证）。`auth.oauth` 仅表示凭证存储配置文件的健康状态；仅使用环境变量的提供商不会出现在其中。
- 对自动化使用 `--check`（缺失/过期时退出 `1`，即将过期时退出 `2`）。
- 使用 `--probe` 进行实时凭证检查；探测行可以来自凭证配置文件、环境变量凭证或 `models.json`。
- 如果显式的 `auth.order.<provider>` 省略了已存储的配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果存在凭证，但无法为该提供商解析出可探测的模型，探测会报告 `status: no_model`。
</Accordion>
</AccordionGroup>
<Note>
认证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API 密钥通常最可预测；也支持复用 Claude CLI，以及使用现有 Anthropic OAuth/token 配置文件。
凭证选择取决于提供商/账号。对于始终在线的 Gateway 网关主机，API 密钥通常最可预测；也支持复用 Claude CLI，以及使用现有 Anthropic OAuth/token 配置文件。
</Note>
示例（Claude CLI）：
@ -266,7 +271,7 @@ openclaw models status
## 扫描（OpenRouter 免费模型）
`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型对工具和图像的支持情况。
`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型的工具和图像支持。
<ParamField path="--no-probe" type="boolean">
跳过实时探测（仅元数据）。
@ -291,7 +296,7 @@ openclaw models status
</ParamField>
<Note>
OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没有密钥的情况下列出免费候选项。探测和推理仍需要 OpenRouter API 密钥（来自认证配置文件或 `OPENROUTER_API_KEY`）。如果没有可用密钥，`openclaw models scan` 会回退到仅元数据输出，并保持配置不变。使用 `--no-probe` 可显式请求仅元数据模式。
OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没有密钥的情况下列出免费候选项。探测和推理仍需要 OpenRouter API 密钥（来自凭证配置文件或 `OPENROUTER_API_KEY`）。如果没有可用密钥，`openclaw models scan` 会回退到仅元数据输出，并保持配置不变。使用 `--no-probe` 可显式请求仅元数据模式。
</Note>
扫描结果按以下顺序排名：
@ -304,32 +309,32 @@ OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没
输入：
- OpenRouter `/models` 列表（过滤 `:free`）
- 实时探测需要来自认证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见[环境变量](/zh-CN/help/environment)）
- 实时探测需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（见[环境变量](/zh-CN/help/environment)）
- 可选过滤器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
- 请求/探测控制：`--timeout`、`--concurrency`
在 TTY 中运行实时探测时，你可以交互式选择回退项。在非交互模式下，传入 `--yes` 接受默认值。仅元数据结果只供参考；`--set-default` 和 `--set-image` 需要实时探测，以免 OpenClaw 配置无法使用的无密钥 OpenRouter 模型。
当实时探测在 TTY 中运行时，你可以交互式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。仅元数据结果只供参考；`--set-default` 和 `--set-image` 需要实时探测，因此 OpenClaw 不会配置无法使用的无密钥 OpenRouter 模型。
## 模型注册表（`models.json`）
`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认 `~/.openclaw/agents/<agentId>/agent/models.json`）。除非 `models.mode` 设置为 `replace`，否则默认会合并此文件。
<AccordionGroup>
<Accordion title="Merge mode precedence">
<Accordion title="合并模式优先级">
匹配提供商 ID 时的合并模式优先级：
- 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。
- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商未由当前配置/auth-profile 上下文中的 SecretRef 管理时优先。
- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用为 `ENV_VAR_NAME`，文件/执行引用为 `secretref-managed`），而不是持久化已解析的密钥。
- 由 SecretRef 管理的提供商标头值会从源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，文件/执行引用为 `secretref-managed`）。
- 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置 `models.providers`。
- 其他提供商字段会从配置和规范化的目录数据刷新。
- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商未由当前配置/凭证配置文件上下文中的 SecretRef 管理时优先。
- SecretRef 管理的提供商 `apiKey` 值会从来源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/执行引用使用 `secretref-managed`），而不是持久化已解析的机密。
- SecretRef 管理的提供商标头值会从来源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/执行引用使用 `secretref-managed`）。
- 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置 `models.providers`。
- 其他提供商字段会从配置和规范化后的目录数据刷新。
</Accordion>
</AccordionGroup>
<Note>
标记持久化以来源为权威：OpenClaw 从活动源配置快照（解析前）写入标记，而不是从已解析的运行时密钥值写入。每当 OpenClaw 重新生成 `models.json` 时都会如此，包括像 `openclaw agent` 这样的命令驱动路径。
标记持久化以来源为权威：OpenClaw 会从活动来源配置快照（解析前）写入标记，而不是从已解析的运行时机密值写入。只要 OpenClaw 重新生成 `models.json`，包括像 `openclaw agent` 这样的命令驱动路径，都会应用此规则。
</Note>
## 相关
@ -338,6 +343,6 @@ OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没
- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键
- [图像生成](/zh-CN/tools/image-generation) — 图像模型配置
- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链
- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由和认证
- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由和凭证
- [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置
- [视频生成](/zh-CN/tools/video-generation) — 视频模型配置