本文翻译整理自：https://github.com/microsoft/Codex-CLI

---

---

一、关于 Codex CLI

本项目利用 GPT-3 Codex 将自然语言指令转换为 PowerShell、Z shell 和 Bash 中的命令。

---

---

命令行界面(CLI)是我们与机器交互的第一个主要用户界面。它功能强大，几乎可以完成任何操作，但要求用户必须极其精确地表达意图——用户需要_掌握计算机的语言_。

随着大语言模型(LLM)的出现，特别是经过代码训练的模型，现在可以使用自然语言(NL)与CLI进行交互。这些模型能充分理解自然语言_和_代码，实现两者之间的转换。

本项目旨在提供跨Shell的 NL->代码转换体验，让用户能用自然语言操作熟悉的CLI。
用户输入如"what’s my IP address"的指令，按下Ctrl + G即可获得符合当前Shell语法的建议命令。
项目直接使用GPT-3 Codex模型（未针对该任务专门训练），通过提示工程（见下文章节）引导Codex生成正确命令。

注意：模型仍可能出错！不要运行你不理解的命令。如果不确定命令作用，请按Ctrl + C取消。

本项目技术灵感来源于zsh_codex，扩展了其功能以支持多Shell，并定制了传递给模型的提示（见下文提示工程部分）。

---

相关链接资源

• github : https://github.com/microsoft/Codex-CLI
• 官网：https://openai.com/blog/openai-codex/
• 官方文档：https://beta.openai.com/docs/
• Demo/在线试用：https://mybuild.microsoft.com/
• License : MIT

---

二、安装

系统要求

• Python 3.7.1+
  • [Windows]: 需将Python添加至PATH环境变量
• OpenAI账号
  • OpenAI API密钥
  • OpenAI组织ID。若属多组织，请在获取ID前于默认组织设置页选择有权访问Codex引擎的组织
  • OpenAI引擎ID。例如code-davinci-002或code-cushman-001，详见可用引擎查询

---

安装步骤

请根据PowerShell、bash或zsh选择对应安装说明：<./Installation.md>

---

三、基本使用

1、基础操作

配置完成后，在Shell中输入以#开头的注释，按Ctrl + G即可使用Codex CLI。

支持两种主要模式：

• 单轮模式（默认）
• 多轮模式（通过# start multi-turn和# stop multi-turn切换）

---

2、多轮模式

启用多轮模式时，Codex CLI会"记忆"与模型的交互历史，允许引用先前操作。例如：

# change my timezone to mountain
tzutil /s "Mountain Standard Time"

# change it back to pacific
tzutil /s "Pacific Standard Time"

---

工具会创建current_context.txt文件记录交互历史，并在后续命令中传递给模型。

关闭多轮模式后，工具不再保留交互历史。多轮模式虽支持上下文关联，但会增加开销——若模型生成错误脚本，需手动清除上下文，否则后续交互可能重复错误。单轮模式下，相同命令始终产生相同输出。

当模型持续输出错误命令时，可使用：

• # stop multi-turn：停止记忆并加载默认上下文
• # default context：加载默认上下文但保持多轮模式

---

四、命令参考

命令	描述
start multi-turn	启用多轮交互
stop multi-turn	禁用多轮交互并加载默认上下文
load context <文件名>	从contexts文件夹加载上下文文件
default context	加载默认Shell上下文
view context	在文本编辑器中打开上下文文件
save context <文件名>	保存上下文至contexts文件夹（未指定文件名则使用当前时间）
show config	显示当前模型交互配置
set <配置键> <配置值>	设置模型交互参数

可通过set命令调整token限制、引擎ID和温度等参数，例如：

# set engine cushman-codex
# set temperature 0.5
# set max_tokens 50

---

五、提示工程与上下文文件

本项目通过_提示工程_引导GPT-3 Codex从自然语言生成命令。具体做法是向模型传递一系列NL->命令示例，使其理解应生成的代码类型，并适配当前Shell语法。示例存储在contexts目录中，如下PowerShell上下文片段：

# what's the weather in New York?
(Invoke-WebRequest -uri "wttr.in/NewYork").Content

# make a git ignore with node modules and src in it
"node_modules
src" | Out-File .gitignore

# open it in notepad
notepad .gitignore

---

项目将自然语言命令建模为注释，并提供预期脚本示例（包括单行、多行及多轮补全）。当用户输入新命令时，系统会将其作为注释追加到上下文中，要求Codex生成后续代码。通过示例引导，Codex能生成满足注释要求的简短PowerShell脚本。

---

自定义上下文

除预置Shell上下文外，可创建自定义上下文引导模型行为。例如要生成Kubernetes脚本，可创建包含kubectl命令示例的新上下文：

# make a K8s cluster IP called my-cs running on 5678:8080
kubectl create service clusterip my-cs --tcp=5678:8080

---

将上下文文件放入contexts文件夹后运行load context <文件名>加载。也可修改src\prompt_file.py中的默认上下文设置。

虽然Codex通常无需示例即可生成正确脚本（因其训练数据包含大量代码），但定制上下文能优化输出风格（如脚本长度、变量声明方式等）。重要提示：添加新上下文时请保持多轮模式开启，以避免自动恢复默认上下文。

我们已提供认知服务上下文示例，展示如何通过API实现文本转语音响应。

---

六、故障排查

• 使用DEBUG_MODE切换至终端输入调试代码（适用于添加新命令时）
• 当openai包抛出未捕获异常时，可在codex_query.py末尾添加catch块打印自定义错误信息

---

七、FAQ

如何查询可用OpenAI引擎？

不同组织可能访问不同OpenAI引擎。通过List engines API查询可用引擎：

• Shell

  curl https://api.openai.com/v1/engines \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'OpenAI-Organization: YOUR_ORG_ID'
  

• PowerShell v5 (Windows默认版本)

  (Invoke-WebRequest -Uri https://api.openai.com/v1/engines -Headers @{"Authorization" = "Bearer YOUR_API_KEY"; "OpenAI-Organization" = "YOUR_ORG_ID"}).Content
  

---

• PowerShell v7

  (Invoke-WebRequest -Uri https://api.openai.com/v1/engines -Authentication Bearer -Token (ConvertTo-SecureString "YOUR_API_KEY" -AsPlainText -Force) -Headers @{"OpenAI-Organization" = "YOUR_ORG_ID"}).Content
  

---

是否支持Azure运行？

当前示例代码仅适用于OpenAI API的Codex。未来几个月将更新版本以支持Azure OpenAI服务。

---

伊织 xAI 2025-04-19（六）