Web 仪表盘
opencodex 内置了一个由代理提供服务的本地 web 仪表盘（gui/ 下的 Vite/React 应用）。你可以在
这里快速管理 provider、Codex/ChatGPT 账号、目录模型、sidecar、子代理设置和请求流量。
ocx gui该命令会在浏览器中打开 http://localhost:<port>；如果代理尚未运行，会先自动启动。开发时也可
让 GUI dev server 单独连接到正在运行的代理：
ocx startbun run dev:gui仅 Material 3
Section titled “仅 Material 3”打包的仪表盘只包含 Material 3 界面。已退役 UI、它的源码以及相邻构建 fallback 均已删除。代理只会
提供当前包拥有的 gui/dist，且其 build manifest 必须标识 Material 3 并与运行包版本一致；HTML 使用
no-store。若缺少经过验证的构建或构建已过期，代理会报告仪表盘不可用并给出重新构建/安装指引，
不会再显示旧界面。不存在 legacy layout 切换选项。
可以完成哪些操作
Section titled “可以完成哪些操作”| 区域 | 作用 |
|---|---|
| Dashboard 摘要 | 显示 multi-agent 模式、在线状态、版本、运行时间、provider 数量、30 天 token 总量、活动 provider 和可用的原生/路由模型。 |
| Sub-agent delegation | 选择供 OpenCodex 委派指引与可选的 Codex 原生子代理默认值共用的原生/路由模型和可选 reasoning 强度。它不是逐次生成的路由器，详见下文。 |
| Sidecar | 选择 web-search 模型及强度，以及图像描述模型；更改从下一次请求开始生效。 |
| Maintenance | 重新同步 Codex 模型目录，查看项目级配置绕过警告，检查 latest/preview 版本，并可在更新后重启代理。 |
| 启动安全 | 显示注入的 Codex 路由能否在重启后继续工作，并分别显示服务、launcher shim 状态和准确的修复命令。 |
| Windows 托盘 | 安装用户登录托盘，一键控制代理启动、停止、重启、面板和状态。托盘不是代理重启服务。 |
| Codex 自动启动 | 允许已安装的 Codex launcher shim 运行 ocx ensure。此开关不会安装 shim 或后台服务。 |
| Providers | 添加、编辑、启用/禁用、删除 provider，并在支持时管理 OAuth 账号池和 API key 池。Claude（Anthropic）OAuth 池中，每个已登录账号显示各自的 5 小时与周限额条（用量按凭证计）；探测失败时保留上次已知数值并标记为暂时不可用。 |
| Add provider | 搜索 registry preset，选择账号登录、API key 服务、本地服务器或自定义 endpoint。 |
| Codex Auth | 添加 ChatGPT/Codex 池账号，选择下一 session 的账号，刷新 5h / 每周 / 30d 配额，启用或停用配额自动切换，设置其 1–100% 阈值和临时故障 failover。 |
| Subagents | 在 spawn_agent override 列表中置顶最多五个原生或路由模型。 |
| Models | 开关原生 GPT 与路由模型，配置 provider allowlist、上下文上限、v1/base/v2 以及 v2 thread 数量。 |
| Logs | 自动刷新近期请求，显示 token、请求强度以及（可用时）实际发送强度、实际模型、provider、状态、request id、耗时和错误详情。适配器发送 reasoning 参数时，详情中还会显示准确的 wire field。可按不透明会话/对话 ID（客户端提供时）筛选，并对当前已加载的 Logs 环形缓冲合计 token 与估算标价成本。 |
| Usage / Debug | 查看 token usage 覆盖率与趋势，或启用可选的 provider transport 和 usage 提取诊断。 |
| Storage | 只读查看 CODEX_HOME 磁盘占用（会话、归档、数据库、附件）。可选归档清理：预览最旧 N%，默认隔离到 CODEX_HOME/.trash，或勾选后永久删除。自动清理策略为可选且默认关闭（storageCleanupPolicy.enabled）；可在 Storage 页配置阈值/目标/计划/模式，或点「立即运行」。可在 Storage 页从隔离区恢复（JSONL + 线程）。活动会话保持只读。Codex 锁定最新/活动的 state_*.sqlite 时拒绝清理与恢复。 |
| 远程连接 | 手动输入 IPv4、IPv6 或主机名及实际运行端口，打开另一台 OpenCodex；ADMIN 认证由目标仪表盘完成。 |
| 导出 | 以支持的格式/归档导出仪表盘数据。没有受保护的密码 transport，因此密码加密 7z 暂不可用。 |
| Stop | 优雅地停止代理和已安装的后台服务，恢复原生 Codex 并退出（POST /api/stop）。 |
连接到另一台 OpenCodex
Section titled “连接到另一台 OpenCodex”从导航栏或移动菜单打开 连接到另一台 OpenCodex。输入 IPv4、IPv6 或 DNS 主机名，以及
1～65535 之间的端口。默认会填入 10100；若远端自动启动到了 fallback 端口，请改用
ocx host status（或 ocx status）显示的 identity-verified 实际运行端口，而不是只看配置值。
连接 会在新标签页打开经过验证的准确 HTTP origin 的 #/dashboard。它不会探测对方是否在线，
不会把 token 加入 URL，也不会保存 token。目标仪表盘会提示输入该代理的 ADMIN token；它与
data-plane API key 相互独立。HTTP 未加密，所以只应在可信 LAN 中直接连接；其他网络请优先使用
SSH tunnel。
机器上存在安全的 7-Zip executable 时仍可导出未加密 7z，但密码加密已禁用。7-Zip 只能通过 process arguments 接收密码，其他本地进程可能看到它。OpenCodex 在有受保护的 password-input channel 前不会启用加密。
链接到某个部分
Section titled “链接到某个部分”布局只有一种，无需切换。Dashboard 的各个部分都有自己的地址：#dashboard 打开 Overview，#dashboard/providers 与 #dashboard/models 打开另外两个。刷新、收藏和后退都会保留当前所在的部分。Logs 同理，使用 #logs 与 #logs/debug。旧的 #providers/workspace 书签现在会跳转到 #providers。
Logs 和 Usage 中的费用是根据已报告 token 计算的 API 标价折算值，不是账单，也不能证明 实际发生了扣费；实际可能计入订阅用量或消耗服务商额度。
Models 开关表示 Codex 中的最终可见状态。路由模型只有在 provider allowlist 中（或未设置 allowlist）且未被禁用时才会开启。开启模型会原子地协调两个过滤条件；全部开启 会清除 allowlist，因此以后新发现的模型也会开启。
委派选择器与生成路由的区别
Section titled “委派选择器与生成路由的区别”Dashboard 的 Sub-agent delegation 选择器会保存 injectionModel，以及可选的
injectionEffort。所选值会用于由 OpenCodex 编写的委派指引，而该指引由
multiAgentGuidanceEnabled 单独控制。清除模型时也会清除已保存的强度，并关闭原生默认值同步。
启用 用作原生 Codex 子代理默认值 后，当 OpenCodex 管理当前 Codex 路由时，下一次同步或重启会
把所选模型和强度应用为原生 [agents] 默认值；外部用户管理的 provider 配置不会被修改。这些默认值只影响新建的 Codex 任务，该选项本身不会触发委派。已有的用户自有
[agents] 默认值会保留而不会被覆盖，因此请求的默认值可能与 Codex 实际使用的默认值不同。
选择器会列出已启用的原生与路由模型，以及全局 Codex reasoning 阶梯。API 会先验证所选强度是否 属于全局阶梯；Codex 仍会根据目标目录条目再次校验该 spawn 强度。
Codex Auth 与账号池
Section titled “Codex Auth 与账号池”Codex Auth 页面用于管理原生 ChatGPT/Codex 路由：
- 手动选择账号会影响下一次新建的 Codex session；已经绑定账号的 thread 不会因为这次手动切换而 在中途转移。
- Thread affinity 可避免每个请求都来回切换账号。启用配额自动切换后，长时间运行的 thread 会被 定期重新评估；当相关 usage 达到阈值，并且存在使用率确实更低的可用账号时，该 thread 可能会 重新绑定。
- 新 session 可以选择 usage 最低的可用账号。付费计划按已知 5h、每周、30d 窗口中的最高使用率 评分；Go/Free 计划只使用 30d 窗口。
- Refresh quotas 会立即重新读取账号 usage，使路由逻辑与页面上的账号卡片使用同一份数据。
- 池账号的请求日志使用
p3fa91c这类不透明标签，不会记录账号邮箱。
仪表盘如何与代理通信
Section titled “仪表盘如何与代理通信”GUI 是代理 JSON 管理 API 之上的轻量客户端。常用 endpoint 包括：
| Endpoint | 用途 |
|---|---|
GET / PUT /api/settings | 读取设置或切换 Codex 自动启动。 |
GET /api/startup-health | 读取不含秘密信息的路由、服务、shim 和重启安全诊断。 |
GET / POST /api/windows-tray | 读取或更改 Windows 托盘安装和显示状态；POST 支持 install、start、stop、uninstall。 |
POST /api/sync | 重建共享模型目录，并把 Codex 模型缓存标记为过期。 |
GET /api/update/check · POST /api/update/run · GET /api/update/status | 检查、运行和监控自更新任务。 |
GET / PUT /api/sidecar-settings | 读取或设置 search/vision sidecar 模型。 |
GET / PUT /api/injection-model | 读取或设置委派指引模型/强度、指引开关及 Codex 原生子代理默认值同步开关。 |
GET / PUT /api/v2 | 读取或设置界面模式、Codex feature flag 和 v2 thread 上限。 |
GET /api/providers · POST /api/providers · PATCH /api/providers?name=... · DELETE /api/providers?name=... | 列出、添加/替换、启用/禁用或删除 provider。 |
GET /api/models · PUT /api/disabled-models | 列出原生/路由模型，并更新共享的 disabled-model 集合。 |
GET /api/selected-models · PUT /api/model-visibility | 读取 provider allowlist，并原子地更改单个模型或 provider 分组的最终可见状态。 |
GET /api/key-providers · GET /api/oauth/providers | 读取 API key 和 OAuth provider 目录。 |
POST /api/oauth/login · GET /api/oauth/status | 启动 provider OAuth 流程并轮询完成状态。 |
GET /api/codex-auth/accounts?refresh=1 | 列出主账号与池账号、强制刷新配额，并返回主账号的 hasCredential / terminal needsReauth 状态。 |
PUT /api/codex-auth/active · PUT /api/codex-auth/auto-switch · PUT /api/codex-auth/failover | 选择下一次请求使用的账号并配置账号池路由。 |
POST /api/codex-auth/login · GET /api/codex-auth/login-status | 通过浏览器登录添加池账号。 |
GET /api/logs?tail=50&provider=...&status=5xx | 使用 tail、provider、精确状态码或状态类别筛选近期请求元数据。 |
GET / PUT /api/subagent-models | 读取或设置五个置顶的 spawn_agent override 模型。 |
POST /api/stop | 停止代理/服务，恢复原生 Codex 并退出。 |