Codex 认证回退机制

为 OpenClaw 配置的多提供商认证方案，支持 Anthropic 与多个 OpenAI Codex OAuth 会话之间的自动故障转移。

概述

OpenClaw 支持为每个提供商配置多个认证配置文件（auth profile）。当某一配置文件触发速率限制时，平台可自动切换至其他可用配置文件。本技能涵盖以下内容：

1. 通过设备流（device-flow）登录方式添加 Codex OAuth 配置文件
2. 配置 openclaw.json，指定各提供商的回退优先级顺序
3. 在 auth-profiles.json 中配置多个配置文件
4. 部署定时任务（cron job），在模型进入冷却期时自动切换模型

前置条件

• 已运行 OpenClaw 实例
• 已安装 codex CLI 工具（执行 npm i -g @openai/codex 安装；该操作同时确保系统中已安装 node）
• 拥有一个或多个具备 Codex 访问权限的 OpenAI 账户

安全与可靠性

本技能所访问的文件：

重要安全说明：

• 令牌始终保留在本地。 所有令牌均不会发送至任何外部端点。脚本仅从本地 Codex CLI 的认证文件中读取令牌，并将其写入本地 OpenClaw 的 auth-profiles.json 文件。
• 始终创建备份。 对上述两个文件的任何修改前，均会生成带时间戳的备份。若登录失败或脚本执行被中断，内置的 trap 处理器将自动还原原始的 Codex CLI 认证文件。
• 交互式确认。 脚本在清空 Codex CLI 认证文件前会提示用户确认，必要时可中止操作。
• 无需提权运行。 脚本以当前用户身份运行，不依赖 sudo 或其他特殊权限。
• 建议手动预先备份。 尽管脚本自带自动备份功能，首次使用前仍强烈建议手动备份 ~/.codex/auth.json 及 OpenClaw 的全部配置文件。
• 请使用非生产环境账户进行测试。 初次测试时，建议使用临时账户或非生产环境的 OpenAI 账户。

步骤 1：添加 Codex OAuth 配置文件

对每个 OpenAI 账户分别运行封装好的脚本：

./scripts/codex-add-profile.sh 

该脚本执行以下操作：

1. 备份 ~/.codex/auth.json 和 auth-profiles.json
2. 清空 Codex CLI 认证信息，以强制触发新的设备流登录流程
3. 执行 codex auth login（自动打开浏览器完成 OAuth 授权）
4. 提取获取到的令牌，并将其导入 OpenClaw 的 auth-profiles.json
5. 还原原始的 Codex CLI 认证文件

对每个账户重复执行该命令。配置文件名称应为简短标识符（例如：OpenAI 用户名）。

步骤 2：配置 openclaw.json

在 openclaw.json 中添加认证配置文件声明及回退模型配置。具体需添加的 JSON 片段，请参阅 references/config-templates.md。

关键配置项如下：

• auth.profiles —— 声明每个配置文件的提供商（provider）和认证模式（mode）
• auth.order —— 设置各提供商内部配置文件的故障转移优先级
• agents.defaults.model —— 设置主用模型及备用模型列表

步骤 3：认证配置文件 JSON 结构

OpenClaw 将活跃令牌存储于 agents/main/agent/auth-profiles.json 中。其数据结构定义请参阅 references/config-templates.md。

每个 Codex 配置文件包含以下字段：

• type: "oauth"
• provider: "openai-codex"
• access: JWT access token（由 add-profile 脚本自动填充）
• refresh: refresh token（由 add-profile 脚本自动填充）
• expires: 令牌过期时间（毫秒级时间戳，从 JWT 中解析得出）
• accountId: OpenAI 账户 ID（从 JWT 中解析得出）

order 对象用于控制各提供商下优先尝试的配置文件顺序。usageStats 对象则自动跟踪速率限制状态与冷却期信息。

步骤 4：模型冷却期自动切换定时任务（可选）

本步骤完全可选。 步骤 1–3 所配置的认证配置文件本身即可与 OpenClaw 内置的故障转移机制协同工作。本定时任务进一步引入了模型的自动切换能力，即活动模型可能在无人工干预的情况下发生变化。仅当您明确理解并希望启用该行为时，才应启用此功能。

部署一个每 10 分钟检查一次冷却状态并自动切换活动模型的定时任务。完整的定时任务定义请参阅 references/config-templates.md。

该定时任务执行以下操作：

1. 运行 openclaw models status 检查当前模型冷却状态
2. 按优先级顺序选取最佳可用模型（优先级：opus > codex 配置文件顺序）
3. 如需切换，则更新会话级模型覆盖设置（session model override）
4. 将状态记录至本地内存文件；仅在状态发生变更时输出日志

启用前须知：

• 请先手动测试：运行 openclaw models status 验证您的配置文件是否正常工作
• 请审阅 references/config-templates.md 中的定时任务模板——该任务仅执行本地命令，并仅向本地状态文件写入数据
• 该任务在隔离会话中运行，除非实际发生模型切换，否则不会影响您的主会话聊天体验

请使用参考文档中提供的模板，将该任务添加至 cron/jobs.json。

文件结构

codex-auth-fallback/
├── SKILL.md                    # 当前文档
├── scripts/
│   └── codex-add-profile.sh    # 设备流配置文件导入脚本
└── references/
    └── config-templates.md     # openclaw.json、auth-profiles、cron 配置模板