---
name: codex-usage
description: 在 Codex 内嵌插件面板查看本机任务的上下文参考、输入输出 Token、输入缓存命中率、本轮提问与累计用量，并选择 WebSocket 优先、HTTPS 或默认连接。用户要求查看 Codex 用量或打开用量插件时使用。不用于业务 Token、登录令牌或套餐重置。
---

# Codex 用量

这是带内嵌 UI 的 MCP App；用量读取只读，连接方式保存会修改用户配置。使用此插件的 `show_usage` 工具，Codex 根据工具的 UI 元数据渲染面板。不要启动 HTTP 服务、打开浏览器或用独立网页替代。

## 打开内嵌面板

1. 在当前 shell 读取 `CODEX_THREAD_ID`，为空时读取 `CODEX_SESSION_ID`。只取这两个变量，不打印完整环境。若用户指定其他任务，使用 Codex 任务列表确认其 ID。
2. 查找本插件 MCP 服务的 `show_usage` 工具，以 `{"thread_id":"实际任务 ID"}` 调用。插件命名空间可能由客户端添加，通过工具发现确定完整名称。
3. 无法可靠确定当前任务时，以空参数调用，让用户在内嵌面板中选择。不能把最近活跃任务当成当前任务，也不能使用 MCP 进程继承的旧任务 ID。
4. 保留工具原生 UI 返回，简短说明面板已请求打开。只有确实出现内嵌界面后，才能声称已显示。

MCP 工具尚未加载时，说明需要在新任务中加载更新后的插件。工具能返回数字但界面未出现时，明确说明客户端没有渲染 MCP App，不能报告集成验收完成，也不要改回浏览器方案。

## 仅查询数字

安装失败、没有数据显示或用户要求环境信息时，调用 `diagnose_installation`。它只返回系统、运行环境、Codex CLI 版本及数据库可用性；不返回用户名、路径、会话内容或凭据。只有 UI 桥接成功的面板诊断才会显示 `bridge_connected`，后台诊断不能证明界面已渲染。

使用 `get_usage`，传明确 `thread_id`。只报告用户所需字段和统计时间。`last` 是最近一次模型请求，`turn.usage` 是本轮提问累计，`total` 是本地日志累计，三者不能混用。

## 数据口径

- 上下文参考 = 最近已上报输入 / 日志报告的上下文额度，生成中及压缩后可能滞后。
- 缓存输入是输入的一部分；推理输出是输出的一部分，不重复相加。缓存命中只针对输入；输出是新生成内容。
- `turn.usage` 按本轮开始前和当前累计计数的差计算。起点缺失或计数重置时显示未知。
- `total` 不等于当前上下文，也不是套餐扣费、剩余额度或账单。
- 连接方式是近期日志中的最后观察记录，并非当前连接探测。重试次数仅覆盖最近 8000 条应用日志中的近一小时。
- 刷新由组件通过 MCP 调用完成，不需要模型循环、自动化或定时新任务。
- 只读本机统计，不读取认证文件、请求头或完整消息，不请求 API Key。

## 查看和选择通讯方式

- `get_transport_config`：读取本机基础配置中的连接偏好，可附 `thread_id` 读取该任务最近观察到的协议。
- `set_transport_mode`：仅在用户明确选择或要求切换时调用；传 `mode`（`default`、`websocket`、`https`）及刚读取的 `expected_revision`。打开面板、刷新、切换观察任务不会改变连接。
- 用户仅要求“增加切换功能”时，安装功能即可，不替用户选择并保存某种连接方式。
- `websocket` 是优先尝试，可回退 HTTPS；`https` 禁用 WebSocket；`default` 恢复原有 OpenAI 提供商。
- 内置 `openai` 在此版 Codex 中不允许覆盖。插件使用自己管理的 `codex_usage_openai` 配置，保留 OpenAI 身份验证，不写入 API Key、网址或模型设置。
- 配置作用于本机用户级新连接，不是选中任务的实时开关。旧任务可能保留原提供商，重载后应新建任务并检查日志。
- 保存成功只能报告配置已保存，不能称当前请求已切换。连接方式以时间戳标注的日志观察值为准，未知时不根据偏好猜测。
- 发现外部编辑、其他提供商、配置方案、自定义端点或校验失败时，说明工具实际返回的阻碍，不绕过检查。