Codex CLI命令速查手册：极简设计与高频场景实战指南

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）。对于绝大多数用户，我强烈推荐使用pip（Python包管理器）。不是因为它最好，而是因为它最通用，且后续依赖管理最清晰。命令很简单：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在发起请求时，可能会尝试读取系统的代理配置。你需要做的是：

1. 检查你是否身处需要代理的网络环境。
2. 明确你的代理设置。例如，如果你使用http://127.0.0.1:7890这样的本地代理，需要在终端中显式设置环境变量：

   export HTTP_PROXY=http://127.0.0.1:7890 export HTTPS_PROXY=http://127.0.0.1:7890

   然后重新运行命令。
3. 如果你不需要代理，请确保这些环境变量没有被设置。可以通过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 x+y" # 从文件读取提示词（适用于长提示） 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 # 上述命令会返回一个会话ID（session_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会显示文件ID（file-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.jsonl

4.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-4

4.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。

• 排查步骤：
  1. 检查当前配置：运行codex whoami或codex config view，查看当前生效的认证方式是API Key还是Session Token，以及对应的账号或Key前缀是否正确。
  2. 重新登录：运行codex auth logout然后再次codex auth login。这能清除可能过期的令牌。
  3. 验证API Key：如果使用API Key，请到Codex官网的账户设置页面，确认该Key是否被启用、是否有足够的权限、是否已过期或被撤销。
  4. 检查多配置环境：如果你使用了codex switch，确认你是否处于正确的配置上下文下。

问题2：命令超时或报错cc switch local proxy failed.../Connection refused。

• 排查步骤：
  1. 诊断网络连通性：在终端尝试curl -v https://api.codex.com/v1/models（将地址替换为实际的Codex API地址）。观察是否能收到正常的JSON响应或认证错误。如果连不上，就是网络问题。
  2. 检查代理设置：如3.1节所述，通过env | grep -i proxy检查环境变量。根据你的网络环境，正确设置或清空它们。
  3. 防火墙/安全软件：临时禁用本地防火墙或安全软件，测试是否是其拦截了CLI的出站连接。
  4. 使用调试模式：在命令前加上CODEX_DEBUG=true环境变量，如CODEX_DEBUG=true 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' | sort

5.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不知如何下手时，打开它，用搜索功能（Ctrl+F）快速定位到你的问题关键词，复制、粘贴、修改、运行。让效率提升发生在每一次具体的操作中，这才是速查手册存在的意义。