Codex + MiniMax 集成实战手册
2026-07-29 修复实战:Codex 0.145.0 ↔ Hermes Gateway 1.x ↔ MiniMax-M3
背景
渔芯 Agent 生态让 Codex CLI(OpenAI 的 coding agent)通过 Hermes Gateway(本地 LLM 代理)调用 MiniMax-M3(国内大模型)。Codex 默认是为 OpenAI Responses API + GPT-5 设计的,跟 MiniMax(OpenAI Chat Completions 兼容)之间需要多层翻译。
已修复的 8 个核心 Bug
Bug 1: "Model metadata for MiniMax-M3 not found"
症状:Codex 启动时打印警告 Defaulting to fallback metadata; this can degrade performance and cause issues
根因:~/.codex/cc-switch-model-catalog.json 里只有 MiniMax M2.7 条目,没有 M3
修复:在 catalog 追加 MiniMax-M3 条目(基于 M2.7 复制 + 改 slug/display_name/description)。注意 catalog 文件会从 ~31KB 翻倍到 ~92KB
Bug 2: Codex 不显示 reasoning
症状:Codex 输出 reasoning summaries: none
根因:~/.codex/config.toml 缺 model_reasoning_summary 字段
修复:加 model_reasoning_summary = "auto"
Bug 3: function name is empty (2013)
根因:translate_responses_to_chat 把 tools 字段在最后一段字段过滤时删掉了 + Codex 14 个工具里 12、13 是 deferred(name: null)
修复:
- keep 列表里加
("tools", "tool_choice", "parallel_tool_calls", "user", "metadata") - 翻译 tools 数组时过滤 name 为 null/空 的工具(Codex deferred tools)
- 自动补
tool_choice = "auto"
Bug 4: Codex 收不到工具调用事件
根因:MiniMax 收到没有 tools 字段的请求后 fallback 到 content 字段写 JSON + chat template 标记 <|minimax|><|tool_call|>
修复:同 Bug 3 — 传正确的 tools 字段
Bug 5: 多轮对话第二轮 400
根因:translate_responses_to_chat 没分类处理 Codex Responses API 的多轮消息类型:
type: "function_call_output"→ 应翻译成 OpenAIrole: "tool"+tool_call_idtype: "function_call"→ 应翻译成role: "assistant"+tool_calls[]
修复:重写 translate_responses_to_chat 的消息循环,分三类处理
Bug 6: gzip 解压错误 incorrect header check -3(豆包报告)
根因:MiniMax 网关处理 Accept-Encoding 容错差,响应头偶尔标记 gzip 但实际返回裸文本
修复:sse_stream_response 的 req_headers 构造里跳过 accept-encoding,并显式置 Accept-Encoding: identity
Bug 7: 长任务 stream disconnected(豆包报告)
根因:MiniMax 长思考阶段不发 SSE 心跳包,120s 空闲阈值到 → 服务端断流 → Codex 报 disconnect
修复:Gateway 主循环用 asyncio.Queue + feeder task 实现 SSE 心跳,每 20s yield : keepalive\n\n(SSE 注释行不影响 Codex 解析)
Bug 8: MiniMax 不识别 OpenAI 扩展参数(豆包报告)
根因:frequency_penalty / presence_penalty / logprobs / top_logprobs 让 MiniMax 流异常中断
修复:normalize_model_name 检测到 minimaxi.com 后端时过滤这些字段
OpenAI Responses API vs Chat Completions 字段映射
| Responses API 字段 | Chat Completions 字段 | 备注 |
|---|---|---|
input: "string" |
messages: [{role: user, content}] |
单轮 |
input: [items] |
messages: [...] |
多轮 |
input[] type message |
messages[] type {role, content} |
普通消息 |
input[] type message role developer |
messages[] role system |
角色映射 |
input[] type function_call_output |
messages[] {role: tool, tool_call_id, content} |
工具结果 |
input[] type function_call |
messages[] {role: assistant, content: null, tool_calls[]} |
助手工具调用 |
max_output_tokens |
max_tokens |
字段重命名 |
stream_options |
(删除) | |
tools[].type=function |
tools[].type=function |
同结构 |
tools[].function.{name,description,parameters} 顶层 |
嵌套 tools[].function.{...} |
Codex Responses API 把 function 字段拍平到顶层! |
parallel_tool_calls |
同 | 直传 |
Codex Responses API 工具 schema(实测)
Codex 0.145.0 的工具定义是拍平格式(name/description/parameters 在 tools[] 顶层,不在 function 字段内):
{
"type": "function",
"name": "exec_command",
"description": "Runs a command in a PTY...",
"strict": false,
"parameters": {"type": "object", "properties": {...}}
}
但 OpenAI Chat Completions 要求嵌套:
{
"type": "function",
"function": {
"name": "exec_command",
"description": "Runs a command in a PTY...",
"strict": false,
"parameters": {"type": "object", "properties": {...}}
}
}
翻译代码必须兼容两种格式(先看 function 嵌套,没有则用顶层字段)。
Codex 14 个默认工具(其中 2 个 deferred)
实测 Codex 0.145.0 发 14 个工具定义,其中 12、13 是 deferred tools(Codex 客户端在 tool call 时动态填充):
| Index | Tool | Name | 状态 |
|---|---|---|---|
| 0-11 | exec_command, edit_file, apply_patch, view_image, ... | 有效 name | ✅ 翻译 |
| 12 | Tool discovery (BM25 search over deferred tools) | null |
❌ 过滤 |
| 13 | (空) | null |
❌ 过滤 |
任何 name: null/空 的工具都必须过滤,否则 MiniMax 返回 400。
Codex 0.145 不支持的配置(豆包步骤 2 无效)
stream_idle_timeout_ms = 90000 # ❌ 不支持
stream_max_retries = 3 # ❌ 不支持
request_timeout_ms = 180000 # ❌ 不支持
Codex 0.145.0 binary 里搜不到这些字段。这些都是 Codex 假设的配置,实际只支持 model_reasoning_effort、model_reasoning_summary、approval、sandbox 等。
Gateway SSE 翻译层(llm_gateway.py 关键函数)
| 函数 | 作用 |
|---|---|
translate_responses_to_chat() |
请求体:Responses API → Chat Completions(含 tools 翻译、deferred 过滤、多轮消息分类) |
normalize_model_name() |
模型名 + MiniMax 专属参数过滤(frequency_penalty 等) |
***SECRET***/done |
推理 item 创建/关闭 |
***SECRET*** |
response.reasoning_summary_text.delta(MiniMax 用 <think>... 标记 or reasoning_content 字段) |
build_sse_function_call_added/done |
工具调用 item |
***SECRET***/done |
工具参数(OpenAI 流式分块累积) |
sse_stream_response() |
主循环:状态机维护 reasoning/content/tool_calls + content_buf 防跨 chunk + SSE 心跳(20s/次) |
关键修复代码片段
1. sse_stream_response 跳过 Accept-Encoding
skip = {"host", "content-length", "connection", "transfer-encoding",
"accept", "accept-encoding"}
req_headers["Accept-Encoding"] = "identity"
2. normalize_model_name MiniMax 专属参数过滤
if "minimaxi.com" in url:
for k in ("frequency_penalty", "presence_penalty", "logprobs", "top_logprobs"):
body_json.pop(k, None)
3. SSE 心跳(防 120s 断流)
HEARTBEAT_INTERVAL = 20
async def feed_queue():
async for chunk in resp.content.iter_any():
await queue.put(chunk)
await queue.put(None)
queue = asyncio.Queue()
feeder = asyncio.create_task(feed_queue())
while True:
try:
chunk = await asyncio.wait_for(queue.get(), timeout=HEARTBEAT_INTERVAL)
except asyncio.TimeoutError:
yield b": keepalive\n\n" # SSE 注释行
continue
if chunk is None:
break
注意:finally 块要清理 feeder task 避免后台挂着。
验证脚本(避免回归)
# 1) Catalog 完整性
python3 -c "
import json
cat = json.load(open('/Users/hua/.codex/cc-switch-model-catalog.json'))
slugs = [m['slug'] for m in cat['models']]
assert 'MiniMax-M3' in slugs, 'MiniMax-M3 missing in catalog'
print('OK catalog:', slugs)
"
# 2) Gateway 启动 + 后端
curl -sS http://127.0.0.1:18888/health | python3 -m json.tool | grep minimax
# 3) Codex 真实多轮任务(应无 ERROR: Reconnecting)
cd /tmp && codex exec --sandbox danger-full-access --skip-git-repo-check \
"Run shell command: date && echo TEST. Then tell me the date."
# 4) Gateway log 应无 HTTP 400 / incorrect header / Reconnecting 警告
tail -30 /Users/hua/.hermes/logs/llm_gateway_stderr.log | grep -E "400|incorrect|Reconnecting"
⚠️ 陷阱:codex exec 在非 git 目录报 "Not inside a trusted directory"
codex exec 默认只信任 git 仓库目录。在非 git 项目目录(实测 /Users/hua/6-产品研发/33-初创者)直接跑会立即退出:
Not inside a trusted directory and --skip-git-repo-check was not specified.
修复:加 --skip-git-repo-check。先判断目录是否 git 仓库再决定:
git -C /path/to/project rev-parse --is-inside-work-tree 2>&1
# 返回 "fatal: not a git repository" = 非 git 目录,codex exec 必须加 --skip-git-repo-check
cd /path/to/project && codex exec --sandbox workspace-write --skip-git-repo-check "$(cat /tmp/task.txt)"
渔芯的
6-产品研发/下很多项目不是 git 仓库(如 33-初创者),在这些目录里 delegate 给 codex 时都会踩到;用--sandbox workspace-write(让 codex 能写文件)+--skip-git-repo-check组合即可。
ZAI/智谱链路速查(2026-08-29 新增)
华哥口语"恢复 zai"= 恢复 Codex→智谱链路。当前实链路:codex 0.148 → CC Switch 代理(127.0.0.1:15721) → open.bigmodel.cn。排查配方、假成功识别(代理 200+0tokens)、1113 余额不足 根因、DeepSeek 兜底切换,见 references/codex-zai-chain-diagnosis.md。
关联
references/codex-desktop-crash-loop.md— Codex 桌面端(ChatGPT.app)崩溃循环 + config.toml 被桌面端重写 + 降级不可行(OpenAI 无旧版 DMG);含 8/29 线程爆炸锁死新病(320线程__ulock_wait卡死,与 PiP 风暴无关)+ .ips 分诊配方 + guard 熔断references/codex-deepseek-direct-cleanup.md— 只保留 DeepSeek 直连(华哥 8/20 定调):清理其它模型接入的完整文件清单 + 步骤 + CC Switch.app 根因 + 防复发选项references/codex-session-recovery.md— Codex 跨会话失忆诊断 + sessions 历史恢复(~/.codex/sessions/*.jsonl提取用户/助手消息)+ 固化上下文到项目 AGENTS.mdreferences/chrome-extension-reinstall.md— ChatGPT for Chrome 扩展丢失诊断 + 为什么无法自动装(Chrome 136+ 堵死 AppleScript JS/CDP/External Extensions)+ 手动重装四步yuxin-llm-402-diagnosis— 通用 LLM API 错误诊断方法(401/402/404/429)hermes-gateway-profile-ops— Gateway 路由 + profile 运维multi-cloud-llm-architecture— 多 LLM provider 架构minimax-embedding-api— MiniMax embedding API(em bo1 + texts + type)
反模式(不要做)
- ❌ 看到 "Model metadata not found" 就改 Codex config — 90% 是 catalog 没条目
- ❌ 在 Gateway 加一层 custom "Codex adapter" — 应在通用 Chat Completions 层处理 tools 翻译
- ❌ 让 Codex 用户每次手动指定
--model MiniMax-M3— 应该 config 默认就指向 catalog slug - ❌ 把 Codex AGENTS.md 的工具名(如
exec)硬编码到 prompt — Codex 实际用exec_command,名字会变 - ❌ 配置 Codex
stream_idle_timeout_ms— Codex 0.145 不支持,得在 Gateway 层做心跳 - ❌ 转发 Codex 请求时保留
Accept-Encoding: gzip— MiniMax 有解压 bug - ❌ 转发 Codex 请求时保留
frequency_penalty等 OpenAI 扩展参数 — MiniMax 不识别 - ❌ 看到 Codex 界面模型名变成
hermes_gateway就以为 model 被改了 — 那是[model_providers.custom].name的显示名,真正的开关是model_provider字段
Codex CLI 位置 + $HOME 隔离陷阱 + 诊断链(2026-08-23 / 2026-09-01 实测)
⚠️ codex CLI 安装形态会随版本反复横跳(不要假定唯一入口)
- 0.148(2026-08):CLI 不再是 npm 安装。真实路径 =
/Applications/ChatGPT.app/Contents/Resources/codex(macOS 无timeout命令,别用它包 codex)。 - 0.152.0(2026-09-01 重装实测):
npm install -g @openai/codex重新有效——CLI 装回~/.local/bin/codex(指向~/.local/lib/node_modules/@openai/codex/bin/codex.js)。别假设只有一个有效入口,先command -v codex或ls ~/.local/bin/codex /Applications/ChatGPT.app/Contents/Resources/codex 2>/dev/null再决定调哪个。 - 判断顺序(cron / 调试脚本里别盲信任何一处):
command -v codex→ 有就用(前置export PATH="$HOME/.local/bin:$PATH")- 没有 →
ls /Applications/ChatGPT.app/Contents/Resources/codex - 都没有 →
npm install -g @openai/codex装回 npm 端
- 路径列表会骗人:
ls -la ~/.local/bin/codex显示 symlink 存在 ≠ 能跑(可能 broken symlink,详见下面「CLI broken symlink」补充节)。真正能跑要看codex --version返回版本号,不是看 symlink。 - 裸
codex命令在 cron / 非交互 shell 下大概率找不到:用户登录 shell 通常把~/.local/bin写进 PATH,cron 不继承。脚本里永远用绝对路径或export PATH="$HOME/.local/bin:$PATH" && codex ...,别靠 shell 自动解析。
首次安装 / 完全没装过 codex 时的 bootstrap 流程(2026-09-01 实测)
如果 cron 报 codex: command not found(且不是 PATH 问题),说明本机根本没装 codex:
# 1. 安装(npm 全局,自动落到 ~/.local/bin/codex)
npm install -g @openai/codex
# 2. 验证
export PATH="$HOME/.local/bin:$PATH" && codex --version
# 3. 不要急着跑 plugin add —— 0.152 第一次 plugin list 会显示 48 个 curated 全部 not installed,
# 但 marketplace 已注册;OPERATIONS.md 里记的"已装 N 个插件"会被这次 bootstrap 整体清零。
# 4. 同步走 ~/.hermes/scripts/codex_github_sync.sh(自动重新生成 STATUS.md / plugins.json,反映 0 安装真状态)
判定是"刚装"还是"早装后坏了":
~/.codex/config.toml不存在 +~/.codex/plugins/cache/openai-api-curated/不存在 → 首次 bootstrap- 上面两个存在但
codex --version失败 → CLI 损坏但配置在,重装 npm 即可(不删~/.codex/,里面是真实状态数据:OPERATIONS.md / auth.json / sessions/)
⚠️ cron 任务简报里的脚本路径陷阱(反复出现,2026-08 / 09 两次)
任务简报里写的 ~/6-产品研发/22-出图智能体训练/sync_codex_repo.sh 不存在(路径下只有 historical_data/ 子目录)。永远不要按字面跑这条路径:
- 真实同步脚本 =
~/.hermes/scripts/codex_github_sync.sh(hourly cron 包装,内部exec python3 codex_self_evolution.py --sync-only,自动 pull → 脱敏拷贝 → commit → push 到git@github.com:openclaw-cn-dev/yuxin-skills.git → codex/)。 - 旧
sync_codex_repo.sh是已弃用产物(详见下方陷阱 4),但 cron 简报 / 文档 / AGENTS.md 历史版本里反复引用它——遇到就替换为codex_github_sync.sh,不要花时间修它。
⚠️ $HOME 被 profile 重定向(改错文件的头号根因)
Hermes profile 会话里 $HOME 被重定向到 ~/.hermes/profiles/<name>/home,所以 ~/.codex 解析到 profile 隔离目录,不是真玉芬的 /Users/hua/.codex。
- 改 codex 全局配置前必先
echo $HOME确认;否则~/.codex/config.toml改的是 profile 镜像(如 zhenglishi 的),真玉芬的没动。 - 真玉芬(default)配置永远在
/Users/hua/.codex/config.toml,读写用绝对路径。 - 误改了 profile 镜像要撤销:删误备份 +
diff确认未污染。 - 验证
codex exec同样要加HOME=/Users/hua前缀:cd /tmp && HOME=/Users/hua /Applications/ChatGPT.app/Contents/Resources/codex exec --skip-git-repo-check "..."。不加的话 codex 读的是 profile 镜像的~/.codex/config.toml(如 zhenglishi 的 18888 豆包配置),provider:显示错误、验证结论误导。本机实测HOME=/Users/hua下正确显示provider: deepseek+tokens used: 2,575。 - patch/脚本报「0 matches」先重读再动手:多 agent 并发环境里 config.toml 可能已被 CC Switch / 另一会话 / 华哥手动改掉。「0 matches」往往不是字符串写错,而是文件已经变了——先
read_file看当前真实内容再决定,别盲目重试或硬改。 import tomllib要 3.11+:本机/usr/bin/python3是 3.9.6(无 tomllib,报ModuleNotFoundError)。跑含 tomllib 的验证脚本用/Users/hua/.hermes/hermes-agent/venv/bin/python(3.11)或python3.11。
CC Switch 的 key 存在 SQLite,不在 config.toml
华哥用 CC Switch 切 codex 大模型时,provider/key 存在 ~/.cc-switch/cc-switch.db(表 providers,列 settings_config JSON 含 auth.OPENAI_API_KEY):
sqlite3 ~/.cc-switch/cc-switch.db "SELECT name,is_current FROM providers WHERE app_type='codex';"
sqlite3 ~/.cc-switch/cc-switch.db "SELECT json_extract(settings_config,'$.auth.OPENAI_API_KEY') FROM providers WHERE app_type='codex' AND is_current=1;"
⚠️ key 其实也镜像在 .codex/auth.json(更易读,且能避开敏感数据 guard)
2026-08-23 实测:CC Switch 切模型时,除了写 config.toml 的 [model_providers.custom] 段(experimental_bearer_token = "PROXY_MANAGED"),还会把 key 写到 .codex/auth.json 的 OPENAI_API_KEY(形如 sk-d06...4a03,35 位 = "sk-" + 32 hex)。所以修直连时不必读 SQLite —— 直接读 auth.json。
- ❌ 别用
sqlite3 ... SELECT settings_config ... | python3抽 key:会触发 Hermes 敏感数据 guard,命令被 BLOCKED("Command timed out without user response... Silence is not consent"),且明确禁止"换个命令重试同一结果"。 - ✅ 正确做法:写一个脚本读 auth.json 的 key → 注入 config.toml 的
experimental_bearer_token,key 全程脚本内部流转、绝不打印;校验只打len==35+startswith('sk-')+tok == auth_key这类长度/布尔,不打印 key 片段。 - ⚠️ $HOME 陷阱:profile 会话(如 zhenglishi)里
$HOME被重定向,~/.cc-switch/和~/.codex/都会解析到 profile 隔离目录而报 "unable to open database"。读写一律用绝对路径/Users/hua/.cc-switch/cc-switch.db、/Users/hua/.codex/auth.json、/Users/hua/.codex/config.toml。 - ⚠️ tomllib 陷阱:profile 会话的
python3可能是 3.9.6(无tomllib,3.11+ 才有)。TOML 校验脚本若import tomllib会直接 ModuleNotFoundError——但注意脚本可能已在 import 之前把 config 写盘了(校验失败 ≠ 修复失败)。校验改用toml库 / 正则 / 或先python3 -c "import tomllib"探测。
修复脚本模板(读 auth.json 注入 key,不打印)
import json, shutil, datetime
CODE="/Users/hua/.codex/config.toml"; AUTH="/Users/hua/.codex/auth.json"
shutil.copy2(CODE, f"{CODE}.bak-{datetime.datetime.now():%Y%m%d-%H%M%S}-deepseek-direct")
key=json.load(open(AUTH))["OPENAI_API_KEY"]
new=open(CODE,encoding="utf-8").read()
new=new.replace('model_provider = "custom"','model_provider = "deepseek"')
new=new.replace('model_catalog_json = "/Users/hua/.codex/cc-switch-model-catalog.json"','model_catalog_json = "/Users/hua/.codex/models.json"')
old='[model_providers]\n[model_providers.custom]\nname = "deepseek"\nbase_url = "http://127.0.0.1:15721/v1"\nwire_api = "responses"\nrequires_openai_auth = true\nexperimental_bearer_token = "PROXY_MANAGED"\n'
newb=f'[model_providers.deepseek]\nname = "deepseek"\nbase_url = "https://api.deepseek.com/"\nwire_api = "responses"\nexperimental_bearer_token = "{key}"\n'
assert old in new; new=new.replace(old,newb)
open(CODE,"w",encoding="utf-8").write(new)
# 校验只打长度/布尔
import re; tok=re.findall(r'experimental_bearer_token = "([^"]+)"',new)[-1]
print(len(tok)==35, tok.startswith("sk-"), tok==key, "15721" not in new, "PROXY_MANAGED" not in new)
端到端验证(profile 会话必须显式 HOME/CODEX_HOME,否则 codex 读错 config):
cd /tmp && HOME=/Users/hua CODEX_HOME=/Users/hua/.codex \
"/Applications/ChatGPT.app/Contents/Resources/codex" exec --skip-git-repo-check --sandbox read-only \
"运行 shell 命令 date 获取当前日期,然后只回复两个字:完成" 2>&1 | tail -30
# 期望:provider: deepseek + tokens used > 0 + 无 Reconnecting/404/超时
诊断链("codex 跑不通 / 模型不对")
按顺序,别跳步:
codex login status+codex doctor(看 auth / reachability /default model provider/model)- 看
config.toml的model_provider+base_url(CC Switch 切过就是custom+127.0.0.1:15721) curl https://api.deepseek.com/v1/chat/completions(带 key)→ HTTP 200 = key 有效curl http://127.0.0.1:15721/v1/models→ 404 = CC Switch 代理没转发(codex 超时的根因)- 结论:key 有效但代理坏 → 让 codex 直连
api.deepseek.com绕开代理
⚠️ 关键教训:华哥「配好了」≠ CLI 能跑
华哥说「给 codex 配好 deepseek、桌面端打开了」时,桌面端 GUI 能显示 ≠ CLI 侧能跑。实测 codex exec 超时 300s,根因是 CC Switch 代理 /v1/models 404。必须先 curl 直连 vs curl 代理实测再下结论,别被「已配好」误导——华哥口述状态常与实际 config 不符(memory 已记"口述可能口误需交叉验证")。
Codex 模型路由三要素(2026-08-14 实测)
✅ 当前正确状态(2026-08-20 华哥拍板):Codex 只保留 deepseek 直连——
model_provider="deepseek"、唯一 provider 段[model_providers.deepseek](base_url=https://api.deepseek.com/、tokensk-4cc…)、model_catalog_json="~/.codex/models.json"(仅 deepseek-v4-flash/pro)。已移除 minimax/custom 段。以后诊断「codex 模型不对」先比对这三项,别再把 codex 切回 MiniMax(15721 代理已停)。
⚠️ 2026-08-23 更新:CC Switch 又把
model_provider=custom+base_url=127.0.0.1:15721塞回来了(覆盖了 8/20 的直连),且 15721 代理/v1/models404 导致 codex CLI 超时。华哥用 CC Switch 切模型是长期习惯,不能假设「config 永远是 deepseek 直连」——每次诊断先实测model_provider/base_url当前值 + curl 代理是否转发(详见上文「诊断链」)。
⚠️ 2026-08-28 更新(智谱套餐接入,覆盖 8/20「deepseek 直连 only」定调):华哥购买智谱个人 pro 包月套餐后,Codex 已切到智谱直连——
model_provider="ZAI"+[model_providers.ZAI](base_url=https://open.bigmodel.cn/api/v1、wire_api="responses"、experimental_bearer_token=<智谱套餐key>),实测回复正常。旧「只保留 deepseek」定调已过时;华哥口述"codex 忘了模型"类问题时先比对这三项当前值。峰谷调度 cronb4bebba0ed5a(switch_work_model.py)已暂停——包月套餐不按 token 计费,峰谷切换失去意义且会把智谱端点配出 deepseek 模型名的必报错组合。端点矩阵详见hermes-config-safe-editskill 的「智谱 Coding Plan 端点矩阵」节。⚠️ 2026-08-29 修正:模型名应为
model = "glm-5.3"(8/28 配的glm-5.3-flash该 key 无权限,从未真正调通)。CC Switch 重启后会把 provider 改回 custom+15721 并删 ZAI 段(8/26、8/29 两次),一键修复python3 ~/.hermes/scripts/fix_codex_config_zai.py。详见references/codex-zhipu-cutover-20260828.md的 8/29 更新节。
config.toml 里三个字段各管各的,混了就会出现"模型名变奇怪":
| 字段 | 作用 | 例 |
|---|---|---|
model_provider = "<key>" |
真正生效的 provider([model_providers] 下的 key) |
"custom" / "deepseek" |
model = "<slug>" |
模型 slug(必须匹配 models.json catalog) |
"deepseek-v4-flash" |
[model_providers.<key>].name |
Codex 界面/App 上显示的"模型名" | "hermes_gateway" / "deepseek" |
症状 "大模型变成 hermes_gateway"
华哥看到 Codex 界面模型名变成 hermes_gateway,不是 model 被改了,而是生效的 provider 是 custom、且它的 name 字段叫 hermes_gateway:
model_provider = "custom" # 生效的是 custom 这个 key
[model_providers.custom]
name = "hermes_gateway" # ← 界面显示的是这个 name
base_url = "http://127.0.0.1:18888/openai" # 走本地 LLM Gateway(18888)
修法(一条改动):把 model_provider 从 "custom" 改成直连 provider 的 key("deepseek"),model 字段不动:
model_provider = "deepseek" # 直连 api.deepseek.com
model = "deepseek-v4-flash" # 不变,时段调度 cron 管
直连 DeepSeek 可行性(实测 2026-08-14)
[model_providers.deepseek] 直连 https://api.deepseek.com/、wire_api = "responses" 完全可用:
GET /models返回deepseek-v4-flash+deepseek-v4-proPOST /responses和/v1/responses都正常(Codex 的 responses 协议,无需经过 Gateway 翻译)
验证方式:用
tomllib读~/.codex/config.toml取[model_providers.deepseek].experimental_bearer_token,直接 curl/models+/responses确认端点通,再切 provider,避免把一个坏的换成另一个坏的。
⚠️ DeepSeek 直连 only(2026-08-20 华哥定调)
华哥 8/20 明确:Codex 只保留 DeepSeek 直连,其它所有大模型接入方式全部清理(MiniMax 代理、豆包/火山 Ark、OpenAI key、CC Switch 目录)。这是长期定调,后续维护不要再引入/恢复非 deepseek 接入。
~/.codex是软链 →/Users/hua/系统文件夹/Codex(patch/read 的 resolved_path 会显示真实路径,属正常)- 唯一正确形态:
[model_providers.deepseek]直连 +models.json只留 deepseek 两个 slug + 无[model_providers.custom] - 元凶除了桌面端 ChatGPT.app,还有 CC Switch.app(
/Applications/CC Switch.app)——它维护cc-switch-model-catalog.json,切换时把model_provider/model/model_catalog_json重写,把127.0.0.1:15721的 minimax 塞回来
完整清理步骤 + 文件清单 + 防复发选项 → references/codex-deepseek-direct-cleanup.md
与 switch_work_model.py 时段调度的关系
switch_work_model.py(cron b4bebba0ed5a,8/17 起)只改写 model = 那一行(工作时段 flash / 非工作 pro),不碰 model_provider。所以手动切 provider 与时段调度互不干扰,切 provider 时 model 保持原样即可。
Weekly Evolution Cron 实战陷阱(2026-08-03 巡检)
每周末跑的 codex_self_evolution.py(或类似 cron)会触发的 3 个易踩点:
⚠️ 陷阱 1:AGENTS.md 自我保护 vs 外部 cron 简报的"优化"要求
AGENTS.md Section C 明确把 ~/.codex/ 列为受保护路径(不可删除/覆盖)。但 cron 简报又显式要求"AGENTS.md 优化"(step 4)。两条指令天然冲突。
解法(2026-08-03 实测通过):
read_file拿到完整 AGENTS.md,定位要改的章节(绝大多数情况只是"当前配置"这一节)- 检查 AGENTS.md 自身的 Section F(变更前奏):"<5 行/单文件 直接执行" — 当前配置节刷新通常就 4-5 行内(版本号、模型、base_url)
- 用
patch工具只动"当前配置"这一节,不碰权限/规则章节 - 如果涉及 Section A-I 任意一节,必须停下来等华哥确认 — 那已是规则本身,不在 cron 自主改动范围
反模式:为了一次性"对齐"AGENTS.md,去大刀阔斧改 Section A-I — 这等同让 cron 偷偷改了 Codex 的运行时安全规则,必须严守。
⚠️ 陷阱 2:Codex 0.146.0 插件命令结构变了(不再是老的 plugin install)
老简报(2026-07 写的)还在用:
codex plugin list # 旧版:列出可安装的
codex plugin install <name> # 旧版:直接安装
codex plugin update <name> # 旧版:更新
实测 0.146.0 已改为:
codex plugin marketplace list # 列已注册的市场源
codex plugin marketplace add openai/codex-marketplace # 先注册源
codex plugin add <name>@openai-api-curated # 再装指定插件
关键差别:新命令是「市场源 + 插件名」二段式。codex plugin install / codex plugin update 这两个子命令在 0.146.0 已不存在。
如何判断"插件到底装没装"(2026-08-15 修正,详见陷阱 5):
- 权威来源是
~/.local/bin/codex plugin list(带完整路径)—— 每个 marketplace 的 STATUS 列(installed, enabled/not installed)才是真相。之前「它不工作」是 PATH bug(裸codex在 cron 下找不到),不是 marketplace 没注册。 ~/.codex/config.toml的[plugins."X@marketplace"] enabled=true是次权威。ls ~/.codex/plugins/cache/*/目录仅供参考,会过期:curated cache 有 7 个目录但 config.toml 早已无对应 enabled 条目(孤儿缓存)。目录存在 ≠ 已启用。computer-use不是插件,是[features] computer_use = false开关。
为什么不自动注册 marketplace 让 plugin list 工作:openai/codex-marketplace 的 Git URL 未在玉芬的项目里固定,盲目 add 可能拉到一个不再维护的 fork。Cron 报告里直接告诉华哥 "ls cache 已经 10/10,是否补 marketplace" 即可,别擅自 add 源。
⚠️ 陷阱 3:Skill 上下文预算溢出(重要 — 实时影响 Codex 行为)
codex exec 启动时打这条警告:
warning: Exceeded skills context budget of 2%. All skill descriptions were removed and 302 additional skills were not included in the model-visible skills list.
后果:
- Codex 在 2% 上下文预算里塞不下 300+ skill 的描述
- 模型启动时完全看不见可用 skills(只能盲猜调不调得到)
- 影响 Codex 实际能调用的工具面 — 远低于
~/.codex/skills/里的目录列表
诊断:
# 看 Codex 内置 skills 目录
ls /Users/hua/.codex/skills/ | wc -l # 2026-08-03 实测:42
# 任何一次 exec 都会重显这条警告
cd /tmp && codex exec --skip-git-repo-check "echo X" 2>&1 | grep -i "skills context budget"
缓解(华哥手动巡检时评估):
- 检查
~/.codex/skills/里有没有大量同名/重复 skill — Codex 的 skills 机制是文件名作为 tool name - 评估能否在
~/.codex/config.toml的[features]节加large_skills_context = true(如果 Codex 版本里有这个 feature flag) - 或者把不常用的 skills 移到
~/.codex/skills/_archive/(确认 Codex 不扫下划线开头目录前不要这么做)
经验法则:Cron 报告里永远复述这条警告的状态(哪怕只是"⚠️ skill 预算仍在溢出"),让华哥每周都看见、记得这事还没修。
⚠️ 陷阱 4:sync_codex_repo.sh 路径缺陷(2026-08-09 发现)
~/6-产品研发/22-出图智能体训练/sync_codex_repo.sh 有两个 bug:
codex 路径问题:脚本用裸
codex命令,cron 环境下 PATH 不含~/.local/bin,导致codex --version返回空、codex plugin list输出 "No plugins found"。修复:用绝对路径$HOME/.local/bin/codex。写入错误的 repo 目录:脚本写到
~/codex-workspace/yuxin-skills/(无 git remote),实际同步仓库在/tmp/yuxin-skills-codex-sync/(remote:git@github.com:openclaw-cn-dev/yuxin-skills.git)。脚本 line 17 尝试 cloneyuxin-tech/yuxin-skills失败后 fallback 到本地 init,所以永远没有 remote。remote 名写死 "origin"(2026-08-15 补发现):
~/codex-workspace/yuxin-skills/实际 remote 名叫openclaw,脚本却grep -q "origin"+git push origin main→ 永远匹配不到 → "no remote configured, saved locally" 假成功。clone URL 也写死yuxin-tech/yuxin-skills(实为openclaw-cn-dev/yuxin-skills)。
更深坑(2026-08-15 实测):即使三处全修好(codex 路径用 command -v codex || echo "$HOME/.local/bin/codex"、remote 名自动识别 git remote | head -1、clone URL 改正),~/codex-workspace/yuxin-skills/ 的本地 git 历史与远程无关(unrelated histories):git pull 报 refusing to merge unrelated histories、push 报 non-fast-forward —— 这个 workspace 从 git init 起就是孤仓库,从未真正连接远程。结论:sync_codex_repo.sh 及其 workspace 是遗留产物,应弃用,不要花时间重建它的 git 历史。
临时修复(cron 作业手动步骤):
# 直接写 status 到真实仓库
STATUS_FILE="codex/status_$(date +%Y-%m-%d).md"
cd /tmp/yuxin-skills-codex-sync
git pull origin main
# ... 生成 status 文件 ...
git add "$STATUS_FILE" && git commit -m "chore(codex): update status $(date +%Y-%m-%d)"
git push origin main
根治方案:改脚本的 REPO_DIR 为 /tmp/yuxin-skills-codex-sync,确保 remote 已在初始化时配好。
✅ 其实已有现成的正确同步脚本,不必改
sync_codex_repo.sh:~/.hermes/scripts/codex_github_sync.sh是 hourly cron 包装,内部exec python3 codex_self_evolution.py --sync-only,会自动 pull → copy(AGENTS.md / config.toml 脱敏 / skills/yuxin-* / plugins.json / STATUS.md) → commit → push 到git@github.com:openclaw-cn-dev/yuxin-skills.git → codex/。维护 cron 里 GitHub 同步这一步应直接bash ~/.hermes/scripts/codex_github_sync.sh,而不是跑sync_codex_repo.sh(后者 target 错 repoyuxin-tech+ 无 remote,只会"no remote configured, saved locally"假成功)。
⚠️
codex_self_evolution.py --sync-only的版本检查同样有 PATH bug:它用裸codex --version,cron 下会 log当前: /bin/sh: codex: command not found并误报⚠️ 有新版本可用。这是假阳性 — 报告"有新版/需升级"前,必须用~/.local/bin/codex --version复核真实本地版本(本次实测本地 0.147.0 == npm latest 0.147.0,无升级)。
📄 STATUS.md / plugins.json 正确模板 + 同步工作流 + [SILENT] 判定 + GitHub SSH 数据通道间歇卡死诊断 →
references/cron-sync-templates.md📄 首次安装 / npm 重装 / CLI command not found →
references/codex-fresh-install-bootstrap.md(含 CLI 形态横跳 + 假升级陷阱 + 任务简报路径不存在的应对)
⚠️ 陷阱 5:插件缓存目录 ≠ 已安装(cache 目录还会骗人)
三级缓存目录各有不同内容:
~/.codex/plugins/cache/openai-api-curated/— curated 市场插件~/.codex/plugins/cache/openai-bundled/— Codex 内置插件~/.codex/plugins/cache/openai-primary-runtime/— 文档类运行时插件
⚠️「目录存在 = 已安装」是错的(2026-08-15 实测翻车):curated cache 有 7 个目录(build-web-apps/coderabbit/figma/github/linear/sentry/superpowers,Jul 11 残留),但 config.toml 里早已没有这 7 个的 [plugins."X@openai-api-curated"] enabled=true 条目,也没有 [marketplaces.openai-api-curated] 段 —— 它们是过期孤儿缓存,实际未启用。cache 目录只证明「曾经下载过」,不证明「当前启用」。
判定插件真实状态的权威顺序(按可信度降序):
~/.local/bin/codex plugin list(必须带完整路径,cron PATH 无 codex)→ 每个 marketplace 都有 STATUS 列:installed, enabled/not installed。这才是当前真相。之前以为它「不工作」其实是 PATH bug,不是 marketplace 没注册。~/.codex/config.toml的[plugins."X@marketplace"] enabled=true段 —— 当前真正启用的插件清单。~/.codex/plugins/cache/*/目录 —— 仅供交叉参考,会过期,不能单独作为「已装」依据。
computer-use 根本不是插件:它是 [features] 段的功能开关 computer_use = false(当前关闭)。AGENTS.md「16 个插件」清单把 computer-use 当插件是文档错误。期望清单「10 个插件」里,browser/chrome 属 openai-bundled 市场、computer-use 是 feature flag、其余 7 个属 curated —— 三者来源不同,别混在一张清单里数。
可疑根因:curated 插件从 config.toml 消失,大概率是 Codex 桌面端(ChatGPT.app,CODEX_CLI_PATH=/Applications/ChatGPT.app/...)重写 config.toml 时丢弃了 [marketplaces.openai-api-curated] 段和对应 [plugins.*] 条目 → 详见 references/codex-desktop-crash-loop.md。报告里提示华哥:若误删需重装,若有意精简需同步改 AGENTS.md。
⚠️ 陷阱 6:升级 codex 会重写 config.toml,丢失 marketplace 注册(2026-08-19 实证)
npm install -g @openai/codex@latest 升级(0.147→0.148)后,桌面端重写 ~/.codex/config.toml,把 [marketplaces.openai-bundled] 和 [marketplaces.openai-primary-runtime] 段删掉,导致 browser/chrome/visualize/documents/pdf 等插件全部"消失"(codex plugin list 只剩 openai-api-curated 一个市场)。
诊断:codex plugin marketplace list 只剩一个市场 = 注册丢了。
修复(重新注册市场 + 重装插件):
# 1. 重新注册 bundled 市场(browser/chrome/visualize 来源)
~/.local/bin/codex plugin marketplace add "/Users/hua/系统文件夹/Codex/.tmp/bundled-marketplaces/openai-bundled"
# 2. 重新注册 primary-runtime 市场(documents/pdf 等来源)
~/.local/bin/codex plugin marketplace add "/Users/hua/.cache/codex-runtimes/codex-primary-runtime/plugins/openai-primary-runtime"
# 3. marketplace add 后之前 installed 的插件会变 not installed,逐个重装
~/.local/bin/codex plugin add browser@openai-bundled
~/.local/bin/codex plugin add chrome@openai-bundled
~/.local/bin/codex plugin add visualize@openai-bundled
~/.local/bin/codex plugin add codex-app-tools@openai-bundled
~/.local/bin/codex plugin add documents@openai-primary-runtime # 同理 pdf/spreadsheets/presentations/template-creator
注意:升级同时会冲掉 [plugins."X@marketplace"] enabled=true 段和 [features] computer_use=false(防崩溃配置),需一并加回。browser/chrome/visualize 的 enabled 段要写回 config.toml,否则即使 installed 也可能不生效。
✅ plugin add 安全、cron 可自动重装(2026-08-24 实测,与陷阱 6 成对比)
Weekly 进化 cron 实测:curated 7 个插件全部 not installed(cache 有残留、config 无 enabled 条目 = 桌面端重写丢弃)时,用 plugin add 自动重装是安全的,与 npm install -g @openai/codex@latest 升级(陷阱 6,会重写 config 丢 marketplace/plugins 段)成鲜明对比:
CODEX="/Applications/ChatGPT.app/Contents/Resources/codex"
cp /Users/hua/.codex/config.toml "/Users/hua/.codex/config.toml.bak-$(date +%Y%m%d-%H%M%S)" # 先备份
for p in build-web-apps coderabbit figma github linear sentry superpowers; do
HOME=/Users/hua CODEX_HOME=/Users/hua/.codex "$CODEX" plugin add "$p@openai-api-curated"
done
# 校验:grep -n "enabled = true" config.toml 应多出 7 条;model_provider/base_url/token 未变
实测 plugin add 只追加 [plugins."X@marketplace"] enabled = true 段,不动 model_provider / base_url / experimental_bearer_token。所以 cron 可安全地把「缺失的 curated 插件」自动装回,不必等华哥确认(前提:marketplace 源已注册 + 先备份 config)。这是陷阱 2「别擅自 add 源」的正确边界 —— 别 plugin marketplace add(加源),但 plugin add(装插件,源已注册时)是安全的。
⚠️ Codex 0.148 把 browser/chrome 移出 bundled 市场(2026-08-24 实测)
openai-bundled 的 marketplace.json(/Users/hua/系统文件夹/Codex/.tmp/bundled-marketplaces/openai-bundled/.agents/plugins/marketplace.json)在 0.148 只剩 3 个插件:codex-app-tools / latex / visualize。browser / chrome 已从市场定义移除(plugin list 不再列出,无法 plugin add 装回),但 ~/.codex/plugins/cache/openai-bundled/browser|chrome/26.814.41957/ 缓存仍在(残留)。是否整合为原生能力需桌面端实测确认 —— 陷阱 5 里「browser/chrome 属 openai-bundled 市场」的结论对 0.148 已过时,别再按它去 plugin add browser@openai-bundled。
Skill 预算警告新措辞(2026-08-24)
早前是 Exceeded skills context budget of 2%. All skill descriptions were removed...(陷阱 3)。0.148 实测变为更温和的:
warning: Skill descriptions were shortened to fit the skills context budget. Codex can still see every skill, but some descriptions are shorter.即「缩短描述」而非「移除描述」,但仍未解除。cron 报告里照旧复述(陷阱 3 强制)。
CLI broken symlink(补充 2026-08-23「已不是独立 npm 安装」)
~/.local/bin/codex 的 symlink 仍存在,但指向 ../lib/node_modules/@openai/codex/bin/codex.js(目标已不存在),执行报 No such file or directory(不是 command not found)。别被 symlink 存在迷惑 —— 唯一可用 CLI = /Applications/ChatGPT.app/Contents/Resources/codex(codex --version 判活,ls -la 会骗人)。
Cron 报告模板(Codex Evolution Weekly)
🧬 Codex 进化报告 | {date}
| 项目 | 状态 | 详情 |
|------|------|------|
| 版本 | ✅ | codex-cli 0.x.x |
| 插件 | ✅/⚠️ | {N}/{M} (curated+bundled+primary-runtime cache 实际目录数) |
| Gateway | ✅/❌ | 端口 {N} 健康 |
| 功能测试 | ✅/❌ | tokens: {N} |
| 新发现 | — | ... |
💡 建议:...
强制字段:
- 必须复述 skill 预算溢出警告状态("溢出" / "已修" / "未复现")
- 插件数必须以
~/.local/bin/codex plugin list(带完整路径)+config.toml[plugins.*] enabled=true为准,不要用ls plugins/cache/目录数当「已装」(cache 会留孤儿,详见陷阱 5) - 必须确认
codex exec真有tokens used > 0(很多"通过"是假阳性,跑完但没真正调通 LLM) codex plugin list是可信的(前提是带完整路径,PATH bug 才是之前「No plugins found」的根因,不是 marketplace 没注册)