项目快照：lidge-jun/opencodex，约 15,249 个 Star，1,149 个 Fork；最新推送时间 2026-09-18T13:06:58Z。本文基于仓库公开资料撰写。

项目地址：https://github.com/lidge-jun/opencodex · https://opencodex.me/

opencodex 从代码、运行环境到实践流程的项目封面
opencodex 的项目能力与实践流程示意。

项目速览（TL;DR）

opencodex 是一个使用 TypeScript 编写的通用提供商代理（Universal provider proxy），目标是让 OpenAI Codex 与 Claude Code 的命令行工具、应用程序和软件开发工具包（SDK）接入不同的语言模型提供商。仓库描述中列出的模型或服务包括 Claude、Gemini、Grok、DeepSeek、Ollama 等。

根据仓库资料，项目当前版本为 2.58.0，默认分支为 main，采用 MIT 许可证，要求 Node.js 版本为 18 或更高版本。GitHub 元信息显示该仓库有 15249 个 Star 和 1149 个 Fork；这些数字会随仓库活动变化，不能视为接口稳定性、性能、服务等级或维护承诺。

项目属性 资料中的值
项目名称 @bitkyc08/opencodex
当前版本 2.58.0
主要语言 TypeScript
许可证 MIT
运行时要求 Node.js >=18；仓库脚本和 Docker 构建使用 Bun 1.4.0
默认分支 main
容器服务端口 10100

定位与目标用户

本项目的核心定位不是单一模型客户端，而是位于 Codex 或 Claude Code 与模型服务之间的代理层。它把客户端侧的调用交给 OpenCodex 路由处理，再根据配置将请求转发到可用的模型提供商；具体提供商选择规则、认证字段和路由策略不在当前资料中，因此应以官方文档和最新 README 为准。

从仓库描述和关键词可以确认，目标用户包括需要使用 Codex CLI、Codex App、Codex SDK 或 Claude Code，并希望接入 Claude、Gemini、Grok、DeepSeek、Ollama 等服务的开发者。若团队只需要直接调用单一模型服务，且不使用上述客户端生态，代理层会增加配置、凭据保存和运维边界，是否采用应根据实际链路判断。

主要使用场景

  • 已有 Codex CLI、Codex App 或 Codex SDK 工作流，但希望将模型来源交给 OpenCodex 统一转发。
  • 使用 Claude Code，同时需要在不同模型提供商之间切换，而不希望逐个修改上层工具的使用方式。
  • 在本地测试环境中接入 Ollama，或将请求路由到远程模型提供商。远程提供商的具体配置项和鉴权方式，官方仓库提供的资料未完整列出。
  • 需要以服务进程形式运行代理，并通过容器暴露固定的 HTTP 端口和健康检查接口。

核心功能

项目的核心能力是提供兼容 Codex 与 Claude Code 使用方式的模型提供商代理。输入端是客户端发起的模型请求，处理过程包括代理服务接收、路由判断、凭据读取和向目标模型服务转发；输出端则返回上游响应。当前资料没有给出完整的 HTTP 接口清单、请求体模式或每个提供商的兼容性表，因此不应据此推导具体接口签名。

多提供商路由

仓库描述明确提到 Claude、Gemini、Grok、DeepSeek、Ollama 等模型或服务。项目的关键词还包含 OpenRouter、Anthropic、Responses API 和 LLM proxy，说明代码仓库围绕多提供商代理与 Codex 兼容场景组织，但关键词本身不等同于已验证的完整功能列表。

路由的实际触发条件取决于配置与客户端请求。根据当前提供的 package.json、Dockerfile 和历史说明，官方资料未提供每个提供商的字段名称、默认模型、鉴权优先级、失败重试规则或流式响应行为；部署前应直接核对官网文档和仓库最新 README。

Codex 与 Claude Code 接入

仓库描述把 Codex CLI、Codex App、Codex SDK 和 Claude Code 作为接入对象。项目二进制入口同时注册为 opencodex 和 ocx，实际启动脚本为 ./bin/ocx.mjs；这表明发布包提供命令行入口，但客户端初始化步骤和兼容参数仍需以文档为准。

当代理以 Docker 服务运行时，容器启动命令是 bun run src/cli/index.ts start --port 10100。容器健康检查访问 http://127.0.0.1:10100/healthz，该路径是 Dockerfile 中明确使用的存活检查端点，不应扩展解释为完整业务 API。

本地模型与远程模型的统一入口

Ollama 出现在项目描述和关键词中，因此仓库定位覆盖本地模型服务接入。对于本地模型，代理进程与模型服务之间还存在网络地址、模型名称、资源占用和权限隔离等运行条件；现有资料没有给出这些配置字段或模型发现机制。

远程模型提供商涉及 API 凭据和第三方服务条款。项目资料没有声明免费额度、价格、并发上限、数据保留策略、服务可用性或跨境处理规则，部署时必须分别查看所选提供商的官方条款，并在组织内部完成凭据和数据分类评估。

系统架构与关键模块

从文件结构、package.json 和 Dockerfile 可以确认，项目采用 TypeScript 源码、Bun 脚本、GUI 构建产物和可选 Rust 原生辅助组件组成的多部分结构。下面的划分只描述资料中能直接验证的模块，不把未展示的内部类名、路由表或协议细节当作事实。

命令行与服务生命周期

package.json 将 opencodex 与 ocx 都指向 bin/ocx.mjs，开发和启动脚本则调用 bun run src/cli/index.ts start。Dockerfile 通过 OCX_SERVICE=1 标记服务模式，并以前台进程形式启动代理，使 Docker 能够监督该进程的生命周期。

该设计的直接结果是：容器重启策略、日志采集和停止信号由容器运行时处理，项目没有在 Dockerfile 中安装额外的服务管理器。服务数据目录通过卷持久化，具体持久化内容包括 /home/bun/.opencodex 和 /home/bun/.codex。

源代码、GUI 与生成文件

发布包的 files 字段包含 bin、src 和 gui/dist，说明发布物同时包含命令行入口、TypeScript 源码和 GUI 构建结果。GUI 的开发和构建脚本在 gui 目录中执行，构建时使用 bun install --frozen-lockfile 和 bun run build。

Docker 构建过程还复制 scripts/model-metadata.source.json 与生成的 src/generated/compatibility-version.json。后者必须存在且包含 64 位十六进制兼容性标识，否则 Dockerfile 中的校验命令会使构建失败；资料没有说明该标识的业务语义，不能将其解释为 API 版本或协议版本。

远程工作区辅助组件

发布文件清单包括 native/remote-workspace-helper/Cargo.toml、Cargo.lock 和 Rust 源码目录，package.json 也提供了 build:remote-workspace-helper 与 test:remote-workspace-helper 脚本。这说明仓库包含远程工作区辅助组件，但现有资料没有给出它的调用协议、权限模型或适用客户端。

依赖与运行环境

运行环境由 Node.js 兼容要求、Bun 工具链、TypeScript 源码和 Docker 镜像共同构成。package.json 声明 Node.js 版本为 >=18，而 Dockerfile 将运行时固定为带摘要的 oven/bun:1.4.0 镜像，因此容器路径与本机 Node.js 路径不应直接混用。

直接依赖

  • @bufbuild/protobuf：版本范围为 ^2.14.0。
  • @modelcontextprotocol/sdk：版本范围为 ^1.30.0。
  • @napi-rs/keyring：固定为 1.3.0，用于与系统密钥环相关的能力；资料未提供具体平台支持矩阵。
  • bun：固定为 1.4.0，同时列入可信依赖。
  • zod：版本范围为 4.4.3。

开发依赖与覆盖版本

开发依赖包含 @types/bun 1.4.0 和 typescript 7.0.2。package.json 还通过 overrides 固定或覆盖 @hono/node-server、hono、fast-uri、ip-address 和 qs 的版本范围。

项目提供 typecheck、test、audit:high 和 privacy:scan 等检查脚本。资料没有提供操作系统支持矩阵、最低内存、CPU 要求、并发容量或性能基准，这些数据应以最新仓库文档和目标环境测试结果为准。

快速开始

最小闭环可以使用仓库源码完成：获取仓库、按锁文件安装依赖、启动服务，再访问容器健康检查所使用的端点。以下命令只针对本地或测试环境，使用仓库已提供的脚本和 Dockerfile 中可核对的端口。

安装依赖

Bash
git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install --frozen-lockfile

bun install --frozen-lockfile 来自 Dockerfile 和 package.json 相关构建流程。仓库资料没有提供安装 Bun 的具体命令，也没有提供从 npm registry 安装已发布包的完整步骤；因此这里不虚构系统级安装方式，Bun 的安装请以其官方环境说明和仓库最新 README 为准。

运行服务

Bash
bun run src/cli/index.ts start --port 10100

该命令与 Dockerfile 的容器启动命令一致。package.json 也提供了 start 脚本，即 bun run src/cli/index.ts start；如果不显式指定端口，资料没有声明该脚本的默认端口，因此示例使用 Dockerfile 明确给出的 10100。

验证服务

Bash
curl --fail http://127.0.0.1:10100/healthz

Dockerfile 的健康检查使用 Bun 请求同一地址，并在响应非成功状态时退出。这里没有加入 API 密钥、远程模型请求或真实业务数据，适合先验证本地进程是否监听并返回健康状态；健康检查通过不代表上游模型凭据、路由配置或业务请求已经验证成功。

配置说明

Dockerfile 明确给出了服务模式、数据目录和 API 令牌文件路径。下表只列出资料中真实出现的配置项；未在给定资料中出现的模型提供商字段、API 地址、默认模型和认证字段不予补写。

字段名 类型 默认值 作用
NODE_ENV 字符串 production Docker 运行阶段设置的 Node.js 环境标识。
OCX_SERVICE 字符串 1 标识以服务生命周期模式运行。
OPENCODEX_HOME 路径字符串 /home/bun/.opencodex OpenCodex 服务相关状态目录。
CODEX_HOME 路径字符串 /home/bun/.codex Codex 相关目录；Dockerfile 将其与 OpenCodex 目录分开保存。
OCX_API_TOKEN_FILE 路径字符串 /home/bun/.opencodex/service-api-token 服务 API 令牌文件路径。
服务端口 整数 10100（Docker 启动命令） Dockerfile 使用该端口启动服务，并通过 EXPOSE 10100 声明。

Dockerfile 还复制了权限为 0600 的 /home/bun/.opencodex/config.json。该文件的完整内容未在给定资料中展示，不能据此推断配置字段；其中的 API 令牌、模型密钥或其他秘密应由部署者在授权环境中管理，不应提交到公共仓库或写入镜像层。

进阶用法

进阶使用重点在于选择运行方式、保留必要目录并执行项目自带质量检查，而不是直接修改未公开的协议细节。下面的命令均来自 package.json 或 Dockerfile 中的脚本和指令。

使用发布包命令入口

package.json 声明发布包名称为 @bitkyc08/opencodex，并注册 opencodex 与 ocx 两个二进制名称。具体的包管理器安装命令、发布包的安装范围和 CLI 参数帮助文本，在当前资料中未完整提供，建议根据最新 README 核对后再用于团队环境。

开发与质量检查

Bash
bun run typecheck
bun run test
bun run privacy:scan
bun run audit:high

typecheck 调用 TypeScript 编译器执行无输出编译检查，test 调用 scripts/test.ts，privacy:scan 执行隐私扫描，audit:high 对根项目和 GUI 目录执行高等级审计。审计结果、测试覆盖率和失败阈值没有在资料中给出，不应将命令成功解释为安全审计或完整功能验证。

构建 GUI 与远程工作区辅助程序

Bash
bun run build:gui
bun run build:remote-workspace-helper
bun run test:remote-workspace-helper

GUI 构建脚本进入 gui 目录，冻结安装依赖后执行构建，并调用 prepare:package。Rust 辅助组件则通过 Cargo 的锁定模式构建和测试；其功能边界、启动方式和与代理主进程的连接方式，官方仓库未提供该信息，建议以最新源码说明为准。

可观测性与运维

当前资料中能够直接确认的可观测性入口是 HTTP 健康检查和前台服务进程。Dockerfile 每 30 秒检查一次 /healthz，超时时间为 5 秒，启动宽限期为 20 秒，连续失败次数为 3 次。

容器使用 USER bun 运行，并将两个用户目录声明为卷。/home/bun/.opencodex 与 /home/bun/.codex 的认证格式不兼容，Dockerfile 明确要求分开持久化，不能把它们合并到同一个认证目录中。

部署检查清单

  • 确认容器或本机服务实际监听 10100，并能访问 /healthz。
  • 为 /home/bun/.opencodex 和 /home/bun/.codex 分别配置持久化存储。
  • 检查 OCX_API_TOKEN_FILE 指向的令牌文件权限，避免将令牌写入日志。
  • 在发布前运行 typecheck、test、privacy:scan 和 audit:high。
  • 不要用健康检查结果替代上游提供商连通性、鉴权和模型响应测试。

资料没有给出结构化日志字段、指标名称、分布式追踪、请求采样策略、日志轮转、告警规则或备份恢复流程。若这些能力是生产上线条件，需在目标部署环境补充设计，并以最新项目文档验证 OpenCodex 是否提供相应钩子。

安全与合规边界

该项目会代理模型请求并涉及服务令牌、Codex 目录和模型提供商凭据，因此安全重点是授权访问、秘密管理、数据流向和运行隔离。本节只讨论在拥有相应系统、账户和数据处理授权的环境中使用，不提供绕过认证、规避审计或访问未授权目标的做法。

凭据与目录隔离

Dockerfile 将 OPENCODEX_HOME 和 CODEX_HOME 设置为两个不同目录，并明确说明两种 auth.json 格式不兼容。部署时应保持目录分离，限制宿主机卷的访问主体，并避免把包含令牌的配置文件复制到公共镜像、构建缓存或版本控制系统。

OCX_API_TOKEN_FILE 指向服务令牌文件，Dockerfile 中配置文件使用 0600 权限。资料没有说明令牌轮换、吊销、加密存储、密钥环失败时的降级路径或多用户授权模型；组织应在上线前补齐这些控制。

请求数据与第三方合规

Codex 或 Claude Code 产生的提示词、源代码、工具输出和模型响应可能包含个人信息、商业秘密或凭据。仓库资料没有声明默认脱敏、数据保留、上游训练使用、跨境传输、审计留痕或合规认证，因此不能将代理层视为自动完成隐私合规。

  • 只在已获得授权的账户、工作区和网络范围内运行代理。
  • 根据组织数据分级策略决定哪些代码、日志和提示词可以发送到远程提供商。
  • 为本地测试与生产环境分开设置目录、令牌、网络权限和持久化卷。
  • 核对每个上游提供商的服务条款、隐私政策、地区限制和数据处理协议。
  • 不要把真实生产秘密放入最小可运行示例、测试日志或公开 Issue。

许可证与商用条款

package.json 将许可证标记为 MIT，仓库资料也列出 LICENSE 文件。MIT 通常允许在满足许可证条件的前提下使用、修改、复制和分发，但本项目的实际分发义务仍应以仓库中的 LICENSE 原文为准。

在分发源码或二进制时，应保留 LICENSE 中要求保留的版权与许可声明，并核对第三方依赖各自的许可证。MIT 标识不等于项目提供商业支持、服务等级、模型调用额度、上游服务授权或数据合规保证；这些事项在当前资料中均未作承诺。

如果企业对闭源集成、内部部署、再分发、商标使用或第三方模型服务有额外要求，应由法务根据仓库 LICENSE、依赖许可证和所选模型提供商条款进行审查。资料未提供单独的商业授权条款，因此不应自行推断存在额外授权或例外。

局限性与已知限制

现有资料足以说明项目的运行入口、容器端口、目录隔离和构建脚本，但不足以覆盖完整生产决策所需的协议、性能和兼容性信息。以下限制来自资料缺口或 Dockerfile 已明确的边界，不能用未验证信息填充。

  • 官方仓库未提供完整的提供商配置字段、默认模型、鉴权优先级和路由失败策略，建议以最新 README 为准。
  • 官方仓库未提供请求与响应的完整接口签名、流式传输说明、错误码表和重试语义，不能直接据此编写生产客户端。
  • 官方仓库未提供吞吐量、延迟、并发上限、资源基线、SLA 或基准测试数据。
  • 官方仓库未提供完整操作系统兼容矩阵，也未说明 @napi-rs/keyring 在每个平台上的差异。
  • Docker 构建依赖生成的 src/generated/compatibility-version.json，源码构建流程需要按仓库要求准备该文件。
  • GUI、远程工作区辅助组件和 MCP SDK 的具体用户流程，在给定资料中没有展开。
  • 健康检查只证明服务健康端点可用，不证明任何远程模型提供商已连接或业务请求成功。

适合谁

下列信号表明项目的代理定位与需求匹配，适合先在隔离环境验证，再决定是否纳入团队工作流。判断依据来自项目描述、命令入口、容器配置和提供商关键词。

  • 团队已经使用 Codex CLI、Codex App、Codex SDK 或 Claude Code，并希望保留上层工具的工作方式。
  • 开发环境需要在 Claude、Gemini、Grok、DeepSeek、Ollama 等模型服务之间进行路由或切换。
  • 团队可以运行 Bun 或满足 Node.js 18 以上要求，并能够维护 TypeScript 项目依赖。
  • 部署环境需要以 Docker 前台进程运行服务，并能够持久化 /home/bun/.opencodex 与 /home/bun/.codex。
  • 团队能够自行完成令牌管理、数据分类、上游服务条款审核和健康检查之外的业务验证。

不适合谁

如果需求与代理层无关，或者组织无法承担多提供商凭据和数据治理责任，采用该项目的收益会受到限制。以下是可用于决策的排除信号。

  • 只需要直接调用单一模型 API，不使用 Codex 或 Claude Code，也不需要提供商切换。
  • 运行环境不允许安装 Bun、Node.js 18 以上运行时，或不允许维护 Docker 卷和前台服务。
  • 合规制度要求模型请求必须留在指定网络或指定供应商，而项目资料无法证明代理层具有满足该制度的默认控制。
  • 业务需要已公开的并发上限、延迟指标、SLA、错误码和支持合同，而仓库资料没有提供这些承诺。
  • 团队无法分别管理 OpenCodex 与 Codex 目录的权限，也不能保护 OCX_API_TOKEN_FILE 中的敏感凭据。

常见问题与排查（FAQ / Troubleshooting）

排查应先区分本地进程问题、目录与权限问题、代理配置问题和上游提供商问题。下面的步骤只使用仓库资料中可验证的路径、命令和端口。

启动后无法访问 10100，如何检查

确认启动命令是否包含 --port 10100，并检查本机访问 http://127.0.0.1:10100/healthz 是否成功。Dockerfile 中的服务端口、启动命令和健康检查都使用 10100；如果改用了其他端口，必须同步调整验证命令和容器端口映射。

容器构建因兼容性文件失败，如何处理

Dockerfile 要求构建上下文中存在 src/generated/compatibility-version.json，并在容器内验证其中的兼容性版本是否匹配 64 位十六进制格式。注释要求在主机上运行 bun scripts/generate-compatibility-version.ts，但该脚本未出现在给定 package.json 的 scripts 列表中；应以仓库当前源码和最新 README 确认它的可用路径。

为什么不能合并两个 Home 目录

Dockerfile 明确说明 .opencodex 和 .codex 中的认证文件格式不兼容。将两者合并会破坏项目预期的目录边界，因此应分别挂载、分别备份并分别设置访问权限。

健康检查通过但模型请求失败怎么办

/healthz 只用于容器健康检查，成功响应不能证明上游凭据、模型名称、网络访问或提供商协议已经正确。此时应先核对最新 README 中的提供商配置，再检查令牌文件、目录权限、网络出口和上游服务条款；具体字段缺失时，官方仓库未提供该信息，建议以最新 README 为准。

依赖安装或类型检查失败怎么办

优先使用锁定安装命令 bun install --frozen-lockfile，确认运行时满足 Node.js 18 或更高版本以及仓库 Dockerfile 使用的 Bun 1.4.0。随后执行 bun run typecheck；如果失败，保留完整错误输出并核对当前分支、锁文件和生成文件状态，不要直接删除锁文件绕过依赖约束。

项目地址与资源

以下链接均来自项目资料中的仓库、官网或官方站点，可用于核对源码、文档和发布信息。部署前应以仓库默认分支的最新内容为准。

“Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code”

来源：README（仓库项目描述）