Codex = 一个愿意花 10+ 分钟思考，一次性给你写出生产级代码的狠角色。

AI 编程这两年已经从一个新鲜概念变成了开发标配。2025 至 2026 年间，AI 编程助手从浏览器和 IDE 插件走向了终端，开发者现在更希望 AI 能直接进入项目目录、理解代码结构、修改文件、执行命令，甚至参与日常的重构、调试和自动化流程。在这场终端 AI 编程的竞赛中，OpenAI 的 Codex 无疑是最值得关注的工具之一。

本文将以实战为核心，带你从零开始完整掌握 Codex CLI 的安装、使用和进阶技巧，并提供一个真实的 C# 集成案例，帮助你快速将 Codex 融入日常开发工作流。

📍 本文基于 2026 年 4 月的公开信息整理，涵盖安装配置、核心用法、最佳实践与实战案例。

一、Codex CLI 安装与配置：从零到运行的完整指南

1.1 安装前提

• Node.js >= 22
• npm >= 10

1.2 安装 Codex CLI

最推荐的安装方式是通过 npm 全局安装，这也是官方推荐的方式：

npm install -g @openai/codex

国内用户建议使用镜像源加速：

npm install -g @openai/codex --registry=https://registry.npmmirror.com

验证是否安装成功：

codex --version

如果命令正常输出版本信息，说明安装完成。

其他可选安装方式：

平台	安装方式	适用场景
macOS	brew install --cask codex	Homebrew 用户
Windows	建议在 WSL 中运行	获得更稳定的类 Linux 体验
预编译二进制	从 GitHub Releases 下载	无 Node.js 环境

1.3 登录认证

首次运行 codex 命令会自动进入登录流程，有两种登录方式可选：

方式一：ChatGPT 账号登录（推荐）

codex

浏览器会自动打开授权页面，登录 ChatGPT 账号后即可开始使用。这种方式适合个人开发者日常使用。

方式二：API Key 登录

export OPENAI_API_KEY="sk-xxxxxxxxxxxx"
codex

或者将 API Key 写入环境配置文件永久生效：

echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

1.4 指定模型

Codex 默认使用 GPT-5.3 模型，如需使用更强的 GPT-5.4 处理复杂任务：

codex --model gpt-5.4

或将模型配置写入项目级配置文件，以便长期固定使用。

⚠️ 国内使用建议：如遇网络问题，可配置 cc-switch 等中转工具解决 API 访问稳定性问题。

二、Codex 的核心使用模式

很多人第一次用 Codex 都会纠结一个问题：“到底是一直 codex xxx 一次性调用，还是进去之后再对话？”这两种用法分别对应 命令模式 和 交互模式，本质上是“调用 AI”和“雇佣 AI”的区别。

2.1 命令模式：一次性调用

命令模式适合快速任务、脚本和 CI 流程。用法非常简单：

codex "帮我写一个 C# 的 JSON 解析函数"

Codex 会直接执行并输出结果，执行完就结束。

适用场景：

• 快速生成代码片段
• CI 自动化脚本中的简单任务
• 一次性代码补全

2.2 交互模式：真正的 Agent

交互模式才是 Codex 真正强大的地方。进入交互模式后，你将拥有一个可以持续对话、理解项目上下文、连续执行复杂任务的 AI 员工：

codex

进入之后，你可以像和同事对话一样连续下达任务：

帮我分析这个项目的代码结构
给这个服务加上 Redis 缓存
写单元测试
跑测试并修复失败用例

Codex 会逐步完成分析、修改文件、执行命令、修复 bug 的完整流程。

交互模式的核心优势：

• ✅ 有上下文记忆，不用每次都从头解释
• ✅ 支持连续任务，可以逐步迭代
• ✅ 能自动执行复杂工程任务
• ✅ 可以读取整个项目结构

💡 推荐日常开发优先使用交互模式。命令模式是“调用 AI”，交互模式才是“雇佣 AI”。

三、Codex 最佳实践：让它真正成为你的队友

OpenAI 官方发布的最佳实践强调了一个核心理念：不要把 Codex 当作一次性助手，而是要把它当作自己的队友，随着时间的推移进行配置和改进。

3.1 提示词四要素结构

优秀的提示词通常包含四个部分：

1. 目标：你想要改变什么或构建什么？
2. 上下文：哪些文件与此任务相关？（使用 @ 符号提及特定文件）
3. 约束：必须遵守的架构规则、安全要求或约定
4. 完成条件：完成的标准，例如测试通过、Bug 不再复现

示例：

codex

进入后输入：

目标：在用户管理模块中增加缓存层
上下文：@UserService.cs @UserRepository.cs
约束：不能破坏现有接口签名，必须保持 100% 单元测试通过
完成条件：所有现有测试通过 + 缓存命中率达到 80%

3.2 使用 @ 符号聚焦上下文

在提示词中使用 @filename 可以让 AI 只关注相关文件，而不是扫描整个仓库。这样能够显著减少 token 消耗，降低答非所问的概率，防止上下文爆炸。

对于大型项目，特别建议将构建产物、自动生成代码、第三方缓存等目录排除在主要上下文之外。

3.3 善用 Plan 模式

当任务复杂、模糊或难以描述时，在开始编码之前先进行规划。Plan 模式允许 Codex 先收集上下文、提出问题，并在实施前制定更完善的计划。

使用方式：在交互模式中输入 /plan 或按 Shift + Tab 切换。

3.4 使用 AGENTS.md 进行重复指导

当某个提示词奏效后，不要反复手动输入，而是把它写进 AGENTS.md 中。这个文件会自动加载进上下文，用来定义 Codex 在你仓库中的工作方式。

一个实用的 AGENTS.md 通常包含：

• 仓库结构与关键目录
• 如何运行项目
• 构建、测试与 lint 命令
• 工程规范与 PR 期望
• 约束与禁止模式
• 完成标准与验证步骤

💡 想进一步提升 Codex 的稳定性和复用性，可以关注 Codex Skills——它将重复工作流封装为标准化技能包，解决 Codex 执行复杂任务时的不稳定和上下文丢失问题。

四、实战案例：在 C#/.NET 项目中集成 Codex

下面分享一个真实的 C# 集成案例——如何在不引入 Node.js 运行时的情况下，在 .NET 项目中原生调用 Codex。

4.1 背景与挑战

在一个开源 AI 代码助手项目 HagiCode 中，需要在纯 .NET 环境（C# 后端服务和桌面端应用）里使用 Codex。摆在面前的只有两条路：

1. 维护一套复杂的 Node.js 桥接层
2. 自己动手，实现一个原生 C# SDK

项目团队选择了后者。目标不是简单翻译代码，而是让 C# SDK “神似"而非"形似”——对外暴露的 API 要保持一致，让熟悉 TypeScript 版本的开发者能零成本上手；但在内部实现上，得充分利用 C# 的语言特性和 .NET 生态的优势。

4.2 技术要点

官方 TypeScript SDK 的核心架构是通过调用 codex exec --experimental-json 命令与 Codex CLI 交互，解析 JSONL 格式的事件流。移植到 C# 时，需要处理以下几个关键问题：

类型系统映射：

TypeScript	C#	说明
interface / type	record	使用不可变数据结构
string | null	string?	可空引用类型
boolean | undefined	bool?	可空布尔值
AsyncGenerator	IAsyncEnumerable	异步迭代器

事件类型系统：TypeScript 使用联合类型定义事件，C# 中使用继承层次和模式匹配实现相同效果：

public abstract record ThreadEvent(string Type);
public sealed record ThreadStartedEvent(string ThreadId) : ThreadEvent("thread.started");
public sealed record TurnStartedEvent() : ThreadEvent("turn.started");

进程管理：使用 CancellationToken 替代 TypeScript 的 AbortSignal，实现跨平台子进程管理。

4.3 架构一致性

C# SDK 保持了与 TypeScript 版本相同的架构层次：

Codex (入口类)
└── CodexExec (执行器，管理子进程)
    └── Thread (对话线程)
        ├── run() / runStreamed() (同步/异步执行)
        └── 事件流解析

整体思路是保持 API 的一致性，但在实现上充分利用 C# 语言特性。

📌 上述 C# 移植方案来自开源项目 HagiCode，如果想深入了解更多细节或获取完整代码，可以在 GitHub 上关注 HagiCode-org/site。

五、避坑指南

5.1 Windows 用户常见问题

Windows 用户是最容易踩坑的一类。很多命令行 AI 工具虽然“理论支持 Windows”，但在实际环境里，往往会遇到路径、权限、Shell、沙箱、环境变量等兼容性细节。

建议方案：

• 优先在 WSL 中运行 Codex CLI，获得更稳定的类 Linux 开发体验
• 或直接使用 Codex App（桌面应用）降低环境折腾成本
• 或使用 VS Code 中的 Codex 扩展

5.2 推理级别选择

Codex 提供多个推理强度级别，最强推理难度并不一定会达到最理想的结果：

• 低：快速、范围清晰的任务
• 中或高：复杂改动或调试
• 极高：长时间、需要主动思考和推理的任务

5.3 大型仓库的效率技巧

对于 Android 工程等大型项目，建议把以下几类目录排除在主要上下文之外：构建产物、自动生成代码、第三方缓存、图片和视频资源。它们要么无助于解决当前问题，只会浪费 token。

六、写在最后

Codex CLI 的价值远不止“代码补全”。它是一个可以在本地项目目录中直接调用的编码代理，让模型围绕真实代码仓库完成分析、修改与执行任务。

从安装到使用，从命令模式到交互模式，从提示词技巧到 C# 实战集成——Codex 正在从“写代码”走向“做工程”。无论你使用什么语言或技术栈，都值得尝试将这个终端 AI 编程助手融入你的日常开发工作流。

📌 本文所有命令和配置示例基于 Codex CLI 0.118.0 版本，更详细的官方文档可访问 OpenAI Codex CLI 官方文档。