【Bug已解决】codex: argument parsing error / unknown option — CodeX CLI 命令行参数解析错误解决方案1. 问题描述CodeX CLI 启动时无法正确解析命令行参数报出未知选项或参数格式错误# 使用未知选项时报错 $ codex --model o3-mini --temprature 0.7 分析代码 Error: unknown option --temprature Did you mean --temperature? at Command.parseOptions (~/.codex/node_modules/commander/index.js:500:15) # 或参数值格式错误 $ codex --max-tokens abc 分析代码 Error: Option --max-tokens requires a number, got abc at validateOption (~/.codex/lib/cli.js:23:9) # 或缺少必需参数 $ codex --model o3-mini Error: Missing required argument: prompt Usage: codex [options] prompt codex [options] --print prompt # 或短选项和长选项混用导致冲突 $ codex -m o3-mini --model o1 分析代码 Error: Option --model specified multiple times with different values --model o1 (from --model) --model o3-mini (from -m) # 或特殊字符导致 Shell 解析错误 $ codex --system-prompt 你是一个 C 专家 分析代码 Error: spawn ENOENT: /bin/sh args: [-c, 你是一个, C, 专家] # Shell 把引号内的内容拆分了有时表现为拼写错误的选项名导致解析失败数值参数传了字符串必需参数未提供同一选项被多次指定Shell 转义导致参数被截断新版本废弃的旧选项未更新这个问题在以下场景中特别常见手动输入命令拼写错误从旧版本文档复制的命令格式Shell 脚本中变量未正确引用管道和重定向符号干扰参数解析不同版本 CodeX CLI 选项不同中文/特殊字符未正确转义2. 原因分析核心原理拆解用户输入命令 → Shell 解析变量展开/引号/转义→ CodeX CLI 接收 argv ↓ Commander.js 解析选项和参数 ↓ 未知选项 / 类型不匹配 / 缺少参数 / 重复指定 ↓ 解析失败CLI 报错退出Shell 解析与 CLI 解析的区别Shell 解析先: hello world → 一个参数: hello world hello world → 两个参数: hello, world $VAR → 展开为变量值 command → 执行命令替换 CLI 解析后: --option value → 选项option, 值value --optionvalue → 选项option, 值value -o value → 短选项 o, 值value positional → 位置参数原因分类表原因分类具体表现占比选项拼写错误--temprature vs --temperature约 30%参数类型错误期望 number 传入 string约 20%缺少必需参数prompt 未提供约 15%Shell 转义问题引号/空格/特殊字符约 15%废弃选项旧版本选项不再支持约 10%重复指定同一选项多次出现约 10%3. 解决方案方案一使用 --help 查看正确选项最推荐# 步骤 1查看所有可用选项 codex --help # 输出示例 # Usage: codex [options] prompt # # Options: # -m, --model name Model name (o1, o3-mini, gpt-4o) # --max-tokens number Maximum output tokens (default: 4096) # --temperature number Sampling temperature 0-2 (default: 0.7) # --system-prompt text Custom system prompt # --print Print mode (no interactive) # --no-stream Disable streaming # -v, --version Show version # -h, --help Show help # 步骤 2确认选项名称和类型 # 注意 --temperature不是 --temprature # 注意 --max-tokens 需要 number 类型 # 步骤 3使用正确的选项 codex --model o3-mini --temperature 0.7 --max-tokens 4096 分析代码 # 步骤 4查看版本确认选项是否受支持 codex --version方案二正确处理 Shell 引号和转义# 步骤 1包含空格的参数必须用引号 codex --system-prompt You are a C expert analyze code # 步骤 2包含特殊字符的参数 codex 分析 function() { return 42; } 的逻辑 # 使用单引号避免 Shell 展开 codex 分析 $HOME 环境变量的使用 # 步骤 3参数中包含引号 # 使用反斜杠转义 codex He said \hello\ to me 分析代码 # 或交替使用引号 codex He said hello to me 分析代码 # 步骤 4多行参数 codex $(cat EOF 分析以下代码的安全性 1. 检查 SQL 注入 2. 检查 XSS 3. 检查 CSRF EOF ) # 步骤 5变量展开 codex 分析文件 $(realpath src/main.ts) 的架构方案三修复参数类型错误# 步骤 1检查选项期望的类型 codex --help | grep -A1 max-tokens # --max-tokens number 需要 number 类型 # 步骤 2正确传入数值 codex --max-tokens 4096 分析代码 # 正确 codex --max-tokens 4.096 分析代码 # 正确小数 codex --max-tokens abc 分析代码 # 错误字符串 codex --max-tokens 4096 分析代码 # 可能错误字符串 # 步骤 3temperature 范围验证 codex --temperature 0.7 分析代码 # 正确 (0-2) codex --temperature 3 分析代码 # 错误 (超出范围) # 步骤 4布尔选项不需要值 codex --print --no-stream 分析代码 # 正确flag 选项 codex --print true 分析代码 # 错误flag 不接受值方案四处理废弃选项# 步骤 1检查是否使用了废弃选项 codex --api-version v1 分析代码 # Error: unknown option --api-version # 如果旧版本支持但新版本不支持说明已废弃 # 步骤 2查看变更日志 codex --changelog 2/dev/null || npm info openai/codex changelog # 步骤 3常见废弃选项映射 # --api-version → 已废弃自动检测 # --retry-count → 改为 --retries # --output-format → 改为 --format # --verbose → 改为 --debug # 步骤 4使用新选项替代 codex --retries 3 --format json 分析代码 # 步骤 5如果需要旧选项兼容降级版本 npm install -g openai/codex0.10.0方案五使用配置文件替代命令行参数# 步骤 1将常用参数写入配置文件 cat ~/.codex/config.json EOF { model: o3-mini, maxTokens: 4096, temperature: 0.7, systemPrompt: You are a helpful coding assistant., streaming: true } EOF # 步骤 2命令行只需提供 prompt codex 分析代码 # 步骤 3命令行参数覆盖配置文件 codex --model o1 分析代码 # --model o1 覆盖 config.json 中的 o3-mini # 步骤 4验证配置加载 codex --show-config # Model: o3-mini (from config.json) # MaxTokens: 4096 (from config.json)方案六Shell 脚本中安全传参# 步骤 1Shell 脚本中正确引用变量 #!/bin/bash MODELo3-mini PROMPT分析 src/main.ts 的架构 # 正确变量用双引号包裹 codex --model $MODEL $PROMPT # 步骤 2使用数组处理复杂参数 #!/bin/bash ARGS( --model o3-mini --temperature 0.7 --max-tokens 4096 --system-prompt You are a C expert ) codex ${ARGS[]} 分析代码 # 步骤 3处理用户输入 #!/bin/bash read -r -p Prompt: user_prompt codex --model o3-mini -- $user_prompt # -- 分隔符确保 prompt 被视为位置参数而非选项 # 步骤 4验证参数解析 codex --debug --model o3-mini 分析代码 21 | grep -E argv|option|arg4. 各方案对比总结方案适用场景推荐指数难度方案一--help 查看选项错误⭐⭐⭐⭐⭐低方案二引号转义特殊字符⭐⭐⭐⭐⭐低方案三类型修复类型不匹配⭐⭐⭐⭐低方案四废弃选项版本升级⭐⭐⭐⭐中方案五配置文件常用参数⭐⭐⭐⭐⭐低方案六Shell 脚本自动化⭐⭐⭐⭐中5. 常见问题 FAQ5.1 如何查看所有可用选项# 完整帮助 codex --help # 搜索特定选项 codex --help | grep -i model # 查看简短用法 codex -h5.2 短选项和长选项的区别# 短选项单个 dash单个字母 codex -m o3-mini 分析代码 codex -v # 版本 # 长选项双 dash完整单词 codex --model o3-mini 分析代码 codex --version # 短选项可以合并 codex -vp # 等同于 -v -p5.3 -- 分隔符的作用# -- 之后的内容都视为位置参数不被解析为选项 codex --model o3-mini -- --verbose analysis # --verbose analysis 被视为 prompt 而非选项 # 适用于 prompt 以 -- 开头的情况 codex -- --help me analyze code # 不触发帮助而是将 --help me analyze code 作为 prompt5.4 为什么 Shell 变量展开会导致参数错误# 变量包含空格时不加引号会被拆分 PROMPTanalyze this code codex $PROMPT # CodeX 收到三个参数: analyze, this, code # 正确做法加双引号 codex $PROMPT # CodeX 收到一个参数: analyze this code # 变量包含特殊字符 FILEmy file (1).ts codex 分析 $FILE # 不加引号的 $FILE 会被 glob 展开和分词5.5 如何查看 CodeX 实际收到的参数# 使用 --debug 查看参数解析 codex --debug --model o3-mini 分析代码 21 | head -20 # 输出示例 # [DEBUG] argv: [--model, o3-mini, 分析代码] # [DEBUG] Parsed options: { model: o3-mini } # [DEBUG] Positional args: [分析代码]5.6 布尔选项怎么使用# 布尔选项flag不需要值 codex --print 分析代码 # 启用 print 模式 codex --no-stream 分析代码 # 禁用 streaming # 不要给 flag 传值 codex --printtrue 分析代码 # 错误 codex --print true 分析代码 # 错误true 被当作 prompt5.7 多个位置参数怎么处理# CodeX 通常只接受一个 prompt 位置参数 # 多个参数会被合并或报错 codex 分析 代码 # 可能被当作两个参数 codex 分析代码 # 正确一个参数 # 如果需要多行 prompt codex 第一行 第二行 第三行5.8 如何在管道中使用 CodeX# 通过 stdin 传入 prompt echo 分析代码 | codex --stdin # 从文件读取 codex prompt.txt # 管道组合 cat src/main.ts | codex 分析以上代码的逻辑 # 命令替换 codex 分析 $(cat src/main.ts) 的架构5.9 配置文件和命令行参数冲突时谁优先# 命令行参数优先级高于配置文件 # config.json: { model: o3-mini } codex --model o1 分析代码 # 实际使用 o1命令行覆盖配置 # 环境变量优先级 export CODEX_MODELgpt-4o codex --model o1 分析代码 # 实际使用 o1命令行 环境变量 配置文件5.10 排查清单速查表□ 1. codex --help 确认选项名称和类型 □ 2. 检查选项拼写temperature 不是 temprature □ 3. 数值选项传入 number 而非 string □ 4. 含空格/特殊字符的参数用引号包裹 □ 5. -- 分隔符防止 prompt 被解析为选项 □ 6. Shell 变量用双引号包裹 $VAR □ 7. flag 选项不传值 □ 8. 废弃选项查看 changelog 替代 □ 9. 常用参数写入 config.json □ 10. --debug 查看实际接收的 argv6. 总结根本原因参数解析错误最常见原因是选项拼写错误30%如--temprature和参数类型不匹配20%如给 number 传 string最佳实践每次遇到 unknown option 时先codex --help查看当前版本支持的选项名称和类型Shell 安全所有含空格、特殊字符的参数用双引号包裹Shell 变量用$VAR引用prompt 以--开头时用--分隔符配置化将常用参数写入~/.codex/config.json命令行只传 prompt 和临时调整的参数最佳实践建议Shell 脚本中使用数组${ARGS[]}传参--debug查看实际 argv 调试解析问题故障排查流程图flowchart TD A[命令行参数解析错误] -- B[codex --help 查看可用选项] B -- C{选项名称正确?} C --|否| D[修正拼写错误] D -- E[重新执行] C --|是| F{参数类型正确?} F --|否| G[修正为期望类型] G -- E F --|是| H{Shell 引号正确?} H --|否| I[用双引号包裹参数] I -- E H --|是| J{必需参数提供?} J --|否| K[补充 prompt 参数] K -- E J --|是| L{选项废弃?} L --|是| M[查看 changelog 找替代] M -- N[使用新选项] N -- E L --|否| O{重复指定?} O --|是| P[删除重复选项] P -- E O --|否| Q[--debug 查看 argv] Q -- R[检查 Shell 变量展开] R -- S[使用 -- 分隔符] S -- E E -- T{成功?} T --|是| U[✅ 问题解决] T --|否| V[写入 config.json 减少命令行参数] V -- W[只用命令行传 prompt] W -- U