1. 项目概述为什么你需要一份“无废话”的Codex命令手册如果你正在寻找Codex的命令行工具CLI使用方法大概率已经翻遍了官方文档、技术博客甚至看了几个视频教程。但结果往往是官方文档过于冗长像一本厚重的说明书想快速查个参数得翻半天而很多网络教程又过于零散要么版本过时要么夹杂着大量无关的“水文”真正核心的命令和参数淹没在字海里。这种感觉就像你想找一把螺丝刀却不得不先拆开一个装满各种工具的大箱子。这正是我整理这份“无废话源自官网的Codex命令速查手册”的初衷。这份手册的核心价值不在于创造新知识而在于做一次极致的“信息提纯”和“场景化重组”。它完全基于Codex官方CLI文档的最新稳定版本剔除了所有冗长的概念阐述、历史背景和重复示例只保留最核心、最高频使用的命令、参数及其组合。它的目标只有一个让你在需要的时候能像查字典一样在10秒内找到那个能解决你当前问题的命令并附上最直白的解释和最常见的用法示例。这份手册适合谁如果你是开发者、运维工程师、AI应用研究者或者任何需要频繁与Codex的API或本地部署打交道的技术从业者它就是你桌面的“瑞士军刀”。无论你是想快速验证一个模型调用调试一个复杂的提示词还是批量处理大量文件这份手册都能提供最直接的路径。它不教你“为什么”要设计这些命令那是官方文档的事它只告诉你“怎么用”才能最快地搞定手头的活儿。2. 手册设计哲学极简、场景与可操作性在动手整理之前我给自己定了三条铁律这也是这份手册区别于其他任何参考资料的核心。2.1 原则一命令即答案参数即说明传统文档喜欢用“章节-小节-段落”的结构来组织内容比如先讲“认证”再讲“模型”最后讲“文件”。但在实际使用中我们的大脑是“问题驱动”的。我们想的是“我怎么用CLI发一条消息”或者“我怎么上传一个文件并让它总结”因此这份手册完全以“命令”为最小组织单元。每个命令独占一个清晰的区块其下直接罗列最关键的参数。没有前言没有后记命令本身就是标题参数和示例就是全部内容。这种结构牺牲了系统性但换来了无与伦比的检索速度。2.2 原则二场景化示例优于抽象描述看一百遍--temperature参数描述为“控制输出的随机性值越高越随机”不如看一个例子。手册中每个重要的参数都会绑定1-2个最典型的应用场景。例如对于codex completions create命令我们不会孤立地列出--temperature 0.7而是会给出一个完整的示例codex completions create -m gpt-4 -p “用Python写一个快速排序函数” --temperature 0.7 --max-tokens 150。这个示例同时展示了模型选择、提示词输入、创造性控制和输出长度限制你几乎可以复制粘贴后稍作修改就能用。场景化示例是将知识转化为肌肉记忆的最短路径。2.3 原则三严格规避“配置深坑”使用任何CLI工具最耗时的往往不是命令本身而是前期的环境配置和认证。网络上大量的求助帖都卡在cc switch local proxy failed或{detail:the gpt-5.6-sol model is not supported}这类错误上。因此本手册在开头部分会用最精炼的步骤确保你“一次性”完成正确的安装、配置和认证绕过那些常见的坑。我们会明确指出哪些步骤是必须的哪些配置项最容易出错以及出现特定错误信息时第一步应该检查什么。这部分的唯一目标就是让你快速进入“可工作状态”。注意本手册的所有命令和参数均基于撰写时Codex CLI的公开稳定版本。CLI工具会持续更新如果遇到命令失效或参数变更第一反应应是查阅官方发布说明。手册提供的是“方法”和“模式”而非一成不变的代码。3. 核心细节解析从安装到核心命令链3.1 环境准备与“零失败”安装安装Codex CLI本身很简单但“安装成功”不等于“配置可用”。很多人在第一步就卡住了。安装方式选择 官方通常提供多种安装方式如通过包管理器pip,brew,curl | bash。对于绝大多数用户我强烈推荐使用pipPython包管理器。不是因为它最好而是因为它最通用且后续依赖管理最清晰。命令很简单pip install codex-cli。如果你遇到权限问题可以使用pip install --user codex-cli安装到用户目录。安装后第一件事——验证与初始化 安装完成后不要急着运行codex --help。首先你需要确认命令行能找到它。打开终端输入which codex或codex --version。如果返回了路径或版本号说明安装成功。接下来是关键一步认证。运行codex auth login。这会打开你的默认浏览器引导你完成OAuth授权或API密钥的输入。请务必在此步骤使用你有权访问Codex服务的账号。避坑指南网络与代理配置 如果你在终端中遇到了cc switch local proxy failed while handling codex endpoint这类错误几乎可以断定是网络或代理问题。Codex CLI在发起请求时可能会尝试读取系统的代理配置。你需要做的是检查你是否身处需要代理的网络环境。明确你的代理设置。例如如果你使用http://127.0.0.1:7890这样的本地代理需要在终端中显式设置环境变量export HTTP_PROXYhttp://127.0.0.1:7890 export HTTPS_PROXYhttp://127.0.0.1:7890然后重新运行命令。如果你不需要代理请确保这些环境变量没有被设置。可以通过env | grep -i proxy来检查。3.2 认证机制与密钥管理CLI与Codex服务交互的核心是认证。理解认证机制能帮你避免很多诡异的“权限不足”错误。API Key vs. Session Token Codex CLI通常支持两种主要认证方式持久的API密钥和临时的会话令牌Session Token。codex auth login命令默认会引导你进行网页登录成功后会在本地生成并存储一个会话令牌。这种方式更安全因为令牌有过期时间。而如果你需要在无头服务器如CI/CD环境中使用则需要使用API密钥。你可以通过codex auth api-key your_key来设置。密钥的存储与安全 你的认证信息默认会存储在一个本地配置文件中通常是~/.codex/config.json。务必保护好这个文件。不要在公共代码库中提交这个文件或硬编码你的API密钥。一个最佳实践是将API密钥存储在系统的环境变量中如CODEX_API_KEY然后在脚本或命令行中通过$CODEX_API_KEY来引用。多配置切换 如果你需要管理多个不同账号或项目的配置例如一个用于公司项目一个用于个人实验可以使用codex switch或codex profile相关命令来创建和切换不同的配置上下文。这比手动修改配置文件要安全方便得多。3.3 核心命令结构解析Codex CLI的命令设计通常遵循资源 操作的模式。理解这个模式你就能举一反三。codex completions这是最核心的命令组用于与文本补全模型交互。其下的create操作是最常用的。codex files用于管理上传到Codex的文件例如用于微调或上下文分析。主要操作包括upload,list,delete,retrieve。codex fine-tunes如果你需要对模型进行微调这个命令组涵盖了从创建任务、查看列表到获取结果的全流程。codex models用于列出可用的模型或获取特定模型的详细信息。codex api这是一个“直通”命令允许你直接向Codex的任意API端点发送原始的HTTP请求用于高级用途或访问CLI尚未封装的功能。每个命令都支持--help参数来获取最即时的帮助信息。例如不确定completions create有哪些参数随时输入codex completions create --help。4. 命令速查手册正文以下是按功能模块组织的命令速查表。每个命令都附带了最精简的说明和最实用的示例。4.1 会话与补全核心命令这是与AI对话、生成代码、创作文本的核心。4.1.1 创建文本补全这是使用频率最高的命令用于一次性的提示与补全。# 基础用法向指定模型发送提示获取补全 codex completions create --model gpt-4 --prompt 请用JavaScript写一个函数判断一个数是否为素数。 # 指定输出长度和随机性 codex completions create -m gpt-3.5-turbo -p 写一首关于春天的五言绝句 --max-tokens 50 --temperature 0.9 # 使用系统指令system message设定AI角色通常用于Chat模型 codex completions create -m gpt-4 \ --system-message 你是一位资深的Python代码审查专家语气严谨但友好。 \ --prompt 请审查以下代码的潜在问题def add(x, y): return xy # 从文件读取提示词适用于长提示 codex completions create -m gpt-4 --prompt $(cat my_prompt.txt) # 流式输出streaming用于实时查看生成过程 codex completions create -m gpt-4 -p 讲述一个骑士屠龙的故事开头 --stream关键参数解读-m, --model:必选。指定模型如gpt-4,gpt-3.5-turbo。使用codex models list查看所有可用模型。-p, --prompt: 用户提示。对于非Chat模型这就是输入的全文。--system-message: 系统指令用于设定对话背景、角色或行为准则。对Chat模型效果显著。--max-tokens: 限制生成内容的最大长度约等于单词数。需预留提示词本身的token数。--temperature: 创造性控制。范围0~2。0表示确定性最高输出固定值越高输出越随机、有创意。--stream: 启用流式响应。生成一个字就返回一个字体验好但处理响应逻辑稍复杂。4.1.2 管理多轮对话会话对于需要上下文连续的多轮对话使用chat子命令更合适。# 创建一个新的聊天会话 codex chat create --model gpt-4 # 上述命令会返回一个会话IDsession_id后续消息需指定此ID # 发送后续消息 codex chat send --session-id sess_abc123 --message Python里列表和元组的主要区别是什么 # 发送带角色的消息模拟历史对话 codex chat send -s sess_abc123 --role user --message 我忘了再说一次 codex chat send -s sess_abc123 --role assistant --message 列表可变元组不可变。 # 获取会话历史 codex chat history --session-id sess_abc123 # 删除会话 codex chat delete --session-id sess_abc123实操心得对于简单的多轮问答手动维护session-id可能比较麻烦。一种常见的做法是在脚本中将会话ID存储为变量或者直接使用completions create并在--prompt中手动拼接完整的历史对话格式如“用户...\n助手...\n用户...”这对于自动化脚本有时更直接。4.2 文件与数据处理命令当你需要让AI处理本地文档、代码库或数据集时需要用到文件操作。4.2.1 上传与管理文件# 上传一个文件并指定其用途如‘fine-tune’用于微调‘assistants’用于助手 codex files upload --file ./my_data.jsonl --purpose fine-tune # 上传时CLI会显示文件IDfile-xxx务必记下或保存后续操作依赖此ID。 # 列出所有已上传的文件 codex files list # 获取特定文件的详细信息 codex files retrieve --file-id file-abc123 # 删除文件 codex files delete --file-id file-abc123 # 下载文件内容注意并非所有文件都可下载如微调结果文件可能不可直接下载 codex files download --file-id file-abc123 --output ./downloaded.jsonl4.2.2 在补全中使用文件上传文件后你可以让模型基于文件内容进行回答。# 方法1在提示词中引用文件ID适用于模型知道如何引用文件的场景 codex completions create -m gpt-4 \ -p 请总结文件 file-abc123 中的核心观点。 \ --file-ids file-abc123 # 方法2更通用的方式是将文件内容作为上下文的一部分需自行读取并拼接 codex completions create -m gpt-4 \ -p 以下是某文档的内容\n$(cat ./document.txt)\n\n请根据上述文档回答...4.3 模型管理与高级操作4.3.1 查询可用模型# 列出所有可用的模型 codex models list # 以更详细的JSON格式列出 codex models list --output json # 获取特定模型的详细信息包括上下文长度、所属家族等 codex models retrieve --model-id gpt-44.3.2 使用原始API调用当CLI没有封装你需要的功能时api命令是你的逃生舱口。# 向指定的API端点发送GET请求 codex api get /models # 发送POST请求并携带JSON格式的请求体 codex api post /completions --data { model: gpt-3.5-turbo, prompt: Hello, world, max_tokens: 5 } # 设置自定义请求头 codex api post /chat/completions --data {model:gpt-4, messages:[{role:user,content:Hi}]} --header Authorization: Bearer $OTHER_API_KEY这个命令本质上是一个方便的HTTP客户端帮你处理了认证和基础URL你只需要关心端点和数据。5. 常见问题与排查技巧实录即使有了速查手册实际使用中还是会遇到各种问题。下面是我在大量使用中总结的“高频故障”及其排查思路。5.1 认证与网络类问题问题1执行任何命令都返回Authentication error或Invalid API Key。排查步骤检查当前配置运行codex whoami或codex config view查看当前生效的认证方式是API Key还是Session Token以及对应的账号或Key前缀是否正确。重新登录运行codex auth logout然后再次codex auth login。这能清除可能过期的令牌。验证API Key如果使用API Key请到Codex官网的账户设置页面确认该Key是否被启用、是否有足够的权限、是否已过期或被撤销。检查多配置环境如果你使用了codex switch确认你是否处于正确的配置上下文下。问题2命令超时或报错cc switch local proxy failed.../Connection refused。排查步骤诊断网络连通性在终端尝试curl -v https://api.codex.com/v1/models将地址替换为实际的Codex API地址。观察是否能收到正常的JSON响应或认证错误。如果连不上就是网络问题。检查代理设置如3.1节所述通过env | grep -i proxy检查环境变量。根据你的网络环境正确设置或清空它们。防火墙/安全软件临时禁用本地防火墙或安全软件测试是否是其拦截了CLI的出站连接。使用调试模式在命令前加上CODEX_DEBUGtrue环境变量如CODEX_DEBUGtrue codex models list。这会输出更详细的网络请求日志帮助你定位问题发生在哪一步。5.2 命令与参数类问题问题3命令执行成功但返回{detail:the gpt-5.6-sol model is not supported...}。原因与解决这明确表示你指定的模型名称gpt-5.6-sol不存在或你无权访问。这常常是因为拼写错误仔细核对模型名区分大小写和横杠。使用codex models list查看准确的名称列表。模型已废弃或更名API模型列表会更新。你之前可用的模型可能已被新版替代。权限问题某些模型如最新的预览版模型可能需要对特定账户开放。确认你的账户是否有权使用该模型。问题4提示词太长导致错误This model‘s maximum context length is ... tokens。解决策略压缩提示词删除不必要的描述和空格用更简洁的语言表达。分而治之将长任务拆分成多个短的请求将前一个请求的输出作为下一个请求的部分输入。使用摘要如果提示词包含长文档先使用模型对文档进行摘要再用摘要作为新提示词的上下文。选择上下文更长的模型检查codex models list选择context_length更大的模型。问题5如何将CLI的输出结果保存到文件或传递给其他程序技巧利用Shell的重定向和管道。# 将输出直接保存到文件 codex completions create -m gpt-4 -p ... output.txt # 将输出以JSON格式保存便于用jq等工具解析 codex completions create -m gpt-4 -p ... --output json response.json # 只提取返回内容中的“文本”部分假设响应结构中有‘choices[0].text’ codex completions create -m gpt-4 -p ... --output json | jq -r .choices[0].text # 将输出作为另一个命令的输入 codex completions create -m gpt-4 -p 生成5个随机单词用逗号分隔 | tr , \n | sort5.3 性能与成本优化技巧技巧1利用--max-tokens精确控制避免浪费。不要总是设置一个很大的max-tokens。先预估一下你期望的回答长度。对于简单的问答50-150个token可能就够了。对于代码生成根据函数复杂度设置200-500。这不仅能加快响应速度还能节省token使用量关乎成本。技巧2在脚本中处理流式输出。当你使用--stream参数时CLI会以Server-Sent Events (SSE)格式逐块返回数据。在Shell脚本中处理它需要一点技巧# 一个简单的例子使用jq解析流式输出的每一行 codex completions create -m gpt-4 -p ... --stream --output json \ | while IFS read -r line; do if [[ $line data:* ]]; then data${line#data: } if [[ $data ! [DONE] ]]; then echo $data | jq -r .choices[0].delta.content // empty fi fi done技巧3善用--temperature和--top-p。对于需要确定答案的任务如代码生成、数据提取将temperature设为0或接近0如0.1-0.3。对于创意写作、头脑风暴可以提高到0.7-1.0。top-p核采样是另一种控制随机性的方式通常与temperature二选一即可不必同时设置。这份“无废话”手册的核心价值在于其极致的工具性。它不是一本教科书而是一张精准的地图。我的建议是不要试图一次性记住所有命令而是把它加入浏览器书签或保存在本地。当你下次在终端前面对Codex CLI不知如何下手时打开它用搜索功能CtrlF快速定位到你的问题关键词复制、粘贴、修改、运行。让效率提升发生在每一次具体的操作中这才是速查手册存在的意义。
