OpenClaw OpenAI Multi Account

OpenClaw OpenAI 账户切换器

本技能专为 在 OpenClaw 内部管理多个 OpenAI OAuth 登录账户 而设计，尤其适用于 OpenClaw 自有的 openai-codex OAuth 账户（而不仅限于普通 Codex CLI 账户文件）。

该技能的功能

• 将当前 OpenClaw 的 openai-codex:default OAuth 配置文件保存为带名称的快照
• 通过执行 openclaw models auth login --provider openai-codex 添加新账户
• 切换所有 Agent 至指定名称的快照
• 显示当前激活的账户（在可获取时显示邮箱地址 / 账户 ID）
• 在配额数据可采集的前提下，显示缓存或观测到的 5 小时 和 每周 使用量
• 自动切换至仍有剩余配额的账户
• 当所有账户配额均耗尽时，自动回退至备用模型

相关文件

• 主脚本：scripts/openclaw-openai-accounts.py
• 回归测试脚本：scripts/test_openclaw_openai_accounts.py
• 状态存储路径：~/.openclaw/openai-codex-accounts/

运行打包的回归测试套件：

python3 scripts/test_openclaw_openai_accounts.py

日常本地检查命令：

/home/djy/.openclaw/workspace-taizi/bin/check-openai-multi-account

日志按时间戳写入以下路径：

• /home/djy/.openclaw/workspace-taizi/data/openai-multi-account-checks/

首次使用

列出当前快照：

python3 scripts/openclaw-openai-accounts.py list

list、add、use、auto 和 cron-check 命令均会在输出或切换前，将当前活跃的 OpenClaw 登录状态同步回已保存的账户列表中，因此任何通过 openclaw models auth login --provider openai-codex 手动执行的登录变更都会被自动识别。

同样的同步机制也确保相关 OpenClaw 认证元数据保持一致：

• 在 openclaw.json 中补全缺失的 auth.profiles 邮箱别名
• 使 auth.order.openai-codex 与已保存账户列表及当前活跃账户保持对齐
• 在每个 Agent 的 auth-profiles.json 中添加或移除匹配的命名邮箱配置文件
• 清理不再对应任何已保存账户的陈旧别名

通过 Codex CLI 探测真实配额并在列表中展示：

python3 scripts/openclaw-openai-accounts.py list --verbose --probe

添加账户（交互式 OAuth 登录）：

python3 scripts/openclaw-openai-accounts.py add --name work

切换账户：

python3 scripts/openclaw-openai-accounts.py use work

自动选择最优账户，或触发回退：

python3 scripts/openclaw-openai-accounts.py auto

面向 cron/systemd 的自动检查模式（单行、通知友好型输出）：

python3 scripts/openclaw-openai-accounts.py cron-check

重要行为说明

1. 权威认证源

本技能以 OpenClaw Agent 的认证文件为唯一可信来源：

• ~/.openclaw/agents//agent/auth-profiles.json

它会更新 所有已配置的 Agent，确保其 openai-codex:default 配置始终对齐。

2. 配额采集机制

配额采集支持两种模式：

• 首选模式：若存在匹配的 Codex CLI 账户快照且系统已安装 codex 命令，则采集真实的 5 小时 / 每周速率限制数据
• 备用模式：若无匹配的 Codex CLI 快照，则仅保留本地观测值，并报告“配额未知”

3. 回退模型

默认回退模型为：

• bailian/qwen3.5-plus

您还可通过环境变量覆盖默认值：

• OPENCLAW_HOME — OpenClaw 数据根目录（默认为 ~/.openclaw）
• OPENCLAW_PRIMARY_AGENT — 被视为真实活跃认证源的主 Agent（默认为 taizi）
• OPENCLAW_FALLBACK_MODEL — 所有 OpenAI 账户配额耗尽时使用的备用模型（默认为 bailian/qwen3.5-plus）

覆盖方式示例：

python3 scripts/openclaw-openai-accounts.py auto --fallback-model bailian/glm-5

4. 自动化检查

建议通过 cron/systemd/循环等方式定期运行。示例一次性命令：

python3 scripts/openclaw-openai-accounts.py auto --json

推荐检查间隔为每 10–15 分钟一次。

对于无人值守的自动切换，建议采用两级阈值策略并配合短时非活跃保护机制。当前打包脚本已支持如下参数：

python3 scripts/openclaw-openai-accounts.py auto --five-hour-switch-at 80 --five-hour-hard-switch-at 90 --weekly-switch-at 90 --weekly-hard-switch-at 95 --inactive-minutes 3
python3 scripts/openclaw-openai-accounts.py cron-check --five-hour-switch-at 80 --five-hour-hard-switch-at 90 --weekly-switch-at 90 --weekly-hard-switch-at 95 --inactive-minutes 3

含义如下：

• 当 5 小时用量达 80%（约剩 20%）时，仅当所有已配置 Agent 中无非 cron 会话在最近 3 分钟内处于活跃状态，才尝试切换
• 当 5 小时用量达 90%（约剩 10%）时，立即切换，避免触达速率限制，即使当前存在活跃会话
• 当每周用量达 90%（本周约剩 10%）时，仅当所有已配置 Agent 中无非 cron 会话在最近 3 分钟内处于活跃状态，才尝试切换
• 当每周用量达 95%（本周约剩 5%）时，立即切换，以保全剩余的周配额

推荐策略

默认采用以下策略：

• 每 10 分钟检查一次
• 当 5 小时用量达 80%：仅当所有非 cron 会话在最近 3 分钟内均未活跃时尝试切换
• 当 5 小时用量达 90%：立即切换以规避速率限制
• 当每周用量达 90%：仅当所有非 cron 会话在最近 3 分钟内均未活跃时尝试切换
• 当每周用量达 95%：立即切换以保全剩余周配额
• 若当前账户仍低于两项软性阈值，则优先维持当前账户不变
• 优先在同一模型间轮转账户（例如：openai-codex/gpt-5.4 → 另一个 openai-codex/gpt-5.4 账户）
• 仅当所有账户均已超阈值或配额未知时，才启用备用模型

脚本内置默认阈值：

• 5 小时软切换阈值：80%
• 5 小时硬切换阈值：90%
• 每周软切换阈值：90%
• 每周硬切换阈值：95%
• 非活跃保护时长：3 分钟

推荐工作流

1. 至少添加两个账户
2. 运行 list --verbose 验证各账户身份信息
3. 运行 auto 验证账户选择逻辑是否符合预期
4. 用户需要自动化时，周期性调度 auto 命令

5. 发生切换时，应上报以下信息：

   • 激活账户名称
   • 邮箱地址
   • 5 小时用量
   • 每周用量
   • 当前主模型 / 回退模型

健康状态分类

脚本现已区分以下健康状态：

• healthy：Token 有效，且成功读取了速率限制数据
• auth-invalid：Token / Refresh Token / 登录状态无效，需重新登录该账户
• plan-unavailable：Token 存在，但所属 workspace / plan / model 不可用
• quota-unknown：暂无法确定配额

这些状态将在 list --verbose 和 status 输出中体现。

重要实现说明

经审查 OpenClaw 源码（/tmp/openclaw/src/commands/models/auth.ts 与 /tmp/openclaw/src/commands/onboard-auth.credentials.ts）及线上运行时文件，内置命令 openclaw models auth login --provider openai-codex 具备如下实际语义：

1. 实际运行时凭证通过 openai-codex:default 使用
2. 切换账户会将新 Token 写入 openai-codex:default
3. 邮箱专属配置文件（如 openai-codex:user@example.com）作为命名记录予以保留
4. 各 Agent 的兄弟认证存储区会被同步更新
5. 已存在的 usageStats 与 lastGood 字段将被保留，而非清空

本技能现完全遵循上述模型：

• 实际活跃账户检测基于实时 openai-codex:default 凭证
• 快照以稳定邮箱标识为基准，而非依赖易歧义的 :default
• 切换操作会跨所有 Agent 重写 :default，同时保留或更新对应的邮箱专属配置项
• 元数据迁移机制可修复旧版快照中错误地将 :default 视作唯一账户 ID 的记录
• 邮箱是去重所依据的权威人类身份标识；accountId 可能随同一邮箱迁移到不同 workspace/team 而变化，因此相同邮箱的重新登录将更新已有保存账户，而非创建重复项

注意事项

• 本技能将敏感 OAuth Token 存储于 ~/.openclaw/openai-codex-accounts/ 下
• 请将这些文件视同密钥对待
• 在执行高风险变更前，请优先使用 list --verbose 或 status 进行确认
• 当前活跃账户的显示源自真实 OpenClaw 认证文件（~/.openclaw/agents//agent/auth-profiles.json），再同步回本技能元数据。此举可避免因手动执行 openclaw models auth login 或其他绕过本技能的认证变更导致 ACTIVE 标记陈旧
• 在周期性检查过程中，若发现当前真实 OpenClaw 认证尚未存在于账户列表中，本技能将自动将其注册为新的 accountN 快照，并标记为活跃