当前位置：首页 > news >正文

Codex CLI - 自然语言命令行界面

news 来源：原创 2025/8/10 10:37:34

在这里插入图片描述

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

文章目录

- 一、关于 Codex CLI
- - 相关链接资源
- 二、安装
- - 系统要求
  - 安装步骤
- 三、基本使用
- - 1、基础操作
  - 2、多轮模式
- 四、命令参考
- 五、提示工程与上下文文件
- - 自定义上下文
- 六、故障排查
- 七、FAQ
- - 如何查询可用OpenAI引擎？
  - 是否支持Azure运行？

一、关于 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，并定制了传递给模型的提示（见下文提示工程部分）。

二、安装

系统要求

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（六）