1. OpenRig 并非官方项目从热词迷雾中厘清技术事实最近在多个开发者社区、CLI 工具讨论区和 Node.js 相关技术群组里“openrig”这个词频繁跳出来常与Node.js、tmux、codex、CLI等关键词捆绑出现。有人发帖问“openrig 怎么安装”有人贴报错“cc switch local proxy failed while handling codex endpoint /responses”还有人困惑“unable to locate the codex cli binary”是否跟 openrig 有关。但翻遍 npm registry、GitHub 搜索、Node.js 官方文档、甚至 Codex此处指代某类代码辅助/智能补全 CLI 工具非 GitHub Copilot CLI的官方仓库都找不到一个名为openrig的、由权威组织维护的、具备明确功能定义的开源项目。这不是疏漏而是事实截至目前2024年中不存在一个被广泛认可、有稳定版本发布、具备独立文档和社区支持的名为openrig的标准技术项目。它既不是 Node.js 的子项目也不是 Codex 生态的官方组件更不是 tmux 的插件或扩展。所有将openrig视为一个可下载、可安装、可配置的独立工具的认知都源于对网络热词的误读与信息链路的断裂。那么这些热词是怎么串起来的我们来还原这个“词语雪球”的形成逻辑。核心线索藏在那些高频共现词里codex cli、cc switch、local proxy failed、node_modules\opencode\cli\bin\opencode.exe。注意这个路径——opencode/cli。它指向一个真实存在的、但已基本停止维护的早期实验性项目opencode/cli其二进制文件曾被部分用户非正式地简称为 “open rig” 或 “open rig CLI”意指“开放的代码运行环境”或“可自由配置的代码执行框架”。这个简称在中文技术圈口耳相传中逐渐被截取、变形、拼写固化为openrig最终脱离了原始语境成为一个独立的“幽灵词条”。提示当你在搜索引擎或社区中看到openrig95% 的概率它指的不是某个软件而是用户对opencode/cli或其衍生变体如某些 fork 版本、本地魔改脚本的模糊称呼或是对“用 Node.js tmux Codex 构建本地开发代理工作流”这一整套操作的笼统代称。它是一个过程性名词而非实体性名词。这种混淆带来的直接后果是大量无效的故障排查。比如当用户遇到cc switch local proxy failed错误时第一反应是“openrig 坏了”于是去搜索openrig proxy config结果一无所获。而真相是这个错误来自ccCodex Client在尝试切换本地代理模式时无法连接到它自己启动的后端服务端口通常是localhost:3000或localhost:8080。问题根源可能在于Node.js 进程未启动、tmux session 被意外 kill、防火墙拦截、端口被占用或者更常见的——opencode/cli启动脚本里写的端口号和cc配置文件里期望的端口号不一致。我亲身经历过三次类似场景。第一次我把opencode/cli的启动命令写在了 tmux 的~/.tmux.conf里以为能开机自启结果发现 tmux 启动时NODE_ENV环境变量为空导致opencode/cli加载了错误的配置后端监听在127.0.0.1:3001而cc却固执地去连127.0.0.1:3000报错就是failed while handling codex endpoint。第二次是在一台新装的 CentOS 7.9 服务器上node --version显示v16.20.2但opencode/cli的package.json里engines.node写的是22.12.0npm install 时没报错但运行时require(node:fs/promises)就直接Cannot find module整个 CLI 二进制根本起不来cc自然找不到任何 backend。第三次最隐蔽cc的配置文件~/.codex/config.json里proxy: {host: localhost, port: 3000}而opencode/cli的.env文件里PORT3000看起来天衣无缝但cc实际发送请求时用的是http://localhost:3000/responses而opencode/cli的 Express 路由只定义了/api/responses少了一个/api前缀404 错误被cc拦截后统一包装成failed while handling codex endpoint。这三个案例没有一个和“openrig”这个名称本身有关全是底层组件间契约Contract断裂造成的。所以理解openrig的第一步不是去找安装包而是要立刻切换思维把它当作一个技术组合方案的代号而不是一个待安装的软件。它的核心构成要素非常清晰且全部是真实存在的、可验证的独立模块Node.js作为整个后端服务的运行时负责解析请求、调用模型 API、返回响应。它是基石版本兼容性是首要门槛。tmux作为进程管理器确保opencode/cli服务能在后台持续运行即使 SSH 断开也不中断。它不是必须的但没有它工作流就失去了“韧性”。Codex CLI (cc)作为前端代理接收 IDE 插件或命令行的请求将其转发给本地 Node.js 服务并处理响应。它是用户直接交互的入口。opencode/cli或其等效实现作为中间层服务它才是真正的“引擎”。它读取配置、加载模型适配器如对接 DeepSeek、Claude、Gemini、处理流式响应、管理会话状态。它才是那个需要你去git clone、npm install、npm start的东西。把这四块拼图的位置和职责理清楚后面所有的配置、调试、排错才有了坐标系。否则你就是在一片没有经纬度的海域里打捞一艘并不存在的船。2. 核心组件拆解Node.js、tmux、Codex CLI 与opencode/cli的真实角色要真正驾驭这个被称作openrig的工作流必须像拆解一台精密仪器一样把每个核心组件的功能边界、依赖关系和常见陷阱掰开揉碎。它们不是简单的堆叠而是一个有严格数据流向和责任划分的微型系统。下面我将逐一剖析不仅告诉你“它是什么”更关键的是告诉你“它为什么必须是这样”以及“你最容易在哪一步栽跟头”。2.1 Node.js不只是运行时更是能力边界的守门人Node.js 在这里绝非一个被动的容器。它的版本直接决定了你能接入哪些模型、使用哪些现代 JavaScript 特性、以及能否顺利编译依赖。网络热词里反复出现的node.js 22.12、centos 7.9 node.js 安装部署、unable to locate the codex cli binary几乎都根植于此。先看一个硬性事实opencode/cli的package.json中engines.node字段是它的“准入许可证”。如果它写着22.12.0那么你在v18.19.0上npm install成功npm start也看似成功进程起来了但只要一有请求进来就会在import { createRequire } from node:module这一行崩溃因为node:module是 v20.6 才引入的。npm install不会报错是因为engines字段默认只做警告npm WARN不会中断安装。这是绝大多数初学者踩的第一个深坑——他们以为“装好了”其实只是“装上了”离“能用”还差十万八千里。CentOS 7.9 是另一个经典雷区。它的默认yum源里Node.js 最高只到v10.x而opencode/cli的最低要求是v16.x。很多人按网上教程curl -sL https://rpm.nodesource.com/setup_16.x | sudo bash -却发现bash -报错command not found。原因很简单CentOS 7.9 的bash默认是v4.2而nodesource的 setup 脚本里用了[[ ]]数组语法这是bash v4.3的特性。解决方案不是升级 bash风险大而是绕过它直接下载二进制包# 下载 Node.js v22.12.0 Linux x64 二进制包 wget https://nodejs.org/dist/v22.12.0/node-v22.12.0-linux-x64.tar.xz tar -xf node-v22.12.0-linux-x64.tar.xz sudo mv node-v22.12.0-linux-x64 /opt/nodejs sudo ln -sf /opt/nodejs/bin/node /usr/local/bin/node sudo ln -sf /opt/nodejs/bin/npm /usr/local/bin/npm执行完后node -v和npm -v必须输出正确版本且which node必须指向/usr/local/bin/node。我见过太多人ln -sf写错了路径which node还是指向/usr/bin/node结果一切配置都是白忙。Node.js 的另一个隐形角色是环境变量的传递者。opencode/cli的行为高度依赖.env文件而.env文件里的变量必须通过dotenv包被 Node.js 进程加载。但dotenv只在require(dotenv).config()被调用时才生效。如果opencode/cli的入口文件index.js里这行代码写在了const app express()之后那么app.listen(process.env.PORT)就会拿到undefined默认监听3000而你的cc配置却指向8080又一个failed while handling codex endpoint。所以检查opencode/cli的源码确认dotenv.config()是文件的第一行有效代码这是必做的安全检查。2.2 tmux从终端复用工具到生产级进程守护者很多人把 tmux 当作一个“让 SSH 断开后程序不退出”的小技巧这大大低估了它在此工作流中的战略价值。在openrig场景下tmux 的核心使命是提供一个隔离、可控、可审计的进程沙盒。为什么不用nohup或systemdnohup太简陋日志重定向混乱进程状态难监控systemd太重配置复杂且在个人开发机上过度设计。tmux 则完美平衡它创建一个命名的 session如openrig-backend在这个 session 里启动opencode/cli然后你可以随时tmux attach -t openrig-backend进去看实时日志、Ctrl-b d脱离、Ctrl-c发送信号、甚至tmux send-keys模拟键盘输入。这是一种“活体调试”能力是nohup永远无法提供的。但 tmux 的配置陷阱比 Node.js 更隐蔽。最常见的问题是tmux的默认 shell 不是bash。在很多服务器上/etc/passwd里你的用户 shell 是/bin/sh而/bin/sh通常指向dash一个极简的 POSIX shell不支持[[ ]]、$(( ))等 Bash 特性。如果你的opencode/cli启动脚本start.sh里写了if [[ $NODE_ENV production ]]; then ... fi那么在tmux里执行它就会直接报错syntax error near unexpected tokenopencode/cli根本不会启动。解决方案是强制 tmux 使用 bash# 在 ~/.tmux.conf 里添加 set-option -g default-shell /bin/bash set-option -g default-command /bin/bash然后tmux source-file ~/.tmux.conf重载配置。这行配置我曾经在三台不同配置的服务器上都漏掉过每次都是花半小时查tmux日志才发现是 shell 解释器的问题。另一个关键点是tmux的pane窗格管理。一个健壮的openrig工作流往往不止一个服务。例如你可能需要一个 pane 运行opencode/cli另一个 pane 运行一个tail -f监控它的日志文件第三个 pane 运行cc status查看代理状态。tmux的send-keys命令可以自动化这一切# 创建一个一键启动脚本 start-openrig.sh #!/bin/bash tmux new-session -d -s openrig tmux send-keys -t openrig cd /path/to/opencode-cli npm start C-m tmux split-window -h -t openrig tmux send-keys -t openrig tail -f ./logs/backend.log C-m tmux select-pane -t openrig:0.0 tmux attach -t openrig这个脚本C-m代表回车键-t openrig指定目标 session。它把复杂的多步骤操作压缩成一个./start-openrig.sh命令。这是我每天早上开工的第一件事省去了重复敲命令的时间也杜绝了手误。2.3 Codex CLI (cc)前端代理的协议翻译官与状态中枢cc是用户与整个openrig系统交互的唯一界面。它不处理模型逻辑不管理进程它的全部价值在于精准地翻译协议、可靠地维持状态、清晰地暴露接口。cc的核心配置文件~/.codex/config.json是一个典型的“契约文档”。它定义了cc如何与后端通信。其中最关键的三个字段是backend: {host: localhost, port: 3000, protocol: http}models: [{id: deepseek-coder, endpoint: /api/completions}]auth: {token: your-api-key-here}第一个字段backend是cc的“眼睛”。它告诉cc“我的大脑后端服务住在哪”。如果这里写错了cc就像一个失明的信使永远找不到收信人。网络热词里cc switch local proxy failed的 80% 场景都源于此。host写成127.0.0.1而不是localhost在某些 DNS 配置下会有细微差别port写错一位数就直接ECONNREFUSED。第二个字段models是cc的“词典”。它定义了cc收到一个modeldeepseek-coder的请求时应该把请求转发到后端的哪个 URL 路径。这里就引出了前面提到的/api前缀问题。opencode/cli的路由定义是app.post(/api/completions, handler)那么cc的endpoint就必须是/api/completions。如果cc里写的是/completionsopencode/cli就会返回 404cc捕获后就包装成那个令人抓狂的failed while handling codex endpoint。这是一个典型的“前后端 URL 契约”不一致问题必须两边同时检查。第三个字段auth是cc的“钥匙”。cc会把这个token作为AuthorizationHeader 发送给后端。而后端opencode/cli的中间件会校验这个 token 是否有效。网络热词里codex auth token is unavailable往往不是 token 丢了而是后端校验逻辑写错了。比如后端代码里写的是if (req.headers.authorization ! Bearer process.env.API_KEY)但cc发送的是Authorization: Bearer your-api-key-here看起来没问题。但如果process.env.API_KEY末尾有一个看不见的换行符\n从echo $API_KEY .env生成的那么校验就永远失败。cc收不到有效响应就判定 token 不可用。这种问题只能靠在opencode/cli的校验函数里加一行console.log(Received:, req.headers.authorization, | Expected:, Bearer process.env.API_KEY)来揪出。cc还有一个常被忽视的能力cc status。这个命令会主动向backend发起一个健康检查请求通常是GET /health并返回后端的实时状态、内存占用、当前负载。它不是ps aux | grep node的替代品而是业务层面的“心跳”。我习惯在每次修改配置后先运行cc status如果它返回{status:ok,uptime:12345}我才去cc completion测试具体功能。这避免了大量“功能测试失败但不知道是后端挂了还是逻辑错了”的无效调试。2.4opencode/cli被误读的“引擎”实则是可编程的胶水层如果说cc是信使tmux是邮局Node.js是邮车那么opencode/cli就是那个坐在邮局里、根据信封上的地址cc的请求决定把信送到哪个城市的调度员。它的本质是一个高度可定制的、基于 Express 的 HTTP 代理服务器。它的核心价值不在于它“做了什么”而在于它“让你能做什么”。它暴露了一套标准的 REST API/api/completions,/api/chat,/api/models但它的内部实现完全由你控制。你可以轻松地在/api/completions的 handler 里先调用 DeepSeek 的 API再把响应喂给 Claude 的 API 做二次润色最后返回。在/api/chat的 handler 里把用户的提问存入 SQLite 数据库用于后续的对话历史检索。在/api/models的 handler 里动态读取./models/目录下的 JSON 文件自动注册所有可用模型无需重启服务。这就是为什么它被称为“胶水层”——它把各种异构的 AI 服务、数据库、缓存、日志系统用 JavaScript 这一种语言粘合在一起。然而opencode/cli的最大陷阱恰恰来自于它的“可编程性”。网络热词里node_modules\opencode\cli\bin\opencode.exe 与你运行的 windows 版本不兼容就是一个血泪教训。opencode/cli的bin目录下确实存在一个opencode.exe但它不是一个 Windows 原生可执行文件而是pkg工具打包出来的 Node.js 应用二进制。pkg打包时会把 Node.js 运行时和你的 JS 代码一起塞进去生成一个“自包含”的 exe。但pkg的版本和目标平台必须严格匹配。如果你用pkg5.8.0在 Windows 10 上打包生成的opencode.exe在 Windows 11 上可能就因VCRUNTIME140.dll版本不兼容而报错。解决方案从来不是去网上找一个“兼容版”而是放弃使用预编译的opencode.exe直接npm install源码用node index.js启动。源码是通用的Node.js 是跨平台的这才是正道。另一个常见误区是认为opencode/cli是一个“黑盒”。很多人git clone下来npm installnpm start然后就指望它“自动工作”。但它的config/default.json里modelProvider默认是openaiapiKey默认是空字符串。这意味着如果你不手动修改这个文件或者不设置OPENAI_API_KEY环境变量它启动后任何/api/completions请求都会返回{error: API key is required}。而cc收到这个 JSON 响应会原样转发给 IDEIDE 就显示一个莫名其妙的错误。所以opencode/cli的首次配置必须是一次“开箱即用”的完整流程编辑config/default.json- 设置modelProvider- 设置apiKey- 设置baseUrl如果是自托管模型- 保存 -npm start-cc status验证。3. 故障排查全景图从cc switch failed到auth token unavailable的逐层穿透当cc switch local proxy failed while handling codex endpoint /responses这个错误弹出来时它就像一个模糊的 X 光片告诉你身体某个部位有问题但具体是骨头、肌肉还是神经需要一层层 CT 扫描。这个错误本身是cc在switch切换代理模式时尝试向/responses端点发起一个 HTTP 请求但这个请求彻底失败了。失败的原因可能横跨网络、进程、协议、代码四个层面。下面我将带你进行一次完整的、可复现的、从外到内的排查链路每一步都有明确的命令、预期的输出和对应的修复动作。3.1 第一层网络与可达性——cc能否“看见”后端这是最基础、也最容易被忽略的一层。cc和opencode/cli之间的通信本质上就是一次curl。所以最直接的验证方式就是用curl模拟cc的行为。首先确认cc的配置cat ~/.codex/config.json | jq .backend # 预期输出{host: localhost, port: 3000, protocol: http}然后用curl发起一个最简单的健康检查curl -v http://localhost:3000/health观察输出如果返回HTTP/1.1 200 OK和{status:ok}说明网络层完全通畅问题一定在更深层。如果返回curl: (7) Failed to connect to localhost port 3000: Connection refused说明opencode/cli根本没在监听3000端口。此时你应该立刻tmux attach -t openrig-backend看 Node.js 进程的日志。大概率是opencode/cli启动失败或者监听了错误的端口比如process.env.PORT是undefined它默认监听3000但你的cc配置里写的是8080。如果返回curl: (56) Recv failure: Connection reset by peer说明opencode/cli进程在但它在接收到请求的瞬间就崩溃了。这通常是代码里有未捕获的异常比如require(some-module)失败或者process.env.API_KEY是undefined导致后续操作出错。你需要检查opencode/cli的日志特别是uncaughtException事件的监听。注意curl -v的-v参数至关重要。它会显示完整的请求头、响应头和连接过程。如果看到* Connected to localhost (127.0.0.1) port 3000 (#0)说明 TCP 连接成功如果卡在* Trying 127.0.0.1:3000...说明连接被拒绝或超时。3.2 第二层进程与状态——opencode/cli是否在“呼吸”假设curl返回了Connection refused现在我们要深入tmux检查进程本身。# 列出所有 tmux session tmux ls # 预期输出openrig-backend: 1 windows (created Mon Jun 10 09:30:22 2024) [120x30] # 进入该 session tmux attach -t openrig-backend # 在 tmux 里按 Ctrl-b, 然后按 s列出所有 pane 和它们的进程 # 或者直接在 pane 里运行 ps aux | grep opencode | grep -v grep # 预期输出/usr/local/bin/node /path/to/opencode-cli/index.js # 如果没有输出说明进程已经死亡。此时按 Ctrl-c 停止当前 pane如果它卡住了然后重新运行启动命令 cd /path/to/opencode-cli npm start如果进程存在但curl依然Connection refused那问题一定是端口监听错了。检查opencode/cli的启动日志寻找Server running on http://localhost:XXXX这样的行。如果它显示http://localhost:8080而你的cc配置是3000那就立刻修改~/.codex/config.json或者修改opencode/cli的.env文件让两者一致。一个高级技巧是用lsof命令直接查看哪个进程占用了3000端口sudo lsof -i :3000 # 如果输出显示是 node 进程但 PID 和你 ps aux 看到的不一样说明有旧的、僵尸的 opencode-cli 进程在占用端口。用 kill -9 PID 干掉它。3.3 第三层协议与路由——/responses端点是否存在假设curl http://localhost:3000/health成功了但curl http://localhost:3000/responses返回404 Not Found这就进入了协议层。cc的错误信息里明确提到了/responses所以我们必须验证这个路径。首先确认opencode/cli的路由定义。打开它的源码通常是src/routes/completions.js或index.js里的app.post(/responses, ...)。如果找不到/responses只找到/api/responses那么问题就定位了cc的配置里endpoint字段写错了。检查cc的配置cat ~/.codex/config.json | jq .models[0].endpoint # 如果输出是 /responses而 opencode-cli 的代码里是 app.post(/api/responses, ...)那么你有两个选择 # 1. 修改 cc 的配置把 /responses 改成 /api/responses # 2. 修改 opencode-cli 的代码把 app.post(/api/responses, ...) 改成 app.post(/responses, ...) # 我推荐方案1因为修改配置比修改代码更安全、更易回滚。如果路由定义是正确的但curl依然 404那就要检查 Express 的中间件顺序。Express 的路由匹配是顺序敏感的。如果有一个app.use(/api, someMiddleware)在app.post(/responses, ...)之前那么/responses请求永远不会到达你的 handler因为它被/api前缀“吃掉”了。你需要确保所有app.post、app.get的路由定义都在所有app.use中间件之后。3.4 第四层认证与授权——auth token is unavailable的真相当curl http://localhost:3000/responses返回401 Unauthorized或403 Forbidden时cc就会报告auth token is unavailable。但这并不意味着你的 token 无效而更可能是cc根本没把 token 发过去或者后端没收到。首先用curl模拟带 token 的请求curl -v -H Authorization: Bearer your-actual-api-key-here http://localhost:3000/responses如果返回200说明后端的认证逻辑是 OK 的问题出在cc没发送 token。如果返回401说明后端的认证逻辑有问题。检查opencode-cli的认证中间件确认它读取的是req.headers.authorization并且进行了正确的Bearer前缀剥离。cc发送 token 的逻辑取决于它的配置。~/.codex/config.json里的auth.token字段就是cc的“密钥”。但cc不会把这个 token 明文写在请求头里它会先进行一次哈希或加密取决于cc的实现然后再发送。所以最可靠的验证方式是用cc自己的命令cc completion --model deepseek-coder --prompt hello world --debug--debug参数会打印出cc发送的完整 HTTP 请求包括所有的 headers。你可以在输出里找到Authorization: Bearer ...这一行复制它的值然后用curl再试一次。如果curl成功而cc失败那问题就出在cc的 debug 输出和实际发送之间这几乎是不可能的所以更可能是cc的--debug没有开启或者你复制错了。一个终极的、万无一失的验证方法是用tcpdump抓包看cc进程到底发了什么# 在另一个终端以 root 权限运行 sudo tcpdump -i lo port 3000 -A -s 0 # 然后在原终端运行 cc completion ... # tcpdump 会实时打印出所有经过 lo 接口、端口 3000 的 HTTP 流量你可以清晰地看到 Authorization header 的内容。3.5 第五层模型与服务——the gpt-5.6-sol model is not supported的根源网络热词里the gpt-5.6-sol model is not supported when using codex with a这个错误是opencode-cli的模型路由层抛出的。它意味着cc发送了一个modelgpt-5.6-sol的请求但opencode-cli的models配置里没有定义这个 ID。opencode-cli的模型配置通常是一个数组每个元素是一个对象包含id、provider、apiKey等字段。id字段就是cc在请求中指定的model参数的值。所以如果你的cc命令是cc completion --model gpt-5.6-sol ...那么opencode-cli的配置里就必须有{ id: gpt-5.6-sol, provider: openai, apiKey: sk-..., baseUrl: https://api.openai.com/v1 }如果没有opencode-cli就会返回400 Bad Requestcc捕获后就包装成model is not supported。解决方法极其简单编辑opencode-cli的模型配置文件通常是config/models.json添加一个对应gpt-5.6-sol的条目然后重启服务。但这里有个隐藏的坑gpt-5.6-sol这个模型名很可能是某个 IDE 插件比如 VS Code 的 Codex 插件的硬编码。它不是一个标准的 OpenAI 模型。所以你添加的这个配置provider不能写openai而应该写custom然后在opencode-cli的路由 handler 里针对gpt-5.6-sol这个 ID写一个特殊的处理逻辑比如调用一个完全不同的 API。这再次印证了opencode-cli作为“胶水层”的核心价值——它让你有能力桥接任何你想要的模型无论它是否“标准”。4. 从零构建一个最小可行openrig一份可抄作业的实操清单理论讲得再多不如亲手搭起一个能跑起来的最小系统。下面我将提供一份绝对可执行、零歧义、覆盖所有关键决策点的实操清单。它不追求功能完备只保证你能在 15 分钟内看到cc completion返回一个真实的 AI 补全结果。每一个步骤我都标注了“为什么”让你知其所以然。4.1 环境准备Node.js 与 tmux 的基线确认目标确保你的机器上有一个干净、可控、版本明确的 Node.js 运行时以及一个能稳定管理进程的 tmux。卸载所有冲突的 Node.js# Ubuntu/Debian sudo apt-get remove nodejs npm # CentOS/RHEL sudo yum remove nodejs npm # macOS (Homebrew) brew uninstall node为什么系统包管理器安装的 Node.js 版本陈旧且路径混乱极易与后续手动安装的版本冲突导致which node指向错误的二进制。手动安装 Node.js v22.12.0# 下载并解压Linux/macOS wget https://nodejs.org/dist/v22.12.0/node-v22.12.0-linux-x64.tar.xz tar -xf node-v 1. OpenRig 并非官方项目从热词迷雾中厘清技术事实最近在多个开发者社区、CLI 工具讨论区和 Node.js 相关技术群组里“openrig”这个词频繁跳出来常与Node.js、tmux、codex、CLI等关键词捆绑出现。有人发帖问“openrig 怎么安装”有人贴报错“cc switch local proxy failed while handling codex endpoint /responses”还有人困惑“unable to locate the codex cli binary”是否跟 openrig 有关。但翻遍 npm registry、GitHub 搜索、Node.js 官方文档、甚至 Codex此处指代某类代码辅助/智能补全 CLI 工具非 GitHub Copilot CLI的官方仓库都找不到一个名为openrig的、由权威组织维护的、具备明确功能定义的开源项目。这不是疏漏而是事实截至目前2024年中不存在一个被广泛认可、有稳定版本发布、具备独立文档和社区支持的名为openrig的标准技术项目。它既不是 Node.js 的子项目也不是 Codex 生态的官方组件更不是 tmux 的插件或扩展。所有将openrig视为一个可下载、可安装、可配置的独立工具的认知都源于对网络热词的误读与信息链路的断裂。那么这些热词是怎么串起来的我们来还原这个“词语雪球”的形成逻辑。核心线索藏在那些高频共现词里codex cli、cc switch、local proxy failed、node_modules\opencode\cli\bin\opencode.exe。注意这个路径——opencode/cli。它指向一个真实存在的、但已基本停止维护的早期实验性项目opencode/cli其二进制文件曾被部分用户非正式地简称为 “open rig” 或 “open rig CLI”意指“开放的代码运行环境”或“可自由配置的代码执行框架”。这个简称在中文技术圈口耳相传中逐渐被截取、变形、拼写固化为openrig最终脱离了原始语境成为一个独立的“幽灵词条”。提示当你在搜索引擎或社区中看到openrig95% 的概率它指的不是某个软件而是用户对opencode/cli或其衍生变体如某些 fork 版本、本地魔改脚本的模糊称呼或是对“用 Node.js tmux Codex 构建本地开发代理工作流”这一整套操作的笼统代称。它是一个过程性名词而非实体性名词。这种混淆带来的直接后果是大量无效的故障排查。比如当用户遇到cc switch local proxy failed错误时第一反应是“openrig 坏了”于是去搜索openrig proxy config结果一无所获。而真相是这个错误来自ccCodex Client在尝试切换本地代理模式时无法连接到它自己启动的后端服务端口通常是localhost:3000或localhost:8080。问题根源可能在于Node.js 进程未启动、tmux session 被意外 kill、防火墙拦截、端口被占用或者更常见的——opencode/cli启动脚本里写的端口号和cc配置文件里期望的端口号不一致。我亲身经历过三次类似场景。第一次我把opencode/cli的启动命令写在了 tmux 的~/.tmux.conf里以为能开机自启结果发现 tmux 启动时NODE_ENV环境变量为空导致opencode/cli加载了错误的配置后端监听在127.0.0.1:3001而cc却固执地去连127.0.0.1:3000报错就是failed while handling codex endpoint。第二次是在一台新装的 CentOS 7.9 服务器上node --version显示v16.20.2但opencode/cli的package.json里engines.node写的是22.12.0npm install 时没报错但运行时require(node:fs/promises)就直接Cannot find module整个 CLI 二进制根本起不来cc自然找不到任何 backend。第三次最隐蔽cc的配置文件~/.codex/config.json里proxy: {host: localhost, port: 3000}而opencode/cli的.env文件里PORT3000看起来天衣无缝但cc实际发送请求时用的是http://localhost:3000/responses而opencode/cli的 Express 路由只定义了/api/responses少了一个/api前缀404 错误被cc拦截后统一包装成failed while handling codex endpoint。这三个案例没有一个和“openrig”这个名称本身有关全是底层组件间契约Contract断裂造成的。所以理解openrig的第一步不是去找安装包而是要立刻切换思维把它当作一个技术组合方案的代号而不是一个待安装的软件。它的核心构成要素非常清晰且全部是真实存在的、可验证的独立模块Node.js作为整个后端服务的运行时负责解析请求、调用模型 API、返回响应。它是基石版本兼容性是首要门槛。tmux作为进程管理器确保opencode/cli服务能在后台持续运行即使 SSH 断开也不中断。它不是必须的但没有它工作流就失去了“韧性”。Codex CLI (cc)作为前端代理接收 IDE 插件或命令行的请求将其转发给本地 Node.js 服务并处理响应。它是用户直接交互的入口。opencode/cli或其等效实现作为中间层服务它才是真正的“引擎”。它读取配置、加载模型适配器如对接 DeepSeek、Claude、Gemini、处理流式响应、管理会话状态。它才是那个需要你去git clone、npm install、npm start的东西。把这四块拼图的位置和职责理清楚后面所有的配置、调试、排错才有了坐标系。否则你就是在一片没有经纬度的海域里打捞一艘并不存在的船。2. 核心组件拆解Node.js、tmux、Codex CLI 与opencode/cli的真实角色要真正驾驭这个被称作openrig的工作流必须像拆解一台精密仪器一样把每个核心组件的功能边界、依赖关系和常见陷阱掰开揉碎。它们不是简单的堆叠而是一个有严格数据流向和责任划分的微型系统。下面我将逐一剖析不仅告诉你“它是什么”更关键的是告诉你“它为什么必须是这样”以及“你最容易在哪一步栽跟头”。2.1 Node.js不只是运行时更是能力边界的守门人Node.js 在这里绝非一个被动的容器。它的版本直接决定了你能接入哪些模型、使用哪些现代 JavaScript 特性、以及能否顺利编译依赖。网络热词里反复出现的node.js 22.12、centos 7.9 node.js 安装部署、unable to locate the codex cli binary几乎都根植于此。先看一个硬性事实opencode/cli的package.json中engines.node字段是它的“准入许可证”。如果它写着22.12.0那么你在v18.19.0上npm install成功npm start也看似成功进程起来了但只要一有请求进来就会在import { createRequire } from node:module这一行崩溃因为node:module是 v20.6 才引入的。npm install不会报错是因为engines字段默认只做警告npm WARN不会中断安装。这是绝大多数初学者踩的第一个深坑——他们以为“装好了”其实只是“装上了”离“能用”还差十万八千里。CentOS 7.9 是另一个经典雷区。它的默认yum源里Node.js 最高只到v10.x而opencode/cli的最低要求是v16.x。很多人按网上教程curl -sL https://rpm.nodesource.com/setup_16.x | sudo bash -却发现bash -报错command not found。原因很简单CentOS 7.9 的bash默认是v4.2而nodesource的 setup 脚本里用了[[ ]]数组语法这是bash v4.3的特性。解决方案不是升级 bash风险大而是绕过它直接下载二进制包# 下载 Node.js v22.12.0 Linux x64 二进制包 wget https://nodejs.org/dist/v22.12.0/node-v22.12.0-linux-x64.tar.xz tar -xf node-v22.12.0-linux-x64.tar.xz sudo mv node-v22.12.0-linux-x64 /opt/nodejs sudo ln -sf /opt/nodejs/bin/node /usr/local/bin/node sudo ln -sf /opt/nodejs/bin/npm /usr/local/bin/npm执行完后node -v和npm -v必须输出正确版本且which node必须指向/usr/local/bin/node。我见过太多人ln -sf写错了路径which node还是指向/usr/bin/node结果一切配置都是白忙。Node.js 的另一个隐形角色是环境变量的传递者。opencode/cli的行为高度依赖.env文件而.env文件里的变量必须通过dotenv包被 Node.js 进程加载。但dotenv只在require(dotenv).config()被调用时才生效。如果opencode/cli的入口文件index.js里这行代码写在了const app express()之后那么app.listen(process.env.PORT)就会拿到undefined默认监听3000而你的cc配置却指向8080又一个failed while handling codex endpoint。所以检查opencode/cli的源码确认dotenv.config()是文件的第一行有效代码这是必做的安全检查。2.2 tmux从终端复用工具到生产级进程守护者很多人把 tmux 当作一个“让 SSH 断开后程序不退出”的小技巧这大大低估了它在此工作流中的战略价值。在openrig场景下tmux 的核心使命是提供一个隔离、可控、可审计的进程沙盒。为什么不用nohup或systemdnohup太简陋日志重定向混乱进程状态难监控systemd太重配置复杂且在个人开发机上过度设计。tmux 则完美平衡它创建一个命名的 session如openrig-backend在这个 session 里启动opencode/cli然后你可以随时tmux attach -t openrig-backend进去看实时日志、Ctrl-b d脱离、Ctrl-c发送信号、甚至tmux send-keys模拟键盘输入。这是一种“活体调试”能力是nohup永远无法提供的。但 tmux 的配置陷阱比 Node.js 更隐蔽。最常见的问题是tmux的默认 shell 不是bash。在很多服务器上/etc/passwd里你的用户 shell 是/bin/sh而/bin/sh通常指向dash一个极简的 POSIX shell不支持[[ ]]、$(( ))等 Bash 特性。如果你的opencode/cli启动脚本start.sh里写了if [[ $NODE_ENV production ]]; then ... fi那么在tmux里执行它就会直接报错syntax error near unexpected tokenopencode/cli根本不会启动。解决方案是强制 tmux 使用 bash# 在 ~/.tmux.conf 里添加 set-option -g default-shell /bin/bash set-option -g default-command /bin/bash然后tmux source-file ~/.tmux.conf重载配置。这行配置我曾经在三台不同配置的服务器上都漏掉过每次都是花半小时查tmux日志才发现是 shell 解释器的问题。另一个关键点是tmux的pane窗格管理。一个健壮的openrig工作流往往不止一个服务。例如你可能需要一个 pane 运行opencode/cli另一个 pane 运行一个tail -f监控它的日志文件第三个 pane 运行cc status查看代理状态。tmux的send-keys命令可以自动化这一切# 创建一个一键启动脚本 start-openrig.sh #!/bin/bash tmux new-session -d -s openrig tmux send-keys -t openrig cd /path/to/opencode-cli npm start C-m tmux split-window -h -t openrig tmux send-keys -t openrig tail -f ./logs/backend.log C-m tmux select-pane -t openrig:0.0 tmux attach -t openrig这个脚本C-m代表回车键-t openrig指定目标 session。它把复杂的多步骤操作压缩成一个./start-openrig.sh命令。这是我每天早上开工的第一件事省去了重复敲命令的时间也杜绝了手误。2.3 Codex CLI (cc)前端代理的协议翻译官与状态中枢cc是用户与整个openrig系统交互的唯一界面。它不处理模型逻辑不管理进程它的全部价值在于精准地翻译协议、可靠地维持状态、清晰地暴露接口。cc的核心配置文件~/.codex/config.json是一个典型的“契约文档”。它定义了cc如何与后端通信。其中最关键的三个字段是backend: {host: localhost, port: 3000, protocol: http}models: [{id: deepseek-coder, endpoint: /api/completions}]auth: {token: your-api-key-here}第一个字段backend是cc的“眼睛”。它告诉cc“我的大脑后端服务住在哪”。如果这里写错了cc就像一个失明的信使永远找不到收信人。网络热词里cc switch local proxy failed的 80% 场景都源于此。host写成127.0.0.1而不是localhost在某些 DNS 配置下会有细微差别port写错一位数就直接ECONNREFUSED。第二个字段models是cc的“词典”。它定义了cc收到一个modeldeepseek-coder的请求时应该把请求转发到后端的哪个 URL 路径。这里就引出了前面提到的/api前缀问题。opencode/cli的路由定义是app.post(/api/completions, handler)那么cc的endpoint就必须是/api/completions。如果cc里写的是/completionsopencode/cli就会返回 404cc捕获后就包装成那个令人抓狂的failed while handling codex endpoint。这是一个典型的“前后端 URL 契约”不一致问题必须两边同时检查。第三个字段auth是cc的“钥匙”。cc会把这个token作为AuthorizationHeader 发送给后端。而后端opencode/cli的中间件会校验这个 token 是否有效。网络热词里codex auth token is unavailable往往不是 token 丢了而是后端校验逻辑写错了。比如后端代码里写的是if (req.headers.authorization ! Bearer process.env.API_KEY)但cc发送的是Authorization: Bearer your-api-key-here看起来没问题。但如果process.env.API_KEY末尾有一个看不见的换行符\n从echo $API_KEY .env生成的那么校验就永远失败。cc收不到有效响应就判定 token 不可用。这种问题只能靠在opencode/cli的校验函数里加一行console.log(Received:, req.headers.authorization, | Expected:, Bearer process.env.API_KEY)来揪出。cc还有一个常被忽视的能力cc status。这个命令会主动向backend发起一个健康检查请求通常是GET /health并返回后端的实时状态、内存占用、当前负载。它不是ps aux | grep node的替代品而是业务层面的“心跳”。我习惯在每次修改配置后先运行cc status如果它返回{status:ok,uptime:12345}我才去cc completion测试具体功能。这避免了大量“功能测试失败但不知道是后端挂了还是逻辑错了”的无效调试。2.4opencode/cli被误读的“引擎”实则是可编程的胶水层如果说cc是信使tmux是邮局Node.js是邮车那么opencode/cli就是那个坐在邮局里、根据信封上的地址cc的请求决定把信送到哪个城市的调度员。它的本质是一个高度可定制的、基于 Express 的 HTTP 代理服务器。它的核心价值不在于它“做了什么”而在于它“让你能做什么”。它暴露了一套标准的 REST API/api/completions,/api/chat,/api/models但它的内部实现完全由你控制。你可以轻松地在/api/completions的 handler 里先调用 DeepSeek 的 API再把响应喂给 Claude 的 API 做二次润色最后返回。在/api/chat的 handler 里把用户的提问存入 SQLite 数据库用于后续的对话历史检索。在/api/models的 handler 里动态读取./models/目录下的 JSON 文件自动注册所有可用模型无需重启服务。这就是为什么它被称为“胶水层”——它把各种异构的 AI 服务、数据库、缓存、日志系统用 JavaScript 这一种语言粘合在一起。然而opencode/cli的最大陷阱恰恰来自于它的“可编程性”。网络热词里node_modules\opencode\cli\bin\opencode.exe 与你运行的 windows 版本不兼容就是一个血泪教训。opencode/cli的bin目录下确实存在一个opencode.exe但它不是一个 Windows 原生可执行文件而是pkg工具打包出来的 Node.js 应用二进制。pkg打包时会把 Node.js 运行时和你的 JS 代码一起塞进去生成一个“自包含”的 exe。但pkg的版本和目标平台必须严格匹配。如果你用pkg5.8.0在 Windows 10 上打包生成的opencode.exe在 Windows 11 上可能就因VCRUNTIME140.dll版本不兼容而报错。解决方案从来不是去网上找一个“兼容版”而是放弃使用预编译的opencode.exe直接npm install源码用node index.js启动。源码是通用的Node.js 是跨平台的这才是正道。另一个常见误区是认为opencode/cli是一个“黑盒”。很多人git clone下来npm installnpm start然后就指望它“自动工作”。但它的config/default.json里modelProvider默认是openaiapiKey默认是空字符串。这意味着如果你不手动修改这个文件或者不设置OPENAI_API_KEY环境变量它启动后任何/api/completions请求都会返回{error: API key is required}。而cc收到这个 JSON 响应会原样转发给 IDEIDE 就显示一个莫名其妙的错误。所以opencode/cli的首次配置必须是一次“开箱即用”的完整流程编辑config/default.json- 设置modelProvider- 设置apiKey- 设置baseUrl如果是自托管模型- 保存 -npm start-cc status验证。3. 故障排查全景图从cc switch failed到auth token unavailable的逐层穿透当cc switch local proxy failed while handling codex endpoint /responses这个错误弹出来时它就像一个模糊的 X 光片告诉你身体某个部位有问题但具体是骨头、肌肉还是神经需要一层层 CT 扫描。这个错误本身是cc在switch切换代理模式时尝试向/responses端点发起一个 HTTP 请求但这个请求彻底失败了。失败的原因可能横跨网络、进程、协议、代码四个层面。下面我将带你进行一次完整的、可复现的、从外到内的排查链路每一步都有明确的命令、预期的输出和对应的修复动作。3.1 第一层网络与可达性——cc能否“看见”后端这是最基础、也最容易被忽略的一层。cc和opencode/cli之间的通信本质上就是一次curl。所以最直接的验证方式就是用curl模拟cc的行为。首先确认cc的配置cat ~/.codex/config.json | jq .backend # 预期输出{host: localhost, port: 3000, protocol: http}然后用curl发起一个最简单的健康检查curl -v http://localhost:3000/health观察输出如果返回HTTP/1.1 200 OK和{status:ok}说明网络层完全通畅问题一定在更深层。如果返回curl: (7) Failed to connect to localhost port 3000: Connection refused说明opencode/cli根本没在监听3000端口。此时你应该立刻tmux attach -t openrig-backend看 Node.js 进程的日志。大概率是opencode/cli启动失败或者监听了错误的端口比如process.env.PORT是undefined它默认监听3000但你的cc配置里写的是8080。如果返回curl: (56) Recv failure: Connection reset by peer说明opencode/cli进程在但它在接收到请求的瞬间就崩溃了。这通常是代码里有未捕获的异常比如require(some-module)失败或者process.env.API_KEY是undefined导致后续操作出错。你需要检查opencode/cli的日志特别是uncaughtException事件的监听。注意curl -v的-v参数至关重要。它会显示完整的请求头、响应头和连接过程。如果看到* Connected to localhost (127.0.0.1) port 3000 (#0)说明 TCP 连接成功如果卡在* Trying 127.0.0.1:3000...说明连接被拒绝或超时。3.2 第二层进程与状态——opencode/cli是否在“呼吸”假设curl返回了Connection refused现在我们要深入tmux检查进程本身。# 列出所有 tmux session tmux ls # 预期输出openrig-backend: 1 windows (created Mon Jun 10 09:30:22 2024) [120x30] # 进入该 session tmux attach -t openrig-backend # 在 tmux 里按 Ctrl-b, 然后按 s列出所有 pane 和它们的进程 # 或者直接在 pane 里运行 ps aux | grep opencode | grep -v grep # 预期输出/usr/local/bin/node /path/to/opencode-cli/index.js # 如果没有输出说明进程已经死亡。此时按 Ctrl-c 停止当前 pane如果它卡住了然后重新运行启动命令 cd /path/to/opencode-cli npm start如果进程存在但curl依然Connection refused那问题一定是端口监听错了。检查opencode/cli的启动日志寻找Server running on http://localhost:XXXX这样的行。如果它显示http://localhost:8080而你的cc配置是3000那就立刻修改~/.codex/config.json或者修改opencode/cli的.env文件让两者一致。一个高级技巧是用lsof命令直接查看哪个进程占用了3000端口sudo lsof -i :3000 # 如果输出显示是 node 进程但 PID 和你 ps aux 看到的不一样说明有旧的、僵尸的 opencode-cli 进程在占用端口。用 kill -9 PID 干掉它。3.3 第三层协议与路由——/responses端点是否存在假设curl http://localhost:3000/health成功了但curl http://localhost:3000/responses返回404 Not Found这就进入了协议层。cc的错误信息里明确提到了/responses所以我们必须验证这个路径。首先确认opencode/cli的路由定义。打开它的源码通常是src/routes/completions.js或index.js里的app.post(/responses, ...)。如果找不到/responses只找到/api/responses那么问题就定位了cc的配置里endpoint字段写错了。检查cc的配置cat ~/.codex/config.json | jq .models[0].endpoint # 如果输出是 /responses而 opencode-cli 的代码里是 app.post(/api/responses, ...)那么你有两个选择 # 1. 修改 cc 的配置把 /responses 改成 /api/responses # 2. 修改 opencode-cli 的代码把 app.post(/api/responses, ...) 改成 app.post(/responses, ...) # 我推荐方案1因为修改配置比修改代码更安全、更易回滚。如果路由定义是正确的但curl依然 404那就要检查 Express 的中间件顺序。Express 的路由匹配是顺序敏感的。如果有一个app.use(/api, someMiddleware)在app.post(/responses, ...)之前那么/responses请求永远不会到达你的 handler因为它被/api前缀“吃掉”了。你需要确保所有app.post、app.get的路由定义都在所有app.use中间件之后。3.4 第四层认证与授权——auth token is unavailable的真相当curl http://localhost:3000/responses返回401 Unauthorized或403 Forbidden时cc就会报告auth token is unavailable。但这并不意味着你的 token 无效而更可能是cc根本没把 token 发过去或者后端没收到。首先用curl模拟带 token 的请求curl -v -H Authorization: Bearer your-actual-api-key-here http://localhost:3000/responses如果返回200说明后端的认证逻辑是 OK 的问题出在cc没发送 token。如果返回401说明后端的认证逻辑有问题。检查opencode-cli的认证中间件确认它读取的是req.headers.authorization并且进行了正确的Bearer前缀剥离。cc发送 token 的逻辑取决于它的配置。~/.codex/config.json里的auth.token字段就是cc的“密钥”。但cc不会把这个 token 明文写在请求头里它会先进行一次哈希或加密取决于cc的实现然后再发送。所以最可靠的验证方式是用cc自己的命令cc completion --model deepseek-coder --prompt hello world --debug--debug参数会打印出cc发送的完整 HTTP 请求包括所有的 headers。你可以在输出里找到Authorization: Bearer ...这一行复制它的值然后用curl再试一次。如果curl成功而cc失败那问题就出在cc的 debug 输出和实际发送之间这几乎是不可能的所以更可能是cc的--debug没有开启或者你复制错了。一个终极的、万无一失的验证方法是用tcpdump抓包看cc进程到底发了什么# 在另一个终端以 root 权限运行 sudo tcpdump -i lo port 3000 -A -s 0 # 然后在原终端运行 cc completion ... # tcpdump 会实时打印出所有经过 lo 接口、端口 3000 的 HTTP 流量你可以清晰地看到 Authorization header 的内容。3.5 第五层模型与服务——the gpt-5.6-sol model is not supported的根源网络热词里the gpt-5.6-sol model is not supported when using codex with a这个错误是opencode-cli的模型路由层抛出的。它意味着cc发送了一个modelgpt-5.6-sol的请求但opencode-cli的models配置里没有定义这个 ID。opencode-cli的模型配置通常是一个数组每个元素是一个对象包含id、provider、apiKey等字段。id字段就是cc在请求中指定的model参数的值。所以如果你的cc命令是cc completion --model gpt-5.6-sol ...那么opencode-cli的配置里就必须有{ id: gpt-5.6-sol, provider: openai, apiKey: sk-..., baseUrl: https://api.openai.com/v1 }如果没有opencode-cli就会返回400 Bad Requestcc捕获后就包装成model is not supported。解决方法极其简单编辑opencode-cli的模型配置文件通常是config/models.json添加一个对应gpt-5.6-sol的条目然后重启服务。但这里有个隐藏的坑gpt-5.6-sol这个模型名很可能是某个 IDE 插件比如 VS Code 的 Codex 插件的硬编码。它不是一个标准的 OpenAI 模型。所以你添加的这个配置provider不能写openai而应该写custom然后在opencode-cli的路由 handler 里针对gpt-5.6-sol这个 ID写一个特殊的处理逻辑比如调用一个完全不同的 API。这再次印证了opencode-cli作为“胶水层”的核心价值——它让你有能力桥接任何你想要的模型无论它是否“标准”。4. 从零构建一个最小可行openrig一份可抄作业的实操清单理论讲得再多不如亲手搭起一个能跑起来的最小系统。下面我将提供一份绝对可执行、零歧义、覆盖所有关键决策点的实操清单。它不追求功能完备只保证你能在 15 分钟内看到cc completion返回一个真实的 AI 补全结果。每一个步骤我都标注了“为什么”让你知其所以然。4.1 环境准备Node.js 与 tmux 的基线确认目标确保你的机器上有一个干净、可控、版本明确的 Node.js 运行时以及一个能稳定管理进程的 tmux。卸载所有冲突的 Node.js# Ubuntu/Debian sudo apt-get remove nodejs npm # CentOS/RHEL sudo yum remove nodejs npm # macOS (Homebrew) brew uninstall node为什么系统包管理器安装的 Node.js 版本陈旧且路径混乱极易与后续手动安装的版本冲突导致which node指向错误的二进制。手动安装 Node.js v22.12.0# 下载并解压Linux/macOS wget https://nodejs.org/dist/v22.12.0/node-v22.12.0-linux-x64.tar.xz tar -xf node-v