FAQ：模型与认证

模型选择、切换、别名、故障转移和认证配置的常见问题。

模型配置

默认模型 由 agents.defaults.model.primary 设置，格式为 provider/model（如 openai/gpt-5.5）。

内置快捷别名：

别名	对应模型
opus	anthropic/claude-opus-4-7
sonnet	anthropic/claude-sonnet-4-6
gpt	openai/gpt-5.4
gpt-mini	openai/gpt-5.4-mini
gemini	google/gemini-3.1-pro-preview
gemini-flash	google/gemini-3-flash-preview

切换模型（不重启）：

/model sonnet
/model opus
/model gpt
/model 3          # 按编号选择
/model opus@anthropic:work  # 指定认证 profile

安全切换方式（不覆盖配置）：

openclaw models set ...
openclaw configure --section model
# 或直接编辑 agents.defaults.model

自定义别名：

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
      },
    },
  },
}

本地模型（Ollama）

# 1. 安装 Ollama
# 2. 拉取模型
ollama pull gemma4
# 3. Onboarding 时选择 Ollama
openclaw onboard  # 选择 Ollama

安全警告： 小型/过度量化的模型更容易受到提示注入攻击，工具使用场景强烈推荐大型模型。

模型故障转移

故障转移分两阶段：

1. 认证 profile 轮换（同一 Provider 内）
2. 模型回退（到 agents.defaults.model.fallbacks 中的下一个模型）

触发故障转移的情况：

• HTTP 429（速率限制）
• Too many concurrent requests
• resource exhausted
• 各类服务器错误

不触发故障转移：上下文溢出错误（走压缩/重试路径）。

认证 Profile 管理

Profile 存储位置：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

openclaw models auth list                    # 查看已保存的 profile
openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic
openclaw models status --probe               # 验证实际会尝试哪些 profile

常见错误： No credentials found for profile anthropic:default

• 检查 auth-profiles.json 路径（新路径 vs 旧路径）
• 确认 Gateway 进程能加载到 ANTHROPIC_API_KEY（systemd/launchd 不继承 shell 变量）
• 使用 openclaw models auth login --provider anthropic --method cli --set-default

GPT-5.5 Fast Mode

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { fastMode: true },
        },
      },
    },
  },
}

或 session 内：/fast on

相关链接

• help-faq-first-run — 首次运行 FAQ
• help-troubleshooting — 故障排查