jev-codex-router：为Codex按轮次动态路由模型与推理深度

0xNatoshi/jev-codex-router

{"state":{"goal":"open the docs"},"questions":{"next":{"type":"choice","instructions":"Which element advances the goal?","criteria":{"e5":"link Documentation"}}}}

#→ {"model":"jev-1.13.0","answers":{"next":{...}},"usage":{...},"ms":612}

校验就是整个契约：一个可 JSON 序列化（JSON-serialisable）的状态，字符数不超过 120k，问题最多 40 个，每个问题是 noul、choice 或 score 类型，并附带各自的 instructions 和 criteria。调用方的状态永远不会被记录（logged）。

... 暴露一次上游 Jev 故障 ， ... 表示 TypeSafe 账户额度已用尽 ， 而 ... 表示未配置 key。

仓库布局

- BACKTEST.md ， 节约方案回测：协议说明、表格、局限性（即"证据"）
- AGENTS.md ， 自治安装与运维手册（供 AI agent 使用）
- poc/ ， 分层 POC、影子回放（shadow replay）以及回测工具
- server/ ， 在线服务及其安装脚本（实际运行的部分）
- hook/ ， 探索过的替代方案（LiteLLM callback tap）， 保留作为参考

快速上手

前置条件：macOS，已安装 Codex 桌面端并接入 Codex Router（用 bin/codex-router 检出），Python 3.11+，以及一个 TypeSafe API key（Jev）。

1. 把 TypeSafe key 提供给服务， 要么在服务环境中 export TYPESAFE_API_KEY=...，要么：

echo 'TYPESAFE_API_KEY=your-key' >> ~/.hermes/.env   # 默认环境文件
# 用 JEV_ENV_FILE=/path/to/env 可以覆盖路径

2. 启动服务（前台测试）

python3 server/jev_server.py
curl -s http://127.0.0.1:4319/health

3. 向 Codex Router 注册

cd <codex-router checkout>

# 启用 chatgpt 会话
./bin/codex-router chatgpt-session enable

# 声明通用 provider（我们的本地服务，使用原生 Responses 格式）
./bin/codex-router providers generic add jev \
    --name "Jev Router" \
    --base-url http://127.0.0.1:4319/v1 \
    --adapter openai-responses \
    --allow-private

# 声明模型：~/.codex/codex-router/user-models.json
# （此文件为本地状态 ， router 的更新不会触碰它）
{
  "version": 1,
  "models": [
    {
      "slug": "jev/auto",
      "gatewayModel": "jev-auto",
      "compHash": "jev-auto-user-v1",
      "upstreamModel": "auto",
      "provider": "jev",
      "listed": true,
      "displayName": "Jev Codex Router",
      "description": "Auto-routing by Jev: every turn is classified and served by luna, terra, sol or astra at the thinking depth it needs.",
      "priority": 1,
      "defaultEffort": "medium",
      "reasoningLevels": [
        {"effort": "low",    "description": "Quick reasoning"},
        {"effort": "medium", "description": "Balanced reasoning"},
        {"effort": "high",   "description": "Deep reasoning"},
        {"effort": "xhigh",  "description": "Extended reasoning"},
        {"effort": "max",    "description": "Maximum reasoning"}
      ],
      "contextWindow": 400000,
      "autoCompact": true,
      "searchTool": {"mode": "hosted"},
      "supportsSearchHistory": true,
      "inputModalities": ["text", "image"]
    }
  ]
}

# 发布目录，让模型在选择器中可见
./bin/codex-router refresh-catalog
./bin/control picker set jev/auto show

4. 退出并重启 Codex，然后在模型选择器中挑选"Jev Codex Router"。

同时核对传输方式以及选择器：jev/auto 必须命中本地 router，而非 OpenAI 的原生端点。仅靠目录条目或 [model_providers.jev] 声明本身，并不会选定这种传输方式。

如果 Codex 报告 jev/auto 在 ChatGPT 账户下不受支持，请参阅传输故障排查（transport troubleshooting）。

5. 设为永久生效（可选但推荐）：在你自己终端中运行服务安装脚本（受监管的 agent 内有意限制了 launchd 管理权限）：

bash server/install-service.sh

若不执行此步骤，server/watchdog.sh（每 5 分钟一次的 cron）会在服务停止响应时将其重启。

运维

| 动作 | 命令 |
| --- | --- |
| 查看路由决策 | tail -f ~/.codex/codex-router/jev-router-live.jsonl |在会话中查看所选模型：每个推理摘要片段的两侧各带一个路由标记作为分隔符：

· 🧠sol:low ·每种路由对应一个图标：

- ⚡ luna（经济型）
- 🧠 sol（主力机型）
- 🚀 astra（前沿）
- 🌍 terra由 Codex-dry 协同提供服务时：

- 🐳 deepseek
- ✨ glm