Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Model 和 auth-profile 问答。关于设置、会话、Gateway 网关、渠道和 故障排除，请参阅主 常见问题。

​
Models：默认值、选择、别名、切换

OpenClaw 的默认模型就是你设置为以下值的模型：
agents.defaults.model.primary
模型以 provider/model 形式引用（示例：openai/gpt-5.5 或 anthropic/claude-sonnet-4-6）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试与该确切模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商，这是一条已弃用的兼容路径。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个陈旧的已移除提供商默认值。你仍然应该显式设置 provider/model。
**推荐默认值：**使用你的提供商栈中可用的最强最新一代模型。 **对于启用工具或处理不可信输入的智能体：**优先考虑模型能力而不是成本。 **对于日常/低风险聊天：**使用更便宜的备用模型，并按智能体角色路由。MiniMax 有自己的文档：MiniMax 和 本地模型。经验法则：对高风险工作使用你负担得起的最佳模型，对日常聊天或摘要使用更便宜的 模型。你可以按智能体路由模型，并使用子智能体并行处理长任务（每个子智能体都会消耗 token）。请参阅 Models 和 子智能体。强烈警告：较弱或过度量化的模型更容易受到提示 注入和不安全行为影响。请参阅 Security。更多背景：Models。
使用模型命令，或只编辑模型字段。避免完整替换配置。安全选项：
  • 聊天中的 /model（快速，按会话生效）
  • openclaw models set ...（仅更新模型配置）
  • openclaw configure --section model（交互式）
  • 编辑 ~/.openclaw/openclaw.json 中的 agents.defaults.model
避免对部分对象使用 config.apply，除非你打算替换整个配置。 对于 RPC 编辑，先用 config.schema.lookup 检查，并优先使用 config.patch。lookup 载荷会给出规范化路径、浅层 schema 文档/约束，以及直接子项摘要。 用于部分更新。 如果你确实覆盖了配置，请从备份恢复，或重新运行 openclaw doctor 来修复。文档：Models、Configure、配置、Doctor。
可以。Ollama 是使用本地模型最简单的路径。最快设置：
  1. 从 https://ollama.com/download 安装 Ollama
  2. 拉取本地模型，例如 ollama pull gemma4
  3. 如果你也想使用云端模型，运行 ollama signin
  4. 运行 openclaw onboard 并选择 Ollama
  5. 选择 Local 或 Cloud + Local
说明：
  • Cloud + Local 会提供云端模型以及你的本地 Ollama 模型
  • 像 kimi-k2.5:cloud 这样的云端模型不需要本地拉取
  • 对于手动切换，使用 openclaw models list 和 openclaw models set ollama/<model>
安全说明：较小或重度量化的模型更容易受到提示 注入影响。对于任何可以使用工具的 bot，我们强烈建议使用大模型。 如果你仍然想使用小模型，请启用沙箱隔离和严格的工具 allowlist。文档：Ollama、本地模型、 模型提供商、Security、 沙箱隔离。
  • 这些部署可能不同，并且可能随时间变化；没有固定的提供商推荐。
  • 用 openclaw models status 检查每个 Gateway 网关上的当前运行时设置。
  • 对于安全敏感/启用工具的智能体，使用可用的最强最新一代模型。
将 /model 命令作为独立消息使用：
/model sonnet
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash
/model gemini-flash-lite
这些是内置别名。可以通过 agents.defaults.models 添加自定义别名。你可以用 /model、/model list 或 /model status 列出可用模型。/model（以及 /model list）会显示一个紧凑的编号选择器。按编号选择：
/model 3
你也可以为提供商强制使用特定 auth profile（按会话生效）：
/model opus@anthropic:default
/model opus@anthropic:work
提示：/model status 会显示当前活跃的智能体、正在使用的 auth-profiles.json 文件，以及接下来会尝试哪个 auth profile。 它还会在可用时显示已配置的提供商端点（baseUrl）和 API 模式（api）。如何取消固定我用 @profile 设置的 profile？重新运行 /model，但不要带 @profile 后缀：
/model anthropic/claude-opus-4-6
如果你想返回默认值，请从 /model 中选择它（或发送 /model <default provider/model>）。 使用 /model status 确认哪个 auth profile 处于活跃状态。
/model provider/model 会为该会话选择确切的提供商路由。例如，qianfan/deepseek-v4-flash 和 deepseek/deepseek-v4-flash 是不同的模型引用，即使二者都包含 deepseek-v4-flash。OpenClaw 不应仅因为裸模型 ID 匹配，就静默地从一个提供商切换到另一个提供商。用户选择的 /model 引用对 fallback 策略同样严格。如果所选提供商/模型不可用，回复会明确失败，而不是从 agents.defaults.model.fallbacks 回答。已配置的 fallback 链仍适用于已配置默认值、cron 作业主模型，以及自动选择的 fallback 状态。如果从非会话 override 启动的运行允许使用 fallback，OpenClaw 会先尝试请求的提供商/模型，然后尝试已配置的 fallback，最后才尝试已配置的 primary。这可以防止重复的裸模型 ID 直接跳回默认提供商。请参阅 Models 和 Model failover。
可以。把模型选择和运行时选择分开处理：
  • **Native Codex coding agent：**将 agents.defaults.model.primary 设置为 openai/gpt-5.5。当你想使用 ChatGPT/Codex 订阅凭证时，用 openclaw models auth login --provider openai-codex 登录。
  • **智能体循环之外的直接 OpenAI API 任务：**为图像、embeddings、语音、realtime 以及其他非智能体 OpenAI API surface 配置 OPENAI_API_KEY。
  • **OpenAI 智能体 API key 凭证：**使用 /model openai/gpt-5.5，并配置有序的 openai-codex API key profile。
  • **子智能体：**将编码任务路由到一个面向 Codex 的智能体，并为其设置自己的 openai/gpt-5.5 模型。
请参阅 Models 和 斜杠命令。
使用会话开关或配置默认值：
  • **按会话：**在会话使用 openai/gpt-5.5 时发送 /fast on。
  • **按模型默认值：**将 agents.defaults.models["openai/gpt-5.5"].params.fastMode 设置为 true。
示例：
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            fastMode: true,
          },
        },
      },
    },
  },
}
对于 OpenAI，快速模式会在受支持的原生 Responses 请求上映射到 service_tier = "priority"。会话 /fast override 优先于配置默认值。请参阅 Thinking and fast mode 和 OpenAI fast mode。
如果设置了 agents.defaults.models，它会成为 /model 和任何 会话 override 的 allowlist。选择不在该列表中的模型会返回：
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
该错误会代替正常回复返回。修复方法：将确切模型添加到 agents.defaults.models，为动态提供商目录添加类似 "provider/*": {} 的提供商 wildcard，移除 allowlist，或从 /model list 中选择模型。 如果命令还包含 --runtime codex，请先更新 allowlist，然后重试 同一个 /model provider/model --runtime codex 命令。
这表示提供商尚未配置（未找到 MiniMax 提供商配置或 auth profile），所以无法解析模型。修复清单：
  1. 升级到当前 OpenClaw 版本（或从源码 main 运行），然后重启 Gateway 网关。
  2. 确保 MiniMax 已配置（向导或 JSON），或者 MiniMax auth 存在于环境变量/auth profiles 中，以便注入匹配的提供商 （MINIMAX_API_KEY 用于 minimax，MINIMAX_OAUTH_TOKEN 或已存储的 MiniMax OAuth 用于 minimax-portal）。
  3. 根据你的 auth 路径使用确切的模型 ID（区分大小写）： API key 设置使用 minimax/MiniMax-M2.7 或 minimax/MiniMax-M2.7-highspeed，OAuth 设置使用 minimax-portal/MiniMax-M2.7 / minimax-portal/MiniMax-M2.7-highspeed。
  4. 运行： 
    openclaw models list
    并从列表中选择（或在聊天中使用 /model list）。
请参阅 MiniMax 和 Models。
可以。将 MiniMax 设为默认值，并在需要时按会话切换模型。 Fallback 用于错误，不是用于“困难任务”，所以请使用 /model 或单独的智能体。选项 A：按会话切换
{
  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "minimax" },
        "openai/gpt-5.5": { alias: "gpt" },
      },
    },
  },
}
然后：
/model gpt
选项 B：单独的智能体
  • 智能体 A 默认值：MiniMax
  • 智能体 B 默认值：OpenAI
  • 按智能体路由，或使用 /agent 切换
文档：Models、Multi-Agent Routing、MiniMax、OpenAI。
是。OpenClaw 内置了一些默认简写（仅在该模型存在于 agents.defaults.models 中时应用）：
  • opus → anthropic/claude-opus-4-7
  • sonnet → anthropic/claude-sonnet-4-6
  • gpt → openai/gpt-5.4
  • gpt-mini → openai/gpt-5.4-mini
  • gpt-nano → openai/gpt-5.4-nano
  • gemini → google/gemini-3.1-pro-preview
  • gemini-flash → google/gemini-3-flash-preview
  • gemini-flash-lite → google/gemini-3.1-flash-lite-preview
如果你设置了同名的自定义别名，将优先使用你的值。
别名来自 agents.defaults.models.<modelId>.alias。示例：
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
        "anthropic/claude-haiku-4-5": { alias: "haiku" },
      },
    },
  },
}
随后 /model sonnet（或在受支持时使用 /<alias>）会解析为该模型 ID。
OpenRouter（按令牌付费；模型众多）：
{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },
    },
  },
  env: { OPENROUTER_API_KEY: "sk-or-..." },
}
Z.AI（GLM 模型）：
{
  agents: {
    defaults: {
      model: { primary: "zai/glm-5" },
      models: { "zai/glm-5": {} },
    },
  },
  env: { ZAI_API_KEY: "..." },
}
如果你引用了某个提供商/模型，但缺少所需的提供商密钥，就会收到运行时认证错误（例如 No API key found for provider "zai"）。添加新智能体后提示找不到提供商的 API 密钥这通常意味着新智能体的认证存储为空。认证按智能体隔离，并存储在：
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
修复选项：
  • 运行 openclaw agents add <id>，并在向导中配置认证。
  • 或者仅将可移植的静态 api_key / token 配置档案从主智能体的认证存储复制到新智能体的认证存储。
  • 对于 OAuth 配置档案，当新智能体需要自己的账户时，请从该新智能体登录；否则，OpenClaw 可以读取默认/主智能体的配置，而无需克隆刷新令牌。
请不要在多个智能体之间复用 agentDir；这会导致认证/会话冲突。

​
模型故障转移和“所有模型均失败”

故障转移分两个阶段发生：
  1. 同一提供商内的认证配置档案轮换。
  2. 模型回退到 agents.defaults.model.fallbacks 中的下一个模型。
冷却时间会应用到失败的配置档案（指数退避），因此即使某个提供商受到速率限制或暂时失败，OpenClaw 也可以继续响应。速率限制桶包含的不只是普通的 429 响应。OpenClaw 还会将 Too many concurrent requests、 ThrottlingException、concurrency limit reached、 workers_ai ... quota limit exceeded、resource exhausted 以及周期性 用量窗口限制（weekly/monthly limit reached）视为值得触发故障转移的 速率限制。一些看起来像计费问题的响应并不是 402，而一些 HTTP 402 响应也会留在这个瞬态桶中。如果提供商在 401 或 403 上返回 明确的计费文本，OpenClaw 仍可将其保留在计费通道中，但提供商特定的文本匹配器仍限定在 拥有它们的提供商范围内（例如 OpenRouter Key limit exceeded）。如果 402 消息看起来更像可重试的用量窗口或 组织/工作区支出限制（daily limit reached, resets tomorrow、 organization spending limit exceeded），OpenClaw 会将其视为 rate_limit，而不是长期计费停用。上下文溢出错误不同：诸如 request_too_large、input exceeds the maximum number of tokens、 input token count exceeds the maximum number of input tokens、 input is too long for the model，或 ollama error: context length exceeded 的特征会留在压缩/重试路径上，而不是推进模型 回退。通用服务器错误文本的匹配范围被有意收窄，而不是“任何包含 unknown/error 的内容”。OpenClaw 确实会将提供商范围内的瞬态形态， 例如 Anthropic 的裸 An unknown error occurred、OpenRouter 的裸 Provider returned error、像 Unhandled stop reason: error 这样的停止原因错误、带有瞬态服务器文本的 JSON api_error 载荷 （internal server error、unknown error, 520、upstream error、backend error），以及 ModelNotReadyException 这类提供商繁忙错误，视为 值得触发故障转移的超时/过载信号，只要提供商上下文 匹配。 像 LLM request failed with an unknown error. 这样的通用内部回退文本会保持保守，单独出现时不会触发模型回退。
这表示系统尝试使用认证配置档案 ID anthropic:default，但无法在预期的认证存储中找到它的凭证。修复检查清单：
  • 确认认证配置档案的存储位置（新路径与旧路径）
    • 当前：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • 旧版：~/.openclaw/agent/*（由 openclaw doctor 迁移）
  • 确认你的环境变量已由 Gateway 网关加载
    • 如果你在命令行环境中设置了 ANTHROPIC_API_KEY，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承该变量。请将其放入 ~/.openclaw/.env，或启用 env.shellEnv。
  • 确保你正在编辑正确的智能体
    • 多智能体设置意味着可能存在多个 auth-profiles.json 文件。
  • 对模型/认证状态做完整性检查
    • 使用 openclaw models status 查看已配置的模型以及提供商是否已认证。
“找不到配置档案 anthropic 的凭证”的修复检查清单这表示本次运行被固定到一个 Anthropic 认证配置档案，但 Gateway 网关 无法在其认证存储中找到它。
  • 使用 Claude CLI
    • 在 Gateway 网关主机上运行 openclaw models auth login --provider anthropic --method cli --set-default。
  • 如果你想改用 API 密钥
    • 将 ANTHROPIC_API_KEY 放入 Gateway 网关主机上的 ~/.openclaw/.env。
    • 清除任何会强制使用缺失配置档案的固定顺序： 
      openclaw models auth order clear --provider anthropic
  • 确认你是在 Gateway 网关主机上运行命令
    • 在远程模式下，认证配置档案位于 Gateway 网关机器上，而不是你的笔记本电脑上。
如果你的模型配置将 Google Gemini 作为回退（或你切换到了 Gemini 简写），OpenClaw 会在模型回退期间尝试它。如果你尚未配置 Google 凭证，就会看到 No API key found for provider "google"。修复：提供 Google 认证，或在 agents.defaults.model.fallbacks / 别名中移除/避免使用 Google 模型，这样回退就不会路由到那里。大语言模型请求被拒绝：需要思考签名（Google Antigravity）原因：会话历史包含没有签名的思考块（通常来自 中止/不完整的流）。Google Antigravity 要求思考块带有签名。修复：OpenClaw 现在会为 Google Antigravity Claude 去除未签名的思考块。如果它仍然出现，请启动一个新会话，或为该智能体设置 /thinking off。

​
认证配置档案：它们是什么以及如何管理

相关：/concepts/oauth（OAuth 流程、令牌存储、多账户模式）
认证配置档案是一个与提供商绑定的命名凭证记录（OAuth 或 API 密钥）。配置档案位于：
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
若要在不转储密钥的情况下检查已保存的配置档案，请运行 openclaw models auth list（可选加上 --provider <id> 或 --json）。详情请参阅 Models CLI。
OpenClaw 使用带提供商前缀的 ID，例如：
  • anthropic:default（没有电子邮件身份时常见）
  • anthropic:<email> 用于 OAuth 身份
  • 你选择的自定义 ID（例如 anthropic:work）
可以。配置支持为配置档案添加可选元数据，并支持按提供商设置顺序（auth.order.<provider>）。这不会存储密钥；它会将 ID 映射到提供商/模式，并设置轮换顺序。如果某个配置档案处于短暂的冷却状态（速率限制/超时/认证失败）或较长的停用状态（计费/额度不足），OpenClaw 可能会临时跳过它。若要检查这一点，请运行 openclaw models status --json 并查看 auth.unusableProfiles。调优项：auth.cooldowns.billingBackoffHours*。速率限制冷却可以按模型划分范围。某个配置档案如果正在针对一个模型冷却， 仍可用于同一提供商下的同级模型， 而计费/停用窗口仍会阻止整个配置档案。你还可以通过 CLI 设置按智能体的顺序覆盖（存储在该智能体的 auth-state.json 中）：
# Defaults to the configured default agent (omit --agent)
openclaw models auth order get --provider anthropic

# Lock rotation to a single profile (only try this one)
openclaw models auth order set --provider anthropic anthropic:default

# Or set an explicit order (fallback within provider)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# Clear override (fall back to config auth.order / round-robin)
openclaw models auth order clear --provider anthropic
若要指定某个智能体：
openclaw models auth order set --provider anthropic --agent main anthropic:default
若要验证实际会尝试哪些配置，请使用：
openclaw models status --probe
如果某个已存储的配置档案未包含在显式顺序中，探测会为该配置档案报告 excluded_by_auth_order，而不是静默尝试它。
OpenClaw 两者都支持：
  • OAuth 通常会利用订阅访问权限（如适用）。
  • API 密钥使用按令牌计费。
该向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API 密钥。

​
相关内容