OpenClaw 多认证配置：OAuth、API Key 共存与自动切换

认证 Profile

OpenClaw 支持为同一个模型提供商配置多种认证方式，并按优先级自动切换。

{
  auth: {
    profiles: {
      "anthropic:me@example.com": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com"
      },
      "anthropic:work": {
        provider: "anthropic",
        mode: "api_key"
      },
      "openai:default": {
        provider: "openai",
        mode: "api_key"
      }
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
      openai: ["openai:default"]
    }
  }
}

工作原理

每个 Profile 有一个唯一 ID（如 "anthropic:me@example.com"）
mode 指定认证方式：oauth（OAuth 授权）或 api_key（API 密钥）
order 定义每个 Provider 的认证尝试顺序

当排在前面的 Profile 认证失败（如 OAuth 令牌过期且刷新失败），OpenClaw 会自动尝试下一个 Profile。

典型场景：订阅 + API Key 备用

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com"
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key"
      }
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"]
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["anthropic/claude-opus-4-6"]
      }
    }
  }
}

这个配置的含义是：

优先使用 OAuth 订阅额度
订阅额度用完后自动切换到 API Key 付费方式
主模型不可用时 fallback 到备选模型

多 Provider 认证

不同 Provider 可以使用不同的认证方式：

{
  auth: {
    profiles: {
      "anthropic:oauth": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
      "openai:key": { provider: "openai", mode: "api_key" },
      "volcengine:key": { provider: "volcengine", mode: "api_key" }
    },
    order: {
      anthropic: ["anthropic:oauth"],
      openai: ["openai:key"],
      volcengine: ["volcengine:key"]
    }
  }
}

注意事项

OAuth Profile 需要先通过 openclaw onboard 完成授权流程
API Key Profile 的密钥存储在本地凭证文件中
order 中的顺序很重要——排在前面的会优先使用