C Codex 中文
GitHub 下载
  1. 首页
  2. 教程
从入门到精通 · 完整中文文档

Codex 使用教程

5 步快速上手 Codex，配合命令参考与常见问题解答，让你快速掌握这款强大的终端 AI 编程助手。

Codex 快速上手教程：安装、配置、运行三步流程
快速上手

5 步 开启 AI 编程

从安装到完成第一个 AI 编码任务，全程只需 5 步。

安装 Node.js 运行环境

Codex 需要 Node.js 18 或更高版本。访问官网下载安装，或使用包管理器安装。

安装 Node.js
# macOS (Homebrew)
$brew install node
# Ubuntu / Debian
$curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
$sudo apt-get install -y nodejs

安装 Codex CLI

通过 npm 全局安装 Codex，国内用户可使用淘宝镜像加速。

安装 Codex
$npm install -g @openai/codex
+ @openai/codex@1.0.0
$codex --version
codex/1.0.0

配置 OpenAI API 密钥

获取 OpenAI API Key，设置为环境变量。国内用户可配置代理或使用兼容 API。

配置密钥
# Linux / macOS
$export OPENAI_API_KEY=sk-your-api-key-here
# 写入配置文件持久化
$echo 'export OPENAI_API_KEY=sk-xxx' >> ~/.zshrc

进入项目目录启动 Codex

进入你的代码项目目录，运行 codex 启动交互式会话。

启动 Codex
$cd my-project
$codex
✓ Codex 已启动
Welcome! 输入你的开发需求开始

输入需求开始编程

用自然语言描述你的需求，Codex 会理解并执行。

交互示例
> 帮我添加用户登录接口，包含 JWT 鉴权
# Codex 分析代码库
读取 src/routes/ 目录...
建议创建 src/routes/auth.js
修改 src/app.js 添加路由
安装 jsonwebtoken 依赖
# 是否应用所有变更？(y/n)
>
命令参考

常用 命令与选项

掌握 Codex 命令行选项，灵活控制 AI 行为。

基础命令

# 启动交互式会话
codex

# 单次执行（非交互）
codex "修复所有 lint 错误"

# 静默模式，仅输出结果
codex --quiet "添加注释"

模型与模式

# 指定模型
codex --model gpt-5-codex

# 设置审批模式
codex --mode suggest
codex --mode auto-edit
codex --mode full-auto

# 全自动模式简写
codex --full-auto

配置选项

# 自定义 API 端点
codex --base-url https://api.example.com/v1

# 设置温度参数
codex --temperature 0.7

# 指定工作目录
codex --cd /path/to/project

实用技巧

# 结合管道使用
cat error.log | codex "分析错误并修复"

# 查看配置
codex config list

# 更新到最新版
npm update -g @openai/codex
配置文件

配置文件 详解

通过配置文件持久化你的偏好设置，避免每次启动都输入参数。

~/.codex/config.json
{
  "model": "gpt-5-codex",
  "mode": "auto-edit",
  "temperature": 0.7,
  "maxTokens": 4096,
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}
配置项 类型 说明 默认值
model string 使用的模型名称 gpt-5-codex
mode string 审批模式：suggest / auto-edit / full-auto suggest
temperature number 采样温度，0-2 之间 0.7
maxTokens number 最大生成 token 数 4096
mcpServers object MCP 服务器配置 {}
常见问题

FAQ 常见问题解答

关于 Codex 使用中最常见的问题与解答。

Codex 是 OpenAI 推出的开源 CLI 编码代理，可在终端本地运行，支持 GPT-5-Codex 等模型，能够读取修改文件、执行命令，帮助你完成编码任务。它是 OpenAI 在 GitHub 上开源的项目，采用 Apache 2.0 协议。
Codex CLI 本身完全免费开源（Apache 2.0 协议），但调用 OpenAI API 需要按使用量付费。你也可以通过 OSS 模式接入免费的本地开源模型，如通过 Ollama 运行 Llama、Qwen 等模型，完全免费使用。
Codex 支持 Windows 10/11、macOS（Intel 与 Apple Silicon）、Linux（Ubuntu、Debian、CentOS、Arch 等主流发行版）。可通过 npm 全局安装，macOS 还可通过 Homebrew 安装。
主要区别有三点：(1) 形态不同：Codex 是终端 CLI 工具，能直接执行命令和修改文件；Copilot 是 IDE 插件，主要提供代码补全。(2) 开源情况：Codex 完全开源（Apache 2.0），Copilot 闭源。(3) 模型支持：Codex 可接入任意 OpenAI 兼容模型，Copilot 仅支持 GitHub 模型。
国内用户可通过以下方式使用：(1) 使用 npm 淘宝镜像加速安装：npm install -g @openai/codex --registry=https://registry.npmmirror.com。(2) 配置 HTTP 代理访问 OpenAI API：export HTTPS_PROXY=http://127.0.0.1:7890。(3) 使用 OSS 模式接入国内可访问的模型代理服务或本地模型。
Codex 所有操作都在沙箱中执行，命令运行和文件修改都需要你确认。默认 Suggest 模式下，AI 只生成建议，不会自动执行任何操作。即使使用 Full-Auto 模式，也支持完整的变更预览与一键回滚，保证安全可控。
有三种方式切换模型：(1) 命令行参数：codex --model gpt-5-codex。(2) 配置文件：在 ~/.codex/config.json 中设置 model 字段。(3) 环境变量：export CODEX_MODEL=gpt-5-codex。
Codex 基于大语言模型，支持几乎所有主流编程语言，包括 JavaScript/TypeScript、Python、Java、Go、Rust、C++、Ruby、PHP、Swift 等。它能根据你的项目自动识别语言与技术栈。
常见解决方法：(1) 检查 Node.js 版本是否 ≥ 18。(2) 使用 sudo（Linux/macOS）或管理员权限（Windows）。(3) 清除 npm 缓存：npm cache clean --force。(4) 切换镜像源：npm config set registry https://registry.npmmirror.com。(5) 查看完整错误日志排查具体问题。
升级命令：npm update -g @openai/codex。如果是通过 Homebrew 安装：brew upgrade codex。建议定期升级以获取最新功能与 bug 修复。可使用 codex --version 查看当前版本。
在 ~/.codex/config.json 中添加 mcpServers 配置即可。例如接入 GitHub MCP 服务器：{"mcpServers":{"github":{"command":"npx","args":["-y","@modelcontextprotocol/server-github"]}}}。配置后重启 Codex 即可使用 GitHub 集成功能。
不会。Codex 本身不存储你的代码，所有操作在本地终端完成。代码片段会发送到 OpenAI API 进行推理（用于生成响应），受 OpenAI 数据政策约束。如果你担心隐私，可使用 OSS 模式接入本地模型，数据完全不离开你的机器。

还有 其他问题？

查看 GitHub 上的完整文档，或加入社区与其他开发者交流。我们持续更新教程与示例。

GitHub 文档 联系我们