ByteNoteByteNote
字

字节笔记本

2026年6月24日

OpenCodex 本地运行指南

#开源工具
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

实测可复现的部署步骤。基于 AITabby/opencodex v0.3.0，macOS + Node.js 环境验证通过。

⚠️ 开始前必读：三个关键事实

  1. 这是 TypeScript 项目，不是纯 JS。npm install 会通过 postinstall 钩子自动运行 tsc 编译。直接 npm start 能跑通，是因为编译被隐式触发了——换台没装依赖的机器，需要先 npm install。
  2. 每次启动都会自动改写你的 ~/.codex/config.toml，并后台重启 Codex Desktop。它会在同目录生成 config.toml.bak_<timestamp> 备份，但属于侵入性操作，务必知情。
  3. Node.js v18+，仅支持 macOS，不支持 Windows。

一、环境检查

bash
node --version    # 必须 >= v18
npm --version
sw_vers          # 确认 macOS

可选依赖：语音 VAD 功能（silero_vad_daemon.py）依赖 torch，不装会在启动日志报 ModuleNotFoundError。不影响 Computer Use 核心功能，可忽略。

二、安装

bash
git clone https://github.com/AITabby/opencodex.git
cd opencodex
npm install

npm install 完成后，确认编译产物已生成：

bash
ls dist/server.js

如果 dist/server.js 不存在（比如 postinstall 被跳过），手动编译：

bash
npm run build   # 即 npx tsc

三、启动服务

方式 A：前台运行（便于看日志）

bash
npm start
# 或: node dist/server.js

方式 B：后台运行（关掉终端不退出）

bash
nohup node dist/server.js > /tmp/opencodex.log 2>&1 &
echo "PID=$!"

启动成功后，日志里会出现：

text
[OpenCodex] Unified HTTP server listening on port 8765
[OpenCodex] Dashboard → http://localhost:8765/dashboard

同时你会看到（每次启动都会执行）：

text
[OpenCodex] Detecting unpatched config.toml. Performing surgical auto-patch...
[OpenCodex] Successfully patched config.toml to route via OpenCodex!
[OpenCodex] Codex Desktop successfully restarted in the background.

四、验证服务可用

bash
# 1. 端口监听检查
lsof -nP -iTCP:8765 -sTCP:LISTEN

# 2. Dashboard 可访问性
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8765/dashboard
# 期望: HTTP 200

# 3. 模型列表接口
curl -s http://localhost:8765/v1/models | head

浏览器打开 http://localhost:8765/dashboard 进入配置面板。

五、配置模型

在 Dashboard 里分两步配：

1. 主模型（负责推理、决策、写代码）

填入第三方模型的 API Key 和 endpoint。例如 DeepSeek：

字段示例值
Provider / endpointhttps://api.deepseek.com/v1
API Key你的 DeepSeek Key
模型名deepseek-chat 等

2. 视觉模型（负责看截图、生成文字描述）

Vision Bridge 设置里单独配一个支持图片输入的模型。

注意： 代码里默认视觉模型是 mimo-v2.5（translator.ts 中 opencodeProvider?.vision_model || "mimo-v2.5"）。可换成 gpt-4o-mini、qwen-vl-plus 等。视觉模型只做「图转文字」，不需要强推理，选便宜的即可。

配置完成后重启 Codex Desktop，模型列表里会出现你加的模型，和官方 GPT 并排，Computer Use 功能可正常使用。

六、Vision Bridge 工作原理（为什么纯文本模型也能用 Computer Use）

text
Codex 触发 Computer Use → 截图
        ↓
截图发给【视觉模型】→ 生成文字描述
  ("当前屏幕显示 VS Code，报错面板有 TypeError 第 42 行……")
        ↓
文字描述注入【主模型】(如 DeepSeek)
        ↓
主模型根据文字决定下一步鼠标/键盘操作

DeepSeek 本身无视觉能力，但通过视觉模型中转，效果等价。视觉模型用量小（只描述截图），主推理跑 DeepSeek，整体成本远低于 GPT-4o 直接跑 Computer Use。

七、停止服务

前台运行

Ctrl + C 即可。

后台运行

bash
# 找到进程
lsof -nP -iTCP:8765 -sTCP:LISTEN
# 或
pgrep -f "dist/server.js"

# 停止（替换为实际 PID）
kill <PID>

# 确认端口已释放
lsof -nP -iTCP:8765 -sTCP:LISTEN   # 无输出 = 已停止

八、还原 Codex 配置（重要）

服务每次启动都会改写 ~/.codex/config.toml。如果不再使用 OpenCodex，需要手动还原：

bash
# 查看备份文件
ls -lt ~/.codex/config.toml.bak_*

# 对比改动
diff ~/.codex/config.toml ~/.codex/config.toml.bak_<timestamp>

# 还原
cp ~/.codex/config.toml.bak_<timestamp> ~/.codex/config.toml

改动内容主要是注入这几行（指向 OpenCodex 本地服务）：

toml
# >>> opencodex managed >>>
model_catalog_json = "/Users/<you>/.opencodex/custom_model_catalog.json"
openai_base_url = "http://127.0.0.1:8765/v1"
# <<< opencodex managed <<<

[model_providers.opencodex]
name = "OpenCodex"
base_url = "http://127.0.0.1:8765/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "dummy"

还原后重启 Codex Desktop 生效。

九、故障排查

现象原因 / 解决
localhost 拒绝连接服务没启动，或已退出。按「三、启动」重新拉起
dist/server.js 不存在没编译，跑 npm run build
npm install 卡住网络问题，可设镜像 npm config set registry https://registry.npmmirror.com
启动报 torch / silero_vad 错误语音 VAD 可选功能，不影响核心，可忽略
Dashboard 能开但模型不工作检查主模型 API Key / endpoint 是否填对，视觉模型是否配置
Codex 里看不到新模型配置改动后需重启 Codex Desktop
不想用了，Codex 行为异常按「八、还原 Codex 配置」恢复 config.toml

十、快速命令速查

bash
# 一条龙：克隆 + 安装 + 启动
git clone https://github.com/AITabby/opencodex.git && \
cd opencodex && npm install && npm start

# 后台启动 + 查日志
nohup node dist/server.js > /tmp/opencodex.log 2>&1 &
tail -f /tmp/opencodex.log

# 停止
pkill -f "dist/server.js"
开源工具
上一篇

我装了个「AI 门卫」，挡在我和 Git 远程之间

下一篇

OpenCodex 本地运行指南

分享: