【免费下载链接】opencodex
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code
本指南以
devlog/_chase/_model/004_patch_index.md为骨架，梳理 OpenCodex 在新增 provider、追加模型、扩展配置字段、打通 jawcode 元数据时的所有实际修改点与联动契约。读完你可以照着索引在 src/providers/registry.ts 等核心文件中定位正确的"首个修改点"，并跑通最小验证命令集，避免把代码写进错误的归属层。
OpenCodex 是面向 OpenAI Codex 与 Claude Code 的通用 provider 代理，负责把 Codex CLI/App/SDK 的请求路由到 Claude、Gemini、Grok、DeepSeek、Ollama 等任意上游。模型/provider 的增删改看似只是"加一个名字"，实际上牵动 registry、derive、router、adapter、catalog、management API 与 jawcode 元数据生成多条链路。004_patch_index.md正是为这类变更准备的"改动路由表"：先用一张表判断变更类型，再按对应清单逐点落位。
快速分类：先判定变更类型，再决定首个修改点
任何 provider/model 相关改动，第一步不是写代码，而是对照下表完成分类，确定"首个所有者"以及"需要一起确认的地方"。
| 变更类型 | 首个所有者 | 需要一起检查的位置 |
|---|---|---|
| 新增 built-in provider | src/providers/registry.ts | derive、auth、router、adapter、catalog、management API、tests/docs |
| 给已有 provider 添加模型 | registry 或 live metadata parser | adapter override、catalog tests、picker 可见性 |
| OAuth/login 变更 | src/oauth/ | registry 的authKind/oauthId、store 并发、management API |
| API-key pool / 429 变更 | src/providers/key-failover.ts | relay retry 边界、tests、quota 展示 |
| wire request/stream 变更 | src/adapters/ | src/server/adapter-resolve.ts、bridge/parser tests |
| Codex picker 元数据 | src/codex/catalog.ts | registry hints、生成 jawcode metadata、/api/models |
| jawcode model metadata 同步 | jawcode generator source | bun run generate:jawcode-metadata、catalog diff |
| GUI provider preset | registry → derive 路径 | management API（GUI 只消费派生值） |
这张表的潜台词是 OpenCodex 的分层原则：registry 是唯一正本，GUI 与 key-login 列表从不复制同一份数据。例如 provider preset 的变更必须落在"registry → derive"路径上，管理 API 与 GUI 只消费派生结果，而不是各自维护一套配置。这一规则在 devlog/_chase/_model/README.md 的操作规则一节有明确表述：built-in provider 的正本是PROVIDER_REGISTRY。
新增 built-in provider 的标准七步流程
原文档给出了完整七步，这里结合源码逐条展开：
在 registry 中登记稳定 id：在 src/providers/registry.ts 的 provider entry 中写入 stable id、label、adapter、base URL 与 auth kind。
PROVIDER_REGISTRY由PROVIDER_REGISTRY_CORE与PROVIDER_REGISTRY_EXTENDED两个分表合并而来（registry.ts），新 provider 应归入其中一张分表。entry 的字段契约定义在 src/providers/registry/types.ts 的ProviderRegistryEntry：id、label、adapter、baseUrl、authKind是必填骨架，其余如dashboardUrl、models、liveModels、modelContextWindows等按需填充。registry 加载时还会对每个 entry 执行fastWireDeclarationError校验，声明非法会直接抛TypeError（registry.ts）。确认现有 adapter 是否够用：只有在出现全新 wire shape 时才扩展 src/adapters/ 与
resolveAdapter()。从 001_provider_inventory.md 的统计看，多数 provider 落在 openai-chat（38 个）、anthropic（5 个）、google（3 个）等既有 adapter family 上——这也是文档强调"现有 adapter 够用就不新建 adapter/auth flow"的原因。处理 key/OAuth 契约：key provider 要核对
dashboardUrl与deriveKeyLoginMap()契约；OAuth provider 则需在 src/oauth/index.ts 注册 login/refresh controller，并在 registry entry 中设置oauthId，同时确认 src/oauth/store.ts 的按账号 credential store 与刷新序列化行为。ProviderAuthKind只有forward | oauth | key | local四种（registry/types.ts），先归类再动手。只有必要时才扩展 bare model prefix：默认使用显式
provider/model命名空间。文档明确"基本默认是显式 provider/model"，bare prefix 是例外而非常态——src/router.ts 中的MODEL_PROVIDER_PATTERNS目前仅覆盖claude-*、groq（llama-/mixtral-/gemma-）两类前缀（router.ts），扩表需谨慎。决定 fallback 模型与 capability 元数据的归属：static fallback 模型、live discovery、context/modality/reasoning 元数据各归其主。从 002_catalog_contract.md 的契约看，
liveModels: true的 provider 以 live/models结果为模型 ID 的权威来源，registry 只提供 fallback 与 capability hint。核对对外接口：检查
/api/providers、/api/models、selected/disabled models 以及 Codex catalog sync。管理 API 实现位于 src/server/management-api.ts，catalog 的合并与缓存失效在 src/codex/catalog.ts。补测试、跑 typecheck、更新文档：执行针对 provider/adapter/catalog 的 focused test 与
bun run typecheck，并同步用户文档。
给已有 provider 添加模型：六步轻量流程
新增模型与新增 provider 是两类变更，后者大多无需动 adapter 或 auth：
- 确认 upstream 模型 ID 与实际 wire protocol；
- 若 provider 是
liveModels: true，不要写 static allowlist，只补 fallback/capability hint——live 结果是权威，registry 的models仅作 fallback； - 按需在对应 registry entry 上补充
modelContextWindows、modelInputModalities、modelReasoningEfforts及参数排除列表（如noVisionModels、noReasoningModels、noTemperatureModels、noTopPModels、noPenaltyModels，字段定义见 registry/types.ts）； - 仅当该模型 wire 与 provider 默认不同时才修改
resolveWireProtocolOverride()——它按"硬 pin → 用户 per-model override → registry 混合 wire 默认 → provider 自身 adapter"的优先级解析（adapter-resolve.ts），当前仓库中的典型例子是 OpenCode Go 的部分 MiniMax 模型； - 区分 media-generation 模型与 vision-input chat 模型，确认 catalog filter 是否放行/隔离——media 生成模型要从 coding model picker 中分离；
- 若需复用 jawcode 元数据，先改生成 source 再重新生成 snapshot，不要手改生成文件。
新增配置字段的六步契约链
文档强调"新字段真的需要时才做"，并给出严格顺序：
- 先在 src/types.ts 的
ProviderRegistryEntry（或OcxProviderConfig）契约上扩展类型； - 在 src/config.ts 实现 validation/default/migration；
- 打通
providerConfigSeed()与enrichProviderFromRegistry()的派生路径（实现位于 src/providers/derive.ts）； - 修改 router/adapter/catalog 中的实际消费者；
- 更新 management API DTO 与 GUI editor；
- 补齐 round-trip config test 与 backward-compat test。
顺序的意图是把"类型 → 校验 → 派生 → 消费 → 对外呈现 → 回归"串成一条单向链，任何一环缺失都会让新字段在某个环节悄悄失效。
与 jawcode 的边界：谁拥有什么
OpenCodex 的模型元数据部分来自 jawcode（packages/ai/src/models.json）生成的 snapshot，但两者的所有权必须严格区分：
| 问题 | jawcode 拥有 | OpenCodex 拥有 |
|---|---|---|
| JWC 自身调用 provider？ | packages/ai/src/providers/、descriptor、auth storage | 不适用 |
| 把 Codex 请求代理到 provider？ | 参考实现 | registry、router、adapters、bridge |
| JWC bundled model metadata | generator +packages/ai/src/models.json | 消费生成的 metadata snapshot |
| Codex App picker 暴露 | 不适用 | src/codex/catalog.ts 与 sync/cache |
| OpenCodex OAuth 账号/密钥池 | 不适用 | src/oauth/、src/providers/api-keys.ts |
接收 provider patch 时，先按JWC native、OCX proxy、both、docs-only四类做初步分类。jawcode 有了某 provider 不代表 OCX registry 要自动加它；OCX 能路由某 provider 也不代表要扩充 jawcode 的KnownProvider——transport、auth、retry、catalog 的所有权不因同名而共享。
最小验证命令集
文档给出的验证命令（测试文件名需在改动前用rg --files tests | rg 'provider|router|catalog|oauth'重新确认，因为仓库测试文件会演进）：
bun test --isolate tests/provider-registry-parity.test.ts tests/provider-live-models.test.ts bun test --isolate tests/router.test.ts tests/codex-catalog.test.ts bun run typecheck git diff --check按当前仓库实际结构，provider 相关测试集中在 tests/providers/ 下（如devin-live-models.test.ts、deepseek-inbound-wire.test.ts等），catalog 契约的完成标准则要求/api/models与/v1/models共用同一 routed model source（详见 002_catalog_contract.md）。建议在改动前运行上述rg命令确认本次变更对应测试的准确文件名。
源码印证：从补丁索引到实现层
- registry 正本：
PROVIDER_REGISTRY合并entries-core与entries-extended，加载期即校验 fastWire 声明合法性（src/providers/registry.ts）；ProviderAuthKind、ModelWireDefault、InboundWire、live discovery 等类型契约集中在 src/providers/registry/types.ts。 - adapter 解析：
resolveWireProtocolOverride()支持"hard pin 优先、per-model override 次之、registry 默认兜底"的多级覆盖，且对 forward provider 禁止切换 wire（避免丢凭证），实现在 src/server/adapter-resolve.ts。 - 路由优先级：
routeModel()依次尝试显式provider/model→ 激活 provider 的defaultModel→ 已知 bare-model prefix → 静态/配置models→defaultProvider→ 报错（详见 003_auth_routing_flow.md，对应实现 src/router.ts）；且带/的 upstream 模型 id 只有在 prefix 确为已配置 provider 时才作命名空间切分。 - jawcode 元数据：生成输入默认是
../jawcode/packages/ai/src/models.json，可用JAWCODE_MODELS_JSON环境变量覆盖，输出为src/generated/jawcode-model-metadata.ts；该文件不允许手改，只能通过bun run generate:jawcode-metadata再生成（契约见 002_catalog_contract.md）。当前仓库 src/generated/ 下的实际生成物为model-metadata.ts，说明生成脚本与产物命名仍在演进，改动前应以仓库现状为准。
进一步阅读
- 变更全貌：chase/_model README（阅读顺序与正本路径）
- Provider 盘点与分层：001_provider_inventory.md
- Catalog 四输入合并契约：002_catalog_contract.md
- 认证与路由流程：003_auth_routing_flow.md
- 上游差距 backlog 与模型 id 差异：005_upstream_delta_backlog.md、007_model_id_delta.md
【免费下载链接】opencodex
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code
相关推荐
Qwen-Agent 文档分块实战：3 个参数让 RAG 知识库从上传到问答一次跑通
Qwen Agent 文档分块实战：3 个参数让 RAG 知识库从上传到问答一次跑通 把一份 PDF 丢给 AI，它却答非所问，多半是文档太长超出了模型窗口。Q
人工智能大模型AI AgentAgent 框架工具调用RAGOpenCodex 并行工具调用接入实战：provider 级 opt-in 配置、请求体标志与 Catalog 能力位全链路实现
OpenCodex 并行工具调用接入实战：provider 级 opt in 配置、请求体标志与 Catalog 能力位全链路实现 本篇技术指南以 OpenCo
opencodex 模型目录增量分析：jawcode 元数据桥接与 provider/model ID 差异对照
opencodex 模型目录增量分析：jawcode 元数据桥接与 provider/model ID 差异对照 本文以 opencodex 的 chase/_
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
