Codex Usage

核心用法

codex-usage 是一款面向 Codex CLI 用户的本地诊断技能，通过解析 ~/.openclaw/agents/main/agent/auth-profiles.json 中的 OAuth 凭据，主动探测 OpenAI Codex 使用端点（chatgpt.com/backend-api/wham/usage），返回多维度的配额与授权健康报告。

典型触发指令：

• /codex_usage — 弹出交互式选择器（default / all / 已发现档案）
• /codex_usage all — 批量扫描所有本地档案
• /codex_usage <profile> — 单档案深度检测
• /codex_usage delete <profile> — 安全删除/隔离档案（需二次确认）

输出维度：

• 本地档案健康：Token 过期时间、最后使用、错误/限流计数器
• 远程配额窗口：5 小时滑动窗口剩余额度、周度限额
• 用户友好格式：本地时区的重置时间、剩余天数/小时/分钟
• 诊断元数据：请求耗时、重试次数、HTTP 状态码

显著优点

1. 零远程代码执行：禁止 curl|bash、wget|sh，无 SSH 或 sudo 操作，安全边界清晰。
2. 只读优先：默认 /codex_usage 为纯查询；任何变更操作（如 --delete-profile）强制要求 --confirm-delete，并优先 --dry-run 预览。
3. 容错设计：端点不可达时降级为本地健康报告；401 错误明确标识为「端点拒绝 OAuth 格式」，避免误报为 CLI 未安装。
4. 跨通道 UX：支持内联按钮交互与纯文本菜单降级，20 秒去重抑制防止误触刷屏。
5. 隐私保护：完整 Token 永不打印，仅用于 HTTPS 请求头注入。

潜在缺点与局限性

• 本地档案依赖：无法检测云端未同步的授权变更；若用户从未运行过 Codex CLI，本地无档案则无法生成报告。
• 端点白名单限制：仅允许 chatgpt.com HTTPS 流量，企业代理或自定义端点需额外配置。
• OAuth 格式敏感：Codex 后端偶尔变更 Token 格式，可能导致 401 误判（非技能缺陷，需等待上游同步）。
• 删除操作的不可逆性：--hard-delete 会永久移除档案与用量记录，虽自动备份但仍建议用户手动二次核对。

适合人群

• 高频 Codex CLI 用户：需实时监控 5 小时滑动窗口，避免突然限流中断工作流。
• 多账号开发者：管理多个 openai-codex:<suffix> 档案，批量对比配额消耗。
• 运维/团队管理员：审计团队成员授权健康，及时发现过期或异常档案。
• 安全意识强的用户：偏好本地脚本而非第三方在线工具处理敏感 Token。

常规风险

| 风险场景 | 发生概率 | 缓解措施 |

|---------|---------|---------|

| 端点 401 误报 | 中 | 技能自动降级本地报告，提示「端点拒绝格式」而非崩溃 |

| 误触删除档案 | 低 | 强制 `--confirm-delete` + `--dry-run` 预览 + 自动备份 |

| Token 泄露（日志/截图） | 低 | 输出规则明确：Never print full tokens |

| 网络超时（25s+） | 低 | 1 次重试 + 超时后返回本地健康数据，不阻塞 |

| 20 秒内重复请求 | 中 | 用户级去重抑制，避免 API 滥刷 |

安全等级说明：来源为本地可信脚本（scripts/codex_usage.py），无外部下载执行，网络仅限于 HTTPS 白名单，符合 S+ 级安全模型。