Skip to content
BranchesTags

Repository files navigation

OpenClaw Codex 容灾机制（小白友好最终版）

Last updated: 2026-03-07

停止更新维护公告

本项目即日起停止继续更新维护。

原因很直接：在后续实际使用和对比中，我发现 CLIProxyAPI 的整体体验、可用性和后续扩展性更好，因此后续精力将转向新的方案，这个仓库不再作为主要维护方向继续推进。

这意味着：

  • 现有代码和文档会继续保留，方便有需要的人参考
  • 仓库暂时不会删除
  • 除非出现特别必要的问题，否则不会继续加入新功能或长期维护
  • 如果你正在找更适合继续投入的方向，建议优先关注 CLIProxyAPI

感谢大家这段时间的支持

感谢这段时间所有正在玩 OpenClaw、测试这个项目、给出反馈、帮忙发现问题的朋友。

不管你是：

  • 真正在跑项目的人
  • 帮忙提建议的人
  • 反馈 bug 和使用体验的人
  • 单纯围观、关注和支持的人

都非常感谢。

正是这些真实使用中的反馈，才让我更快看清楚这个方向哪些地方有价值，哪些地方应该及时止损、尽快切换到更合适的方案。

这个仓库到这里先告一段落。
谢谢大家这些日子的支持。

当前状态：停止更新维护（代码保留，仅供参考）

原目标：openai-codex:* 账号池自动巡检、异常告警、自动/手动修复、可选删除、快速补位。

隐私原则：脚本不上传 token，不上传账号凭据；日志默认仅保留本机。

一句话流程

检测 → 分级 → 熔断 → 修复 →（可选）删除 → 补位 → 恢复

最新增量（2026-03-05）

  • ✅ 修复“写入后被回收”：auth-profiles.json 写入链路补齐文件锁 + 原子写（tmp+rename）
  • ✅ 新增反回滚守护：openclaw-profile-reconcile.timer 每 2 分钟回灌缺失 profile（from openai-codex-auth-map.env）
  • ✅ 新增独立凭据快照：每个 profile 使用独立 auth.json 路径，避免共享凭据被覆盖串号
  • ✅ 修复过期判定链路：remainingMs 保留负值，失效账号可正确进入 failed/隔离流程
  • ✅ 增加可回归验证：新增 quota 注入自测脚本，验证“限额后自动切号”是否在时限内生效

这次是“持久化不回滚 + 自动回灌 + 可验证切换”的永久修复包。

60 秒 Demo（已提供录屏）

已生成终端录屏：docs/demo/quick-validation.cast

GIF 预览：

Quick validation demo

本地回放：

asciinema play docs/demo/quick-validation.cast

重新录制：

TERM=xterm-256color asciinema rec -y -q -c "bash scripts/demo_terminal_walkthrough.sh" docs/demo/quick-validation.cast

重新生成 GIF：

agg docs/demo/quick-validation.cast docs/demo/demo.gif

对外分享前，先按下文“隐私发布检查清单”打码。

你能得到什么

  • ✅ 账号池自动检测（默认每10分钟）
  • ✅ 状态机：Healthy / Degraded / Repairing / Recovered
  • ✅ 异常分类：auth / network / provider / unknown
  • ✅ 熔断器：连续失败账号自动 cooldown
  • ✅ 修复节流：最短间隔限制，避免死循环
  • ✅ 双探针：ok + pong，降低假健康
  • ✅ 告警策略：首次3连发 + 每小时提醒 + 去重窗口
  • ✅ 精准定位失效账号（accXX）
  • ✅ 修复脚本（自动尝试 + 手动命令）
  • ✅ 删除脚本（封禁账号下线，可选）
  • ✅ 补位脚本（新账号快速补回 accXX）
  • ✅ SLO指标文件 + 配置快照历史

已验证环境

  • Ubuntu 22.04 LTS
  • OpenClaw 2026.3.2
  • Node.js 22.x
  • Codex CLI 0.104.0

路径选择（必须先看）

# 推荐（有 /data）
export OCX_BASE_DIR=/data/openclaw

# 或默认兼容
# export OCX_BASE_DIR=$HOME/.openclaw/openclaw-tools

登录机制说明（避免误解）

  • 当前方案采用 Bridge 模式：codex login --device-auth + import_codex_auth_to_openclaw.sh 导入到 OpenClaw。
  • 这不是 OpenClaw 原生命令直接完成 device code 登录，而是容灾仓库提供的可复用接入流程。
  • 因此文档中所有 device code 示例，均基于 Codex CLI 登录后再导入。

前置依赖（先确认）

# 1) OpenClaw 已安装
openclaw --version

# 2) Codex CLI 已安装（device code 登录要用）
# npm install -g @openai/codex
codex --version

说明：onboard/repair/healthcheck 依赖 scripts/import_codex_auth_to_openclaw.sh，本仓库已内置。

预检（推荐先跑）

${OCX_BASE_DIR:-/data/openclaw}/scripts/preflight_openai_codex_failover.sh

健康报告新鲜度看门狗（解决“面板显示旧报告/停更”）：

${OCX_BASE_DIR:-/data/openclaw}/scripts/watch_openai_codex_health_freshness.sh
# 可选：最大允许陈旧秒数（默认 1800）
# OCX_MAX_STALE_SECONDS=900 ${OCX_BASE_DIR:-/data/openclaw}/scripts/watch_openai_codex_health_freshness.sh

公开仓库的 3 个安全增强（已内置）

  1. SECURITY.md / SECURITY.zh-CN.md：安全边界与泄露应急流程（中英）
  2. scripts/bootstrap.sh：一键初始化（目录/脚本/systemd/模板）
  3. config/public-safe.env.example / config/public-safe.env.example.zh-CN：公开安全模板（中英、无真实密钥）

快速启动（推荐）：

cd openclaw-codex-failover
# 中文模板可选：export OCX_BOOTSTRAP_LANG=zh-CN
bash scripts/bootstrap.sh

一键安装 + 一键验收（复制即用）

export OCX_BASE_DIR=/data/openclaw

sudo bash -lc '
set -e
: "${OCX_BASE_DIR:=/data/openclaw}"
mkdir -p "$OCX_BASE_DIR/scripts" "$OCX_BASE_DIR/reports" "$OCX_BASE_DIR/systemd" "$OCX_BASE_DIR/config"
cp scripts/*.sh "$OCX_BASE_DIR/scripts/"
cp systemd/* "$OCX_BASE_DIR/systemd/"
cp -n config/openai-codex-auth-map.env.example "$OCX_BASE_DIR/config/openai-codex-auth-map.env" || true
chmod +x "$OCX_BASE_DIR/scripts"/*.sh
cp "$OCX_BASE_DIR/systemd/openclaw-healthcheck.service" /etc/systemd/system/
cp "$OCX_BASE_DIR/systemd/openclaw-healthcheck.timer" /etc/systemd/system/
cp -n openclaw-healthcheck.env.example /etc/openclaw-healthcheck.env || true
systemctl daemon-reload
systemctl enable --now openclaw-healthcheck.timer
systemctl start openclaw-healthcheck.service || true
$OCX_BASE_DIR/scripts/preflight_openai_codex_failover.sh
cat $OCX_BASE_DIR/reports/openai_codex_health_latest.json
'

小白推荐入口（先用这个）

${OCX_BASE_DIR:-/data/openclaw}/scripts/onboard_profiles_wizard.sh

向导支持：单个导入、批量导入、每次询问是否使用代理、代理检测与导入联动。

最小可跑（3步）

1) 一键安装

sudo bash -lc '
set -e
: "${OCX_BASE_DIR:=/data/openclaw}"
mkdir -p "$OCX_BASE_DIR/scripts" "$OCX_BASE_DIR/reports" "$OCX_BASE_DIR/systemd"
cp scripts/*.sh "$OCX_BASE_DIR/scripts/"
cp systemd/* "$OCX_BASE_DIR/systemd/"
chmod +x "$OCX_BASE_DIR/scripts"/*.sh
cp "$OCX_BASE_DIR/systemd/openclaw-healthcheck.service" /etc/systemd/system/
cp "$OCX_BASE_DIR/systemd/openclaw-healthcheck.timer" /etc/systemd/system/
cp -n openclaw-healthcheck.env.example /etc/openclaw-healthcheck.env || true
systemctl daemon-reload
systemctl enable --now openclaw-healthcheck.timer
'

2) 手动跑一次

sudo systemctl start openclaw-healthcheck.service

3) 看结果

cat ${OCX_BASE_DIR:-/data/openclaw}/reports/openai_codex_health_latest.json

异常处理（实战）

A) 手动修复（推荐先做）

${OCX_BASE_DIR:-/data/openclaw}/scripts/repair_openai_codex_pool.sh

B) 封禁账号删除（可选）

${OCX_BASE_DIR:-/data/openclaw}/scripts/decommission_openai_codex_profile.sh openai-codex:acc03 banned

C) 新账号补位

codex logout && codex -c cli_auth_credentials_store='file' login --device-auth
${OCX_BASE_DIR:-/data/openclaw}/scripts/onboard_openai_codex_profile.sh openai-codex:acc03 /root/.codex/auth.json

代理格式说明（统一）

支持以下三种格式：

  1. host:port:username:password
  2. socks5h://user:pass@host:port（推荐 socks5h）
  3. http://user:pass@host:port（你当前默认方案）

如果使用第 1 种，会按 OCX_PROXY_DEFAULT_SCHEME 自动补全协议。

配置总表（OCX_*）

变量 默认值 作用
OCX_BASE_DIR /data/openclaw 工作根目录
OCX_PROVIDER openai-codex Provider 名称
OCX_MIN_PROFILES 1 最低账号数（低于则 CRITICAL）
OCX_RECOMMENDED_MIN 1 建议最小账号数（生产建议 >=4）
OCX_RECOMMENDED_MAX 12 建议最大账号数
OCX_EXPIRING_HOURS 24 即将过期阈值
OCX_NOTIFY_CHANNEL telegram 告警渠道
OCX_NOTIFY_TARGET 182211955 告警目标
OCX_ALERT_BURST_COUNT 3 首次异常告警次数
OCX_ALERT_REMIND_SECONDS 3600 持续异常提醒间隔
OCX_ALERT_DEDUP_SECONDS 900 同类告警去重窗口
OCX_CB_FAIL_THRESHOLD 3 熔断触发失败次数
OCX_CB_COOLDOWN_SECONDS 3600 熔断冷却时长
OCX_AUTO_REORDER 0 1=按健康分自动重排账号顺序
OCX_AUTO_REORDER_ACCOUNT_DIVERSITY 1 1=按 accountId 交错重排，减少同账号连续命中
OCX_PROBE_HINT_DEMOTE_WITHOUT_AUTO_REORDER 1 1=即使 AUTO_REORDER=0，探针命中 auth/quota/`connected
OCX_PROBE_HINT_FORCE_TRIP 1 1=探针强信号直接触发熔断（不等累计到阈值）
OCX_PROBE_HINT_MIN_COOLDOWN_SECONDS 1800 探针推断熔断最短冷却时长
OCX_PROBE_HINT_MAX_COOLDOWN_SECONDS 259200 探针推断熔断最长冷却时长（支持从 Try again in ~NNN min 推导）
OCX_HARD_DISABLE_FAILED 1 1=硬隔离失败账号，仅 active 池参与轮换
OCX_HARD_DISABLE_FAILED_ACCOUNT 1 1=按 accountId 联动隔离同账号 profiles
OCX_ACCOUNT_QUARANTINE_SECONDS 7200 同账号联动隔离时长（秒）
OCX_RECOVERY_SUCCESS_ROUNDS 2 恢复门槛：连续 N 轮健康才放回 active 池
OCX_HARD_DISABLE_MIN_ACTIVE_PROFILES 2 active profiles 低于阈值时自动 fail-open
OCX_HARD_DISABLE_MIN_ACTIVE_ACCOUNTS 1 active account 数低于阈值时自动 fail-open
OCX_AGENT_TIMEOUT_SECONDS 45 轻量调用超时
OCX_CODEX_AUTH_PATH /root/.codex/auth.json Codex 登录凭证路径（按运行用户调整）
OCX_AUTH_PROFILES_PATH /root/.openclaw/agents/main/agent/auth-profiles.json accountId 回填来源（models status 不含 accountId 时使用）
OCX_AUTH_SNAPSHOT_DIR /data/openclaw/auth/openai-codex 每个 profile 独立 auth 快照目录
OCX_AUTH_SNAPSHOT_PERSIST 1 1=onboard 后把凭据落到 profile 独立路径
OCX_RECONCILE_MODE missing-only profile 反回滚模式（缺失即补）
OCX_RECONCILE_LOCK_FILE /data/openclaw/run/openai_codex_reconcile.lock reconcile 互斥锁文件
OCX_LOG_RETENTION_DAYS 30 日志保留天数
OCX_DRY_RUN 0 1=只检查不发消息
OCX_AUTO_REPAIR 0 1=异常时自动触发修复
OCX_REPAIR_MIN_INTERVAL_SECONDS 1800 自动修复最短间隔
OCX_SUGGEST_DECOMMISSION 0 1=在修复建议中显示删除命令
OCX_USE_PROXY_LOGIN 1 1=使用代理登录, 0=直连登录
OCX_PROXY_AUTO_FALLBACK 1 1=主代理失败时尝试备用代理池
OCX_PROXY_FALLBACK_MAX_ATTEMPTS 6 fallback 最大尝试次数
OCX_PROXY_FALLBACK_BACKOFF_SECONDS 2 fallback 退避基数（第 N 次 sleep=N×基数）
OCX_PROXY_FALLBACK_PERSIST_MAP 1 fallback 成功后是否回写账号映射
OCX_PROXY_DEFAULT_SCHEME socks5h/http host:port:user:pass 这种格式自动补全的协议
OCX_PROXY_QUARANTINE_FILE /data/openclaw/run/proxy-quarantine.tsv 代理隔离池文件
OCX_PROXY_QUARANTINE_SECONDS 1800 默认隔离时长（秒）
OCX_PROXY_QUARANTINE_SECONDS_STRICT 3600 严格失败类型隔离时长（如 custom_check_rejected）
OCX_PROXY_QUARANTINE_SECONDS_SOFT 900 软失败类型隔离时长（如 egress_ip_missing）
OCX_PROXY_CHECK_CACHE_TTL_SECONDS 600 代理 clean 检测缓存 TTL（秒）
OCX_PROXY_CHECK_CONCURRENCY 5 批量代理检测并发度
OCX_PROXY_CHECK_METRICS_FILE /data/openclaw/reports/proxy-check-metrics.jsonl 代理检测结果落盘文件
OCX_ACCOUNT_PROXY_AUDIT_FILE /data/openclaw/reports/account-proxy-audit.jsonl 账号↔代理绑定审计日志文件

常用命令

# 反回滚守护：手动补齐缺失 profile
${OCX_BASE_DIR:-/data/openclaw}/scripts/reconcile_openai_codex_profiles_from_map.sh

# 一次性将当前 auth store 固化成“每 profile 独立凭据快照”
${OCX_BASE_DIR:-/data/openclaw}/scripts/materialize_openai_codex_auth_snapshots.sh

# 限额切号自测（默认 shadow 模式，不污染线上状态）
${OCX_BASE_DIR:-/data/openclaw}/scripts/selftest_quota_failover_switch.sh --mode shadow --timeout 30 --interval 2

# 仅检查不发通知
${OCX_BASE_DIR:-/data/openclaw}/scripts/healthcheck_openai_codex_pool.sh --dry-run

# 无破坏模拟掉线
SIMULATE_UNUSABLE=openai-codex:acc03 ${OCX_BASE_DIR:-/data/openclaw}/scripts/healthcheck_openai_codex_pool.sh || true

# 查看 timer
systemctl status openclaw-healthcheck.timer --no-pager -l | sed -n '1,20p'

# 查看账号↔代理审计日志
 tail -n 30 /data/openclaw/reports/account-proxy-audit.jsonl

# 最近24h按profile成功率+失败TopN
/data/openclaw/scripts/report_account_proxy_audit_24h.sh 24 5

审计与追踪（新增）

  • 绑定审计脚本：scripts/audit_account_proxy_binding.sh
  • 24h 汇总脚本：scripts/report_account_proxy_audit_24h.sh
  • 默认审计日志文件：/data/openclaw/reports/account-proxy-audit.jsonl

建议每次批量导入后跑一次 24h 汇总，快速定位失败账号与失败原因 TopN。

常见报错与排查

1) auth.json missing required access/refresh token fields

  • 原因：导入脚本读取到不兼容的 auth.json 结构（旧版脚本常见）。
  • 处理：更新到本仓库当前版本脚本；并确认 auth 文件路径正确。

2) custom clean check rejected ...

  • 原因：代理 IP 被你的 clean 策略拒绝（风控分数、年龄、代理属性等）。
  • 这通常是策略拦截，不是脚本损坏。
  • 处理：换下一条代理，或调整 clean check 阈值。

兼容性说明（重要）

  • systemd/openclaw-healthcheck.service 默认是 User=rdpuser，请按你的机器改（例如 root）。
  • 默认 auth 路径推荐：/root/.codex/auth.json。如使用其他用户，请在命令里传入实际路径。
  • 若你只配置了 1 个账号池，建议将 /etc/openclaw-healthcheck.env 中 OCX_RECOMMENDED_MIN=1，避免新装阶段误报。

隐私发布检查清单（必须）

  • 截图/录屏前，隐藏 Telegram chat id、邮箱、主机名、IP。
  • 不要提交 /etc/openclaw-healthcheck.env、auth.json、任何 token 文件。
  • 粘贴日志时先脱敏：账号只保留 accXX，不带邮箱。
  • 不公开 OCX_NOTIFY_TARGET 的真实个人账号，可替换为 YOUR_TARGET_ID。

智能熔断 v2（2026-02-22 更新）

新增能力：

  • 按失败类型分级熔断：auth / network / other
  • 半开探测：冷却尾段提前探测恢复
  • default 账号独立阈值/冷却
  • 冷却抖动：错峰解冻，避免同秒重试风暴
  • 失败计数衰减：降低短时抖动长期影响

推荐新增配置（/etc/openclaw-healthcheck.env）：

OCX_CB_FAIL_THRESHOLD_AUTH=3
OCX_CB_FAIL_THRESHOLD_NETWORK=5
OCX_CB_FAIL_THRESHOLD_OTHER=5
OCX_CB_COOLDOWN_SECONDS_AUTH=3600
OCX_CB_COOLDOWN_SECONDS_NETWORK=600
OCX_CB_COOLDOWN_SECONDS_OTHER=900
OCX_CB_HALF_OPEN_WINDOW_SECONDS=300
OCX_CB_FAIL_THRESHOLD_DEFAULT=4
OCX_CB_COOLDOWN_SECONDS_DEFAULT=1800
OCX_CB_COOLDOWN_JITTER_MIN_SECONDS=30
OCX_CB_COOLDOWN_JITTER_MAX_SECONDS=120
OCX_CB_FAILCOUNT_DECAY_ENABLED=1
OCX_CB_FAILCOUNT_DECAY_INTERVAL_SECONDS=1800

如果你看到大量 cooldown active 告警，先确认是否为短时网络抖动；v2 已内置降噪与恢复优化。

相关文档

  • 快速开始：docs/quickstart-zh.md
  • 故障排查：docs/troubleshooting-zh.md
  • 变更记录：CHANGELOG.md
  • Release Notes (EN, latest): docs/release-notes-2026-03-05.md
  • 发布说明（中文，最新）: docs/release-notes-2026-03-05.zh-CN.md
  • 先前发布说明：docs/release-notes-2026-03-04.md / docs/release-notes-2026-03-04.zh-CN.md
  • 历史发布说明：docs/release-notes-2026-03-03.md / docs/release-notes-2026-03-03.zh-CN.md

License

MIT

About

No description, website, or topics provided.

Resources

Readme

Security policy

Security policy
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages