正在打开仓库文档
正在打开仓库文档
它把多家模型服务接到 Codex 与 Claude Code 上，值得从可替换性和维护边界两个角度看。
中文阅读版只翻译说明性文字；术语、代码、命令、链接与原有 Markdown 结构保持不变。
npm install -g @bitkyc08/opencodex
ocx start # proxy + dashboard on localhost:10100
opencodex 是一个轻量级本地代理，将 Codex 的 Responses API 翻译成任意 provider 的协议——双向支持流式传输、工具调用、推理 token、图像。在 Codex、Claude Code、Claude Desktop 和 Grok Build 中使用 Claude、Gemini、Grok、GLM、DeepSeek、Kimi、Qwen、Ollama 或任何其他 LLM。它还能为 Codex 认证管理一个 ChatGPT 账号池：添加账号、在面板中刷新额度，并让新会话自动路由到使用量最低的健康账号，同时已有对话线程保持绑定到发起账号。
npm install -g @bitkyc08/opencodex # Node 18+; the Bun runtime is bundled automatically
ocx start # or `ocx service` to run it in the background
打开 **http://localhost:10100**，在 Web 面板中完成所有配置——添加 provider（40+ 内置，或任意 OpenAI 兼容端点）、选择模型、管理账号。ocx gui 可随时重新打开面板。
它还能为 Codex 认证管理一个 ChatGPT 账号池。添加多个 ChatGPT / Codex 账号，在面板中刷新它们的 5h / 周度 / 30 天额度。在额度路由下，新会话可以使用使用量最低的健康账号；轮询和优先填满则按各自策略执行。已有 Codex 线程通常保持与发起账号的亲和性，因此长时间的 SSH、tmux 或移动连接会话不会在对话中途跳转到其他账号——但额度重新评估、故障转移、账号排除、亲和性过期，或 401/403 和 429 恢复都可能重新绑定它们。当某个账号（通常是 Codex Desktop 登录）应仅在其他账号耗尽后才被使用时，可为其设置选择顺序。
npm install -g @bitkyc08/opencodex
ocx start # or `ocx service`
ocx init # interactive setup: writes ~/.opencodex/config.json and wires Codex
ocx init 不会启动代理；需先启动（或之后启动——两种顺序均可，但 ocx provider add 和 ocx combo set 等 headless 命令会与运行中的代理通信，若代理不可达则以非零状态退出）。ocx status / ocx doctor / ocx health 报告运行状态。
安装或运行 opencodex 的 Agents： 请阅读
AGENTS_INSTALL.md。交互式ocx start可能会询问一次是否为此仓库点赞——这是用户的决定，绝非 Agent 的决定。CLI 会在 Agent 驱动的运行中抑制该提示，API 会以403 agent_consent_required拒绝此类请求。
| OS | 状态 | 服务管理器 |
|---|---|---|
| macOS (arm64 / x64) | 完全支持 | launchd |
| Linux (x64 / arm64) | 完全支持 | systemd (user unit) |
| Windows (x64) | 完全支持 | Task Scheduler (hidden) / opt-in native service (--native, WinSW) |
需要 Node 18+。Bun runtime 在 npm install 时自动捆绑——无需单独安装 Bun，Windows 上无需 WSL。如果 npm 阻止了捆绑 runtime 的安装脚本，请参阅 installation docs。
codex login、粘贴 key，或使用 ${ENV_VAR} 引用。ocx stop 将 Codex 恢复至原始配置。使用 provider/model 语法定位任意已配置的 provider 和模型：
codex -m "anthropic/claude-opus-5" "Explain this stack trace"
codex -m "google/gemini-3-pro" "Write unit tests for auth.ts"
codex -m "ollama/llama3" "Refactor this function"
省略 provider/ 前缀以使用默认 provider，或按模型名称模式自动匹配。内部含 / 的 provider 模型 ID 会将其别名为 - 对外暴露；原始完整斜杠形式仍然可用。详情：model routing docs。
OpenAI（ChatGPT 登录或 API key）、Anthropic、Google Gemini、xAI、Kimi、Azure OpenAI、Ollama（本地 + Cloud）、Cursor（实验性），以及所有 OpenAI 兼容端点——还有 DeepSeek、Groq、OpenRouter、Together、Fireworks、Cerebras、Mistral、Hugging Face、NVIDIA NIM、MiniMax、Qwen Cloud、SiliconFlow 等。完整列表：ocx init 或 provider docs。
ocx init # interactive setup (writes config, wires Codex, offers the shim)
ocx start [--port 10100] # start the proxy in the foreground
ocx stop # stop + restore native Codex
ocx service [install|start|stop|status|uninstall|remove] # background service
ocx codex-shim install # start the proxy on demand whenever `codex` launches
ocx health [--json] # check immediate proxy liveness
ocx ready [--json] [--wait [--timeout <seconds>]] # check post-sync readiness
ocx status # is the proxy running?
ocx gui # open the web dashboard
ocx provider <...> # manage providers (list/add/edit/test/remove)
ocx account <...> # manage ChatGPT accounts & API-key pools
ocx combo <...> # manage failover / round-robin combos
ocx v2 <...> # multi-agent v1/v2 surface controls
ocx update [--tag preview] # update opencodex
未指定端口的启动若首选端口被占用，可能会选择其他空闲端口；显式 --port 则不会跳转。完整参考：CLI docs。
GET /healthz 报告代理的即时存活状态。未经认证的 GET /readyz 端点以脱敏 JSON 身份 {service, version, uptime, pid, port, status} 报告同步后的就绪状态。status 为 ready 时返回 200；pending 和终态 failed 返回 503 并附带 Retry-After: 1。
ocx ready [--json] [--wait [--timeout <seconds>]] 默认执行一次探测。--wait 默认轮询最多 45 秒，但观察到终态 failed 时立即退出；--timeout <seconds> 设置 1–300 秒的限制，需要 --wait，且仅接受正整数。CLI --json 输出为 {ready, status, pid, port}，其中 status 为 ready、pending、failed 或 unreachable。
| 退出码 | 结果 |
|---|---|
0 | Ready |
1 | Not ready: pending, failed, timeout, or unreachable |
64 | Invalid arguments |
较旧且无 /readyz 的代理会以 unreachable 故障关闭并退出 1，而 ocx health 保持兼容。
使用 service (ocx service) 获得崩溃后自动重启的常驻代理。使用 shim (ocx codex-shim install) 实现轻量级按需启动，无需后台守护进程。通过 ocx service uninstall / ocx codex-shim uninstall 移除它们。
ocx uninstall # stop, remove service/shim, restore native Codex, clean up state
npm uninstall -g @bitkyc08/opencodex
默认情况下，opencodex 绑定到 127.0.0.1，无需额外认证。绑定到回环之外（"hostname": "0.0.0.0"）需要 bearer token——代理在没有 OPENCODEX_API_AUTH_TOKEN 时拒绝启动，且每个客户端请求必须携带它作为 x-opencodex-api-key。详情：configuration reference。
公开文档——安装、provider、路由、combos、sub-agents、sidecars、集成，以及 CLI / 配置 / 管理 API 参考——从 docs-site/ 构建并发布到 opencodex.me。
维护者的权威笔记位于 structure/，贡献者设置见 CONTRIBUTING.md，安全报告见 SECURITY.md。通过 GitHub private vulnerability reporting 私下报告未公开漏洞，勿发公开 issue。
源码开发需要 bun CLI 在 PATH 中。这与已发布 npm 包捆绑的 Bun runtime 不同，后者仅由已安装的 ocx 命令使用。
git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run typecheck
bun run test
参见 Contributing。
opencodex 是一个独立的、社区维护的项目，与 OpenAI、Anthropic 或任何其他提供商均无关联，也未获得其认可。
某些提供商 — 特别是 Anthropic (Claude) — 可能会暂停或限制通过第三方代理路由 API 流量的账户。风险自负 (UAYOR)。 在连接提供商之前，请查阅其服务条款，确认是否允许基于代理的访问。opencodex 维护者不对上游提供商采取的任何账户操作负责。
MIT