第四章：配置体系、模型接入与认证管理

OpenClaw 的配置决定 Gateway 如何启动、连接哪些通道、使用哪些模型、开放哪些工具以及如何暴露网络。默认配置文件是 ~/.openclaw/openclaw.json，格式为 JSON5。

4.1 修改配置的方式

推荐优先使用交互式或 schema 感知方式：

openclaw onboard
openclaw configure
openclaw dashboard

精确修改可用 CLI：

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset channels.telegram.botToken

直接编辑 JSON5 时要先备份，因为 OpenClaw 对配置做严格 schema 校验。

4.2 严格校验

未知字段、类型错误、非法枚举或插件配置错误都可能导致 Gateway 拒绝启动。排查：

openclaw config schema
openclaw doctor

Control UI 的 Config 页面会使用 live schema 渲染字段说明，是新手修改配置的好入口。

4.3 最小配置

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

Telegram 示例：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
    },
  },
}

4.4 模型引用

模型通常写成 provider/model，例如 anthropic/claude-sonnet-4-6、openai/gpt-5.4、openrouter/moonshotai/kimi-k2、ollama/gemma4:26b。OpenClaw 按第一个 / 分割 provider 和 model，因此 OpenRouter 这类模型 ID 中含 / 时必须保留 provider 前缀。

4.5 主模型与 fallback

模型选择顺序：主模型、fallback 列表、provider 内部认证 profile failover。示例：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}

agents.defaults.models 既是目录也可能是 allowlist。若用户在 /model 中选择不在 allowlist 的模型，OpenClaw 会拒绝。

4.6 模型命令

openclaw models status
openclaw models list
openclaw models list --all
openclaw models set anthropic/claude-sonnet-4-6
openclaw models fallbacks add openai/gpt-5.4
openclaw models aliases add sonnet anthropic/claude-sonnet-4-6

聊天中切换：

/model
/model list
/model openai/gpt-5.4
/model status

用户选择的会话模型通常是严格选择，失败时不会悄悄降级到其他模型；配置级主模型则可使用 fallback。

4.7 认证管理

认证方式包括 API Key、OAuth/订阅、CLI 复用、环境变量、SecretRef、文件或 exec。长期运行的 Gateway 通常使用稳定 API Key 或明确 OAuth profile。不要把 key 写入 AGENTS.md、SOUL.md、技能说明或公开仓库。

4.8 本地模型与 Docker

Docker 内的 127.0.0.1 是容器本身，不是宿主机。访问宿主机 Ollama/LM Studio 常用：

宿主机服务也要监听可被容器访问的地址。

4.9 小结

配置、模型和认证是 OpenClaw 稳定性的基础。掌握 schema、doctor、models status、fallback 和 secret 管理，能避免大部分入门故障。