Codex Multi Subscription Auth Fallbacks

Codex Auth 回退机制

面向 OpenClaw 的多提供方认证配置，支持 Anthropic 与多个 OpenAI Codex OAuth 会话之间的自动故障转移（failover）。

概述

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

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

前置条件

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

安全性与安全性说明

本技能所访问的文件：

重要安全提示：

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

步骤 1：添加 Codex OAuth Profile

对每个 OpenAI 账户运行配套脚本：

./scripts/codex-add-profile.sh

该脚本执行以下操作：

1. 备份 ~/.codex/auth.json 和 auth-profiles.json
2. 清空 Codex CLI 的 auth 状态，以强制触发全新的设备流登录
3. 运行 codex auth login（自动打开浏览器完成 OAuth 授权）
4. 提取生成的 token，并将其导入 OpenClaw 的 auth-profiles.json
5. 恢复原始的 Codex CLI auth 状态

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

步骤 2：配置 openclaw.json

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

关键配置项包括：

• auth.profiles —— 为每个 profile 声明其提供方（provider）与认证模式（mode）
• auth.order —— 设置各提供方下 profile 的故障转移优先级顺序
• agents.defaults.model —— 设置默认模型及其回退链（fallbacks）

步骤 3：Auth Profiles JSON 结构说明

OpenClaw 将有效 token 存储于 agents/main/agent/auth-profiles.json。完整结构定义请参阅 references/config-templates.md。

每个 Codex profile 包含以下字段：

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

order 对象用于控制每个 provider 下各 profile 的尝试优先级。usageStats 对象则由系统自动维护，用于追踪速率限制状态与冷却期。

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

此步骤完全可选。 仅通过步骤 1–3 配置的 auth profile 即可配合 OpenClaw 内置的故障转移机制正常工作。本定时任务额外提供模型级别的自动切换能力，即：当前活跃模型可能在无人工干预的情况下发生变更。仅当您明确理解并需要该行为时，才应启用此项。

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

该 cron 任务执行以下操作：

1. 运行 openclaw models status 查询当前模型冷却状态
2. 依据优先级选取最优可用模型（优先级顺序：opus > 按 auth.order 顺序排列的 codex profile）
3. 如需切换，则更新当前会话的模型覆盖设置（session model override）
4. 将状态记录至本地内存文件；仅在模型实际变更时输出通知

启用前须知：

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

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

文件结构

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