安装

安装 opencodex 后会得到 ocx 和 opencodex 两个等价命令，它们都指向同一个基于 Bun 的小型本地 HTTP 服务器。模型请求会发往路由所选的 provider；当已路由模型需要时，可选的 vision 和网络搜索 sidecar 也可以使用你的 ChatGPT 登录凭据。

默认本地路径可直接使用现有 ChatGPT/Codex 登录，无需 OpenAI API key 或任何其他 provider API key。

前置条件

要求	原因
Node ≥ 18	`ocx` 运行在 Bun 运行时上，但运行时会在 `npm install` 时自动打包，你无需自己安装 Bun。
OpenAI Codex(CLI、App 或 SDK)	opencodex 所代理的客户端。opencodex 会写入 `$CODEX_HOME/config.toml`（默认 `~/.codex/config.toml`）。
ChatGPT/Codex 登录	默认内置 `openai` 路径会转发由 `codex login` 或 Codex App 创建的账号会话；它不是 API key。
上游 provider 账号或 API key（可选）	仅当你主动添加 Anthropic、xAI、Kimi、Ollama Cloud、OpenRouter、其他托管 provider 或需要认证的自定义 endpoint 时才需要。

安装

npm install -g @bitkyc08/opencodex

较新的 npm 可能会拦截 bun 的 postinstall 脚本（npm warn install-scripts ... blocked because they are not covered by allowScripts），导致捆绑的 Bun 运行时未能就绪。请允许 bun 脚本后重新安装。注意 npm 警告给出的缩写命令缺少包名，会把当前目录重新安装进去，请始终显式写上包名：

npm install -g --allow-scripts=bun @bitkyc08/opencodex

# 如果最初是用 sudo 安装的，请继续使用 sudo：
sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex

确认两个命令都已加入 PATH：

ocx --version
opencodex --version

立即启动默认本地路径：

ocx start

保持这个终端运行，然后在另一个终端执行 ocx codex。如果 Codex 尚未登录，只需运行一次 codex login。ocx gui 会在实际代理端口打开仪表盘，并在需要时先启动代理。

发布渠道

稳定的 latest 渠道已经包含 ChatGPT、OpenAI API key、OpenRouter 以及实验性 Cursor 路由所需的 GPT-5.6 Sol/Terra/Luna 目录信息，但这些条目本身不会授予上游模型权限。只有在测试尚未正式发布的 opencodex 构建时，才需要使用 preview 渠道：

npm install -g @bitkyc08/opencodex@preview
ocx update --tag preview

从源码运行

若要对 opencodex 本身进行开发:

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run dev:proxy   # 以开发模式启动代理 API (src/cli/index.ts start)
bun run dev:gui     # 启动仪表盘 dev 服务器 (另一个终端)

bun run dev 作为 bun run dev:proxy 的别名保留。代理 API 暴露 /healthz、/v1/responses、 /api/*;只有在 bun run build:gui 生成 gui/dist 之后,GET / 才会提供打包后的仪表盘。开发仪表盘时,请用 bun run dev:gui 单独运行前端。

会创建哪些内容

opencodex 状态文件位于 $OPENCODEX_HOME（默认 ~/.opencodex），Codex 集成文件位于 $CODEX_HOME（默认 ~/.codex）。

路径	用途
`$OPENCODEX_HOME/config.json`	你的 provider、默认 provider、端口及选项。
`$OPENCODEX_HOME/ocx.pid`	正在运行的代理的 PID（单实例保护）。
`$OPENCODEX_HOME/runtime-port.json`	当前 PID、主机名和端口，包括自动选择的备用端口。
`$OPENCODEX_HOME/auth.json`	执行 `ocx login` 后保存的 OAuth 凭据。
`$OPENCODEX_HOME/catalog-backup*.json`	opencodex 修改 Codex 模型目录前创建的备份。
`$CODEX_HOME/config.toml`	仅监听回环地址时，opencodex 会添加由自身标记管理的根级 `openai_base_url`；监听非回环地址时，则使用 `model_provider = "opencodex"` 和 `[model_providers.opencodex]`，以便 Codex 发送 API 认证 header。
`$CODEX_HOME/opencodex.config.toml`	与 Codex 主配置一同写入的备用/参考 profile。
`$CODEX_HOME/opencodex-catalog.json`	供 Codex 使用的原生与已路由模型目录。

下一步

继续阅读快速开始以启动无需 key 的本地默认路径，或阅读工作原理了解其架构。