Jev本地模型接入Codex：用TypeSafe决策模型实现离线与云端的自动路由

1. 先把 Jev、Codex、TypeSafe 这三个词放在同一张桌上

1.1 Jev 到底是个什么东西，它为什么值得接进 Codex

先交代背景。我最近一直在用 Codex 做终端里的编码代理，它能把“你帮我改一下这个模块”这种自然语言指令，拆解成改文件、跑测试、查日志的实际操作。Codex 的好处是它有一套完整 agent 循环，工具调用、上下文管理、多轮对话都做得比较省心，不需要你手动去喂上下文。

但这里有个老问题：Codex 默认走云端模型，能力没问题，可一旦遇到私有代码、离线开发环境，或者想完全掌控模型行为的时候，就非常受限。数据要往外发，网络断了就没法用，api 账单还会随用量越走越高。

于是我注意到 Jev。Jev 是一个可以本地部署的模型与聊天助手项目，具备 OpenAI 兼容的 API 结构，你可以把它理解成“本地推理引擎 + 代码助手外壳”的组合。它尤其针对代码补全和指令遵循做了调优，本地跑起来之后，离线场景也能提供推理能力。

把 Jev 接进 Codex，本质上是拿 Codex 的外壳——也就是那一整套自动改代码、执行命令、多轮任务拆解的工具链——去驱动 Jev 的本地推理内核。两者互补的点非常明显：Codex 擅长调度，Jev 擅长在本地完成推理，成本、隐私、可控性一次全拿回来。

这跟社区里有人拿 Codex 接 DeepSeek 是同一个思路。Codex 并没有绑死只能用自己的官方模型，它允许配置自定义模型提供者。既然 DeepSeek 这种在线 API 能接，那 Jev 这种本地服务当然也能接，而且反过来更自由——你甚至可以在飞机上、在无网环境里继续用 Codex 干活。

1.2 决策模型不 TypeSafe 会怎样：两个真实翻车场景

说“接入”，本质上是在做一道路由题。请求来了，什么时候发给 Codex 云端，什么时候转给本地 Jev，模型名填什么，endpoint 指向哪里，超时多久算失败——这些规则组合在一起，就是一个决策模型。

如果决策模型是 TypeSafe 的，配置会在编译期或运行前被校验兜住，类型不对、字段缺失、拼写错误都会有明确报错；反过来，如果它就是一堆散装的字符串和 if 分支，那踩坑是必然的。

我见过两个真实的翻车场景。

第一个：朋友在 Codex 的配置文件里写了一个模型名，用来切换本地链路，但拼写和实际支持的模型 ID 对不上。代码跑起来一切正常，直到请求打到 /responses 端点才被服务端拒绝，报错一看是 “The 'gpt-5.6-sol' model is not supported when using codex with a...”。模型名这种东西，在普通配置里没有任何人校验，等真正调用时才爆出来。

第二个：有人用环境变量控制“本地模型还是远端模型”，变量写成了 MODEL=L10CAL，字符串里多了一个数字，程序默默走了默认分支。用户连续好几天困惑为什么代码风格突然变了，最后才发现是环境变量里的一个字符错了。这种“静默降级”正是非 TypeSafe 决策模型最坑的地方——它不报错，不提示，只让你在行为异常里慢慢猜。

本文要做的三件事因此很清晰：把 Jev 本地跑起来，把 Codex 接上，再把“走本地还是走云端”这个决策用 TypeSafe 的方式固化下来。

2. 接入前的基础工程：本机部署 Jev，再把 Codex 调通过

2.1 Windows 上部署 Jev 的最小步骤

Jev 的部署在 Windows 上比较直接。项目发布包里一般自带打包好的可执行文件和模型权重，省去了自己装 Python 环境、配 CUDA 的折腾过程。最小步骤大致是：

1. 从项目官方 GitHub 仓库的 release 页面下载 Windows 安装包或解压包。
2. 找一个磁盘空间充足的目录解压，模型文件通常有几个 GB，建议放在 SSD 上。
3. 打开终端，执行启动命令，例如./jev serve --model jev-q4 --port 8080。
4. 用浏览器或 curl 访问一下基础地址，确认端口被监听。

启动之后，Jev 会提供一个本地 HTTP 服务，接口路径模拟 OpenAI 的格式。这样做的原因很实际：Codex 和大量现成工具都认识 OpenAI 兼容协议，不需要额外写适配层。实测下来可以用 curl 做个最基础的验证：

curl -X POST http://127.0.0.1:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"jev-model","messages":[{"role":"user","content":"hello"}]}'

如果返回的 JSON 里有choices[0].message.content，说明 Jev 服务已经待命。这里我建议第一次跑通时不要急着并发压测，先记录单请求延迟和吐字速度，后面调路由策略的时候要用到这些数据。另外提醒一句，模型文件名和启动命令里的 model 参数要保持一致，否则 Jev 可能起不来或者报权重加载失败。

2.2 Codex 的安装与登录注意点

Codex 的安装有桌面版和命令行 CLI 两种路径。命令行方式适合开发者，通常通过包管理器安装，装完在终端执行初始化命令，跟着走完登录流程即可。

登录之后要立刻做一件事：验证默认配置目录是否正确生成。Codex 的配置存放在用户目录下的 .codex 文件夹里，核心文件是 config.toml。如果这个文件不存在，不要手动瞎建，先跑一次初始化命令，让它自己生成模板，因为模板里的字段注释和默认值可以帮助你理解哪些配置项是合法的。

另一个容易忽略的细节是：Codex 对配置文件的解析是严格区分类型的。config.toml 里 model 字段应该是字符串，temperature 应该是浮点数，如果你把布尔值写成字符串，它启动时可能不报错，但运行中行为会很怪。这其实就是 TypeSafe 思想的最基本体现：配置即类型，类型即契约，字段不符合契约时，不要指望程序帮你兜底。

实测中，我习惯在改完 config.toml 后先执行一次最小命令，观察是否出现 “ignoring unrecognized configuration setting” 这类提示。出现这个提示，基本等于告诉你配置文件里有字段拼错了或者不认识了，按提示去核对即可。后面第 4 节我会展开讲这种问题怎么排查。

3. 方式一：OpenAI 兼容端点直连，最粗暴但也最有效

3.1 启动 Jev 兼容服务

方式一一句话就能说清：既然 Jev 对外暴露的是 OpenAI 兼容端点，Codex 又支持自定义模型提供者，那直接把 Codex 的 base_url 指向 Jev 的地址就好。

操作上，保持 Jev 服务运行在http://127.0.0.1:8080，然后打开 Codex 的 config.toml，新增一个本地 provider。以常见的配置格式为例：

[model_providers.jev] name = "jev" base_url = "http://127.0.0.1:8080/v1" api_key_env_var = "JEV_API_KEY"

这里的 API Key 是形式上的，可以设一个本地环境变量，值随意填，因为 Jev 通常不做严格鉴权。关键是 base_url 必须指向 Jev 暴露的 /v1 前缀，不能只写到根路径。我之前犯过这个错，只写了http://127.0.0.1:8080，结果 Codex 请求路径变成http://127.0.0.1:8080/responses，Jev 那边没有这个路由，直接 404。

3.2 Codex 侧指认模型名

配置好 provider 后，还要在 model 字段指认 Jev 的模型名。这里的模型名必须和 Jev 服务端注册的名字完全一致。我用的是jev-model，因为它在 Jev 的启动日志里能直接看到。

然后在 config.toml 里写：

model = "jev-model"

有些人会顺手写成model = "jev"或model = "local"，“看着差不多”就是这类坑的根源。在 TypeSafe 的视角下，模型名是一个枚举值，不是自由字符串，你该把当前可用的模型名当成一个有限的集合去对待。建议的做法是：从 Jev 启动时打印的模型 identifier 里复制粘贴，不要手打。

3.3 为什么这种配置自带一半 TypeSafe

直连方式虽然没有写一行决策代码，但它其实已经完成了 TypeSafe 的一半：

• base_url 是结构化的 URL，不是随手拼出来的字符串。
• 模型名是来自服务端的 identifier，经过实际验证。
• config.toml 本身是强类型配置文件，字段类型由解析器保证。

剩下那一半，只是缺少“运行时路由判断”。方式一默认所有请求都进 Jev，本地不可用时不会自动切换到 Codex 云端。所以它最适合场景单一、追求“一条通路跑到底”的情况。我实际把它用在一台完全离线的开发机上，所有 Codex 会话都走本地 Jev，省掉了 API 费用，也避免了代码跑到外部服务器。离线时候还能正常用，只要不涉及云端兜底场景就够了。

4. 方式二：把决策模型写成配置对象，路由规则全部显式化

4.1 用 TOML 字段做模型分配

方式一的问题在于没有决策。方式二就要把决策显式化——在 config.toml 里直接定义一套路由规则，把不同场景的路由值写清楚。Codex 本身支持多个 provider，可以通过配置让“常规问答走本地 Jev，重活走云端”。

在 config.toml 里我会放这样一段：

[model_routing] default = "jev-model" highload = "codex-gpt-oss-200" timeout_ms = 5000 allow_fallback = true

highload 字段代表需要更大上下文窗口或更强推理能力的场景。allow_fallback 表示本地响应超时后，是否允许切到云端。这份配置的可读性比方式一高很多——任何人打开文件，都能看懂“默认走本地，超时走云端”这套规则。

4.2 用 TOML 解析器把错误提前暴露

TypeSafe 落地的第一站就是 TOML 的类型系统。TOML 的 value 天生有类型，[model_routing]是一个 table，timeout_ms = 5000是整数，模型名是字符串。如果你在配置里写timeout_ms = "fast"，TOML 解析器直接抛类型错误，不会留到运行期。

第二步是加一层 schema 校验。哪怕是小型项目，我也推荐在启动时用一个模式校验函数去检查配置是否满足预期结构。以 TypeScript 生态为例，可以用 zod 定义 ConfigSchema：

import { z } from "zod"; const ModelRoutingSchema = z.object({ default: z.enum(["jev-model", "codex-gpt-oss-200"]), highload: z.enum(["codex-gpt-oss-200", "jev-model"]).optional(), timeout_ms: z.number().int().min(1000), allow_fallback: z.boolean(), }); const ConfigSchema = z.object({ model_providers: z.record(z.string(), z.object({ base_url: z.string().url(), api_key_env_var: z.string(), })), model_routing: ModelRoutingSchema, });

TOML 文件解析成 JavaScript 对象之后，经过 zod parse，任何多余字段、缺失字段、类型不匹配都会立刻抛出带路径的错误信息。这里带来的好处是：你改配置时不需要靠记忆，不需要翻文档，靠编译器和 schema 就够。proje配置错了，启动阶段就崩溃，而不是线上请求失败了才被发现。

4.3 遇到 “unrecognized configuration setting” 时怎么查

Codex 启动时会打印类似 “codex is ignoring 1 unrecognized configuration setting. check for typos” 的警告。这个警告本身就是在告诉你：这次配置没通过类型校验，但 Codex 选择忽略而不是崩溃。

我会劝大家不要直接忽略。第一步，先看警告里的字段名是什么，去和官方模板比对。第二步，检查是不是大小写问题，TOML 对字段名是大小写敏感的，Model和model是两个东西。第三步，确认值的类型，如果字段需要数组你却写了字符串，某些解析器会静默转成单元素数组，看不出来但行为已经变了。

有一次我遇到的就是这种情况：把model_providers写成了model_providerss，Codex 完全忽略，之后的请求全部落到默认模型上，现象非常隐蔽——命令能跑，结果不对。排查过程花了半小时，其实只要养成“改完配置先跑启动检查”的习惯，几秒就能定位。

5. 方式三：自建一个网关，把决策逻辑做成本地强类型模块

5.1 网关的整体结构

前两种方式都依赖 Codex 自身配置。方式三需要你动手写一个轻量网关服务，放在 Jev 和 Codex 之间，让所有请求统一从网关经过，再由网关按决策模型决定转发到 Jev 还是 Codex 云端。

结构大致是这样：Codex 把网关当作自定义 provider，base_url 指向网关地址。网关收到请求后，读取内部配置的决策模型，计算出该请求应该走哪条链路，再转发到 Jev 或 Codex 官方 endpoint，最后把原始响应返回给 Codex。

网关放在这里有一个明显好处：决策模型是代码，不是配置文件，你可以用真正的类型系统来约束它。这正是“TypeSafe 决策模型”字面意思的完整实现。

5.2 用判别联合 + Zod 实现 TypeSafe 路由决策模型

我实现时，核心数据结构是一个判别联合。所有可能的路由决策被定义为有限集合：

type RouteDecision = | { kind: "local"; provider: "jev"; model: "jev-model"; endpoint: "http://127.0.0.1:8080/v1" } | { kind: "cloud"; provider: "codex"; model: "codex-gpt-oss-200"; endpoint: "https://api.openai.com/v1" } | { kind: "fallback"; reason: "timeout"; from: "local"; to: "cloud" };

kind字段作为判别键，决定了该对象还有哪些字段可用。这样在写处理逻辑时，一旦拿到的对象 kind 是 local，TypeScript 编译器就会保证 endpoint 字段存在，而 model 字段的取值也被限制在联合类型里。只要 typecheck 通过，靠字符串拼路由的日子就结束了。

运行时校验交给 zod。为上述类型写一个对应的 schema，在网关进程启动时加载配置，用schema.parse校验一次。后续每个请求进来，先快速判断请求参数满足哪些条件，再得出路由决策。请求 payload 本身也要校验——乱传的字段不该导致网关崩溃。

5.3 网关如何同时对接 Jev 与 Codex endpoint

网关代码量其实不大。用 Node.js 的 HTTP 服务器就能承载，核心逻辑就三块：

1. 接收 Codex 转发来的请求，解析路径和 body。
2. 套用决策模型，计算出目标配置。
3. 把请求转发到目标端点，再回传响应。

需要注意的一点是路径兼容。Codex 实际调用的是 /responses 端点，而 Jev 比较标准的 OpenAI 兼容路径是 /v1/chat/completions（视版本也可能兼容 /v1/responses）。网关需要在转发时做路径映射：Codex 请求 /responses，网关如果路由到 Jev，就转换成 Jev 支持的路径；如果路由到 Codex 云端，保持 /responses 不变。

我用一个映射表把“Codex 对外路径 → 各 provider 内部路径”固定下来，避免在转发函数里到处都是 if-else：

const PATH_MAP: Record<string, Record<string, string>> = { "/responses": { "/jev": "/v1/chat/completions", "/codex": "/responses", }, };

转发部分的伪代码大致长这样：

const server = http.createServer(async (req, res) => { const body = await readBody(req); const decision = decide(body); // 返回 RouteDecision const target = resolveTarget(decision); const upstreamBody = mapPayload(body, decision); const upstreamRes = await fetch(target.endpoint + PATH_MAP["/responses"][target.provider], { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(upstreamBody), }); res.writeHead(upstreamRes.status, { "Content-Type": "application/json" }); res.end(await upstreamRes.text()); });

用这套代码，我同时打通了 Jev 和 Codex 云端两条链路。Codex 侧完全无感，它只知道自己请求的是一个提供者的 /responses 地址，网关在后端替它做了分发和路径翻译。

5.4 请求分类策略与配置热更新

决策模型除了类型安全，还得真正可配。我在网关里放了一个 policy.json，结构很简单：

{ "strategy": "latency-first", "localTimeoutMs": 3000, "rules": [ { "whenRequest": { "hasTools": true }, "target": "cloud" }, { "whenRequest": { "sessionEmpty": true }, "target": "local" } ] }

请求进来之后，网关先判断是否有工具调用需求，有就发云端，因为本地模型在工具调用上容易卡壳；没有工具调用且是空会话，就发本地 Jev，响应快、不花钱。每个请求都会把最终决策写入日志，观察一段时间后，能清晰看到本地命中率和云端兜底率。

配置热更新的做法是：网关监听 policy.json 的文件修改时间，变化后重新读入并用 schema 校验。这样你可以直接改策略文件，网关动态调整，不用重启进程。我拿这套网关跑了半个月，最直观的收益就是 API 账单降了一截——绝大多数轻量请求都被 Jev 本地消化了。

6. 真实踩坑回顾：从 “gpt-5.6-sol not supported” 到 “CC switch local proxy failed”

6.1 问题一：模型名写错导致 /responses 端点直接拒绝

最开始我在 Codex 配置里指认了一个看起来“很新”的模型名 gpt-5.6-sol，想着反正都是模型 ID，应该没问题。结果实际调用时，Codex 把请求发到 /responses 端点后，API 直接返回：

{"detail":"the 'gpt-5.6-sol' model is not supported when using codex with a ..."}

这个报错信息虽长，核心就一句话：模型名不在支持列表里。原因不外乎三种——拼写错误、模型 ID 并不是公开发布的、以及该模型名在当前场景下不可用。我逐一核对后确认，是我自己道听途说拼错了。

这个坑本质上就是“模型名未进入类型安全枚举”的典例。解决方式很简单：不管用什么模型，先查该 provider 的 models 接口，或直接看官方文档的支持列表，把 ID 原样复制。现在我的所有配置里，模型名一律从服务端获取或从文档复制，不再手打。

6.2 问题二：CC switch local proxy 在本地 Codex endpoint 上失败

第二个问题来自切换链路。为了管理多套 Codex 配置环境，我在用一个切换工具做配置切换，有一次执行切换后，Codex 进程的本地代理链路坏了。日志里出现：

cc switch local proxy failed while handling codex endpoint /responses. provi...

报错的直接原因是：切换动作改动了环境变量或代理连接参数，但 Codex 进程没有重新加载配置，导致 /responses 的请求被转发到一个已经不存在的本地服务上。更隐蔽的是，Codex 不会主动提示链路失效，它只是行为变得莫名慢，或者请求卡住超时。

排查链路是这样的。第一步，把终端里的相关环境变量全部打印出来，和当前 Codex 正在使用的值做对比。第二步，关掉切换工具，手工把 config.toml 里 provider 的 base_url 写回127.0.0.1:8080，验证基础链路。第三步，确认切换工具到底修改的是哪个文件——是改 config.toml 还是改环境变量，改完之后有没有进程重启机制。落到我这里，是工具只更新了环境变量，而 Codex 在启动时把环境变量固化成了内部值，改晚了就不生效，重启 Codex 进程才恢复。

6.3 排查这类问题的通用思路

遇到这类问题，我有一套固定打法，分享出来：

1. 先复现最小链路。把 Codex 的 provider 临时指到 Jev，用 curl 直接打一次 /responses，确认服务端是好的。
2. 分边定位。请求是从 Codex 出去坏的，还是到 Jev 才坏的——在网关或抓包日志里，看最后成功的那一跳。
3. 看配置加载时机。Codex 很多配置只在启动时读取，改了文件不重启就相当于没改。
4. 把字符串字段当成枚举。模型名、provider 名、端点路径，全部从可信源复制，不要手输。

这套思路贯穿了前面三种接入方式。所谓 TypeSafe，其实不只是类型系统的能力，更是这种“把变量变成可校验、可穷举、可追踪”的工程习惯。

7.1 一张表把三种方案看清楚

维度	方式一：端点直连	方式二：配置路由	方式三：网关强类型
改造成本	最低	低	中
决策能力	无，全量走 Jev	有，但依赖配置	强，逻辑可编程
TypeSafe 程度	半程	中	完整
适用场景	离线开发、单一模型	轻量分流、团队统一	多 provider、动态策略
维护难度	基本不用维护	靠配置文件规范	需要维护一段代码

这张表是我的实际感受，不是从文档里抄来的理论对比。方式一全量走本地，没有决策成本，但也没有保险；方式二适合“规则固定、变化少”的团队环境，配置一目了然，新人上手也快；方式三前期要写代码，但一旦上了这套网关，后面的路由调整、故障切换、审计日志都是可编程的，边际成本反而低。

7.2 我的选择建议

如果让我给一个可以直接抄作业的结论：常规开发机用方式二，复杂项目用方式三，方式一保留为验证手段。

方式二能覆盖 80% 的场景。你在 config.toml 里写好几个 provider、定好默认模型和超时时间，团队里的人不需要理解判别联合和 zod，也会改配置。

需要复杂策略的时候就启用方式三的网关，因为写进代码的决策模型可以做工具调用分流、超时兜底、日志审计这些配置表达不了的事。我现在的主力开发环境就是这样的：轻量问答走本地 Jev，带文件编辑和命令执行的重活走云端 Codex，中间全部通过网关里的强类型路由来控制。

方式一也不是没用。它是最快验证 Jev 部署是否正常的手段，也是完全离线环境下的保底方案。我偶尔还会把它当作网关出问题时的临时逃生通道——直接把 Codex 指回 Jev，先恢复可用，再去修网关。

最后分享一个个人习惯：无论用哪种方式，我都会先把 Jev 的单次请求延迟和 Codex 云端的网络往返时间记下来，之后所有 routing 策略都以这两个数作为基准。自己搭的链路，别指望别人帮你测；先测后配，才能让 TypeSafe 决策模型在踩坑之前就把问题挡在门外。