AxonHub Codex 集成指南：将 Codex 流量接入 OpenAI 兼容网关、按会话聚合 Trace 并跟踪 Provider 配额

AI 应用API网关LLM 网关后端前端【免费下载链接】axonhub⚡️ Open-source AI Gateway — Use any SDK to call 100 LLMs. Built-in failover, load balancing, cost control end-to-end tracing.项目地址https://gitcode.com/gh_mirrors/ax/axonhub点击查看免费下载本篇指南讲解如何把 Codex 客户端的 API 流量指到 AxonHub使其成为 OpenAI 端点的drop-in replacement。读完你可以独立完成三步实操在~/.codex/config.toml中注册 AxonHub provider 并导出 API Key通过server.trace.codex_trace_enabled或extra_trace_headers把同一会话的多轮请求聚合为一条 Trace从而提升上游缓存命中率以及利用 AxonHub 的 Provider Quota 跟踪机制在控制台中实时查看 Codex 通道的配额窗口与重置时间。文中所有配置参数均可对照 config.example.yml 与相关源码核实。概览AxonHub 如何充当 Codex 的网关AxonHub 可以对 Codex 发出的请求执行 AI 协议/格式转换你在控制台配置多个上游通道provider然后对外暴露一个单一的 OpenAI 兼容接口供 Codex 调用。这意味着 Codex 只需要指向 AxonHub 的base_url背后到底走哪个模型、哪个供应商完全由 AxonHub 的路由与 Model Profile 决定。两个核心要点协议转换与多通道路由AxonHub 将 Codex 的请求转换为对应上游通道的协议格式一个入口即可聚合多个供应商会话级 Trace 聚合可通过server.trace.codex_trace_enabled复用Session_id头或server.trace.extra_trace_headers追加自定义头把同一会话中的多次 Codex 请求归并为一条 Trace。前置条件一台可从开发机访问的 AxonHub 实例一个具有项目project访问权限的有效 AxonHub API Key一个可配置的 CodexOpenAI 兼容应用可选已在 AxonHub 控制台配置一个或多个 Model Profile。配置 Codex 指向 AxonHub第一步注册 provider编辑${HOME}/.codex/config.toml将 AxonHub 注册为一个 model providermodel gpt-5 model_provider axonhub-responses [model_providers.axonhub-responses] name AxonHub using Chat Completions base_url http://127.0.0.1:8090/v1 env_key AXONHUB_API_KEY wire_api responses query_params {}各字段说明字段说明modelCodex 侧声明使用的模型名。该名称会经过 AxonHub 的 Model Profile 映射因此可以写占位名称详见后文配合 Model Profile 工作model_provider引用下方[model_providers.*]段落的 keynameprovider 的显示名便于在 Codex 界面辨识base_urlAxonHub 实例的 OpenAI 兼容入口默认端口为8090对应 config.example.yml 中server.port: 8090需追加/v1env_keyCodex 从中读取鉴权信息的环境变量名不是 Key 本身wire_apiCodex 与 AxonHub 之间的协议形态此处为responsesquery_params附加到出站 URL 的查询参数无则留空{}第二步导出 API KeyCodex 通过env_key指定的环境变量获取密钥请在启动 Codex 的同一 shell 会话中导出export AXONHUB_API_KEYyour-axonhub-api-key第三步重启 Codex重启 Codex 使config.toml中的配置生效。会话级 Trace 聚合重要启用内置的 Codex Trace 提取让 AxonHub 复用Session_id请求头作为 trace ID即可把同一会话的所有请求聚合到同一条 Trace 下server: trace: codex_trace_enabled: true该选项在 config.example.yml 中默认为true对应环境变量AXONHUB_SERVER_TRACE_CODEX_TRACE_ENABLED。使用其他稳定的会话标识头作为回退如果 Codex或你的客户端发送的是另一个稳定的会话标识头例如Conversation_id可以在config.yml中将其配置为回退 trace 头server: trace: extra_trace_headers: - Conversation_idextra_trace_headers在 config.example.yml 中默认值为空列表[]对应环境变量AXONHUB_SERVER_TRACE_EXTRA_TRACE_HEADERS。源码视角trace ID 是如何提取和落库的Trace 解析发生在 Gin 中间件WithTrace中见 trace.go其提取优先级为主 trace 头server.trace.trace_header默认AH-Trace-Id定义于 tracing.goextra_trace_headers中逐个回退查找codex_trace_enabled: true时调用tryExtractTraceIDFromCodexRequesttrace.go#L96-L98。Codex 侧的提取逻辑在 headers.go 的GetSessionIDFromHeaders中先尝试读取Session_id/Session-Id两个头部若都没有则解析X-Codex-Turn-Metadata头中的 JSON取出session_id字段即codex turn metadata回退路径。因此文档所说的复用Session_id在实现上有两层保障老版本客户端只发 turn metadata 时同样能聚合成功。一旦解析出 trace ID中间件会调用traceService.GetOrCreateTrace在数据库中获取或创建该会话的 Trace 记录错误只记日志、不阻塞请求将 trace ID 写回上下文并可通过response_trace_headers回写到响应头便于客户端侧关联通过shared.WithSessionID把会话 ID 放入请求上下文trace.go#L170-L171——注释明确其目的是让 provider 在需要时用于缓存。注意正因为会话 ID 会随请求下传到上游开启 Trace 聚合还会让同一会话的请求被优先发往同一上游通道从而显著提升 provider 侧缓存命中率例如 Anthropic Prompt Caching。从源码结构看/embeddings等非消息型端点如 isNonMessageEndpoint即使命中 trace 头也不会创建持久化 Trace 记录——它们属于工具调用而非会话轮次这保证了 Trace UI 中只会展示有对话内容的请求。相关行为在 trace_test.go 中有对应测试用例覆盖。验证集成发送一条样例 promptAxonHub 的请求日志中应当出现一次/v1/chat/completions或对应端点调用记录在 AxonHub 中启用 tracing检查 prompt、响应与延迟。Tracing 的完整用法见 Tracing Guide。配合 Model Profile 工作AxonHub 的 Model Profile 会把入站请求中的模型名重新映射为 provider 侧对应的模型名。典型用法在 AxonHub 控制台创建一个 profile添加映射规则支持精确名称或正则将该 profile 绑定到你的 API Key切换激活的 profile 即可改变 Codex 的实际行为而无需改动 Codex 侧任何配置。映射示例请求gpt-4→ 映射为deepseek-reasoner以获得更准确的响应请求gpt-3.5-turbo→ 映射为deepseek-chat以降低成本。即 Codex 配置中的model只是入口名真正调用什么模型由 profile 规则决定这也是把 AxonHub 作为多供应商网关的核心价值。故障排查Codex 报告认证错误确认AXONHUB_API_KEY已在启动 Codex 的同一 shell 会话中导出env_key只是变量名变量本身缺失会导致鉴权失败模型响应不符合预期到 AxonHub 控制台检查当前激活 profile 的映射规则必要时禁用或调整规则。Provider Quota 跟踪Codex 通道的配额监控AxonHub 会自动跟踪 Codex provider 通道的配额使用情况并在控制台中以电池图标展示当前状态。工作原理自动轮询Automatic PollingAxonHub 按配置间隔周期性地查询 Codex 账号的配额状态。从源码看CodexQuotaChecker.CheckQuota会携带通道中保存的 OAuthaccess_token请求https://chatgpt.com/backend-api/wham/usage端点见 codex_checker.go并从 JWT 中提取 ChatGPT 账号 ID 用于请求头通道若配置了代理轮询也会走该代理存储Storage配额数据持久化到数据库ProviderQuotaStatus实体按配置的检查间隔更新可视化Visual Indicators电池图标一眼可见剩余配额超过 80% 使用率时进入 warning 状态阈值定义见 types.go 的WarningThresholdRatio 0.8。配额窗口Quota WindowsCodex 使用多个配额窗口Primary window主窗口主要用量限制具有可配置时长例如 5 小时、1 天Secondary window次窗口可选的次级用量限制拥有独立的时长与重置计划。对应地上游返回的rate_limit结构包含primary_window与secondary_window每个窗口带有used_percent、reset_at、reset_after_seconds、limit_window_seconds等字段见 CodeUsageWindow。AxonHub 会解析这些字段把使用率换算为 0–1 的比例并归一化为available/warning/exhausted三种状态同时展示主窗口时长与重置时间。配置检查间隔在config.yml中调整配额检查间隔provider_quota: check_interval: 5m # 每 5 分钟检查一次默认值或通过环境变量export AXONHUB_PROVIDER_QUOTA_CHECK_INTERVAL30m支持的取值1m、2m、3m、4m、5m、6m、10m、12m、15m、20m、30m、1h、2h等与 config.example.yml 注释一致。该文件还额外提供了warning_check_interval_ratio默认4字段用于按比率调整 warning 状态通道的检查间隔具体语义以其注释为准。建议开发环境使用较短间隔如5m以快速获取反馈生产环境使用5m默认以保证配额变化被及时检测若想减少上游 API 调用可上调至10m或20m。手动刷新配额数据点击配额状态浮层popover中的刷新图标即可手动触发一次配额刷新。查看配额状态在控制台头部找到设置齿轮旁边的电池图标点击电池图标查看详细信息包括主窗口使用百分比与时长主窗口重置时间套餐类型plan type若上游提供次窗口使用情况若已配置。相关文档Tracing Guidetrace 提取与持久化的完整说明含 Codex / Claude Code / OpenCode 三种提取方式的对比OpenAI APIAxonHub 暴露的 OpenAI 兼容端点参考README Usage GuideAxonHub 安装与使用入门。赞分享AI 应用API网关LLM 网关后端前端【免费下载链接】axonhub⚡️ Open-source AI Gateway — Use any SDK to call 100 LLMs. Built-in failover, load balancing, cost control end-to-end tracing.项目地址https://gitcode.com/gh_mirrors/ax/axonhub点击查看免费下载相关推荐KernelSU 元模块 5 步装好meta-overlayfs 让模块修改 /system 真正生效KernelSU 元模块 5 步装好meta overlayfs 让模块修改 /system 真正生效 KernelSU 是一款基于 Android 内核的操作系统驱动开发通过 CCX 网关接入 DeepSeekClaude Code / Codex / OpenAI 兼容工具三场景完整配置指南通过 CCX 网关接入 DeepSeekClaude Code / Codex / OpenAI 兼容工具三场景完整配置指南 本文是一份以 CCXClaudAPI网关LLM 网关后端Codex-X 实战指南用桌面工具统一管理 OpenAI Codex 的提示词、Provider、会话与 Skills/MCPCodex X 实战指南用桌面工具统一管理 OpenAI Codex 的提示词、Provider、会话与 Skills/MCP 本指南围绕 Codex XO桌面应用开发者工具AI 应用上一篇Vim-dirvish与其他文件浏览器对比为什么它是最佳选择下一篇Aether-app P2P网络原理节点发现与数据同步的实现机制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考