如果你最近在关注AI编程助手，可能会发现一个现象：很多开发者都在讨论一个叫“Codex”的工具，但相关的教程要么过于零散，要么已经过时。更让人困惑的是，当你想尝试时，却发现从注册、安装到配置，每一步都可能遇到意想不到的障碍，尤其是在国内网络环境下。

这篇文章要解决的，正是这个看似简单实则暗藏玄关的问题： 如何在国内环境下，免费、稳定地安装和使用Codex，并真正让它为你所用，而不是停留在“安装成功”的幻觉里。

很多人以为安装Codex就是下载一个客户端，输入API Key。但实际上，从选择合适的版本、处理网络问题、配置开发环境，到理解其核心的“Skill”机制，每一步都决定了你最终的使用体验。本文将基于最新的信息，为你提供一个从零开始、手把手式的完整指南。你将不仅学会安装，更能理解Codex的工作原理、核心功能，并避开那些新手最容易踩的“坑”。

1. Codex究竟是什么？它解决了什么核心问题？

在深入安装步骤之前，我们必须先厘清一个关键问题：Codex到底是什么？很多人把它简单地等同于一个“代码生成AI”，这种理解是片面的，也导致了很多后续使用上的困惑。

Codex的核心定位是一个“AI Agent开发平台与运行时” 。你可以把它想象成一个“大脑”，这个大脑本身具备强大的代码理解和生成能力（基于类似GPT的模型），但它真正的威力在于能够调用各种“技能”（Skills）去执行具体的任务。这些技能可以是操作本地文件、执行Shell命令、调用Web API、操作数据库等等。

那么，它解决了什么痛点？

  1. 自动化复杂工作流 ：传统上，我们需要写脚本（Python/Bash）来串联不同的工具和步骤。Codex允许你用自然语言描述任务，它自动规划、调用合适的技能去完成。例如，“帮我分析这个项目目录下的所有Python文件，找出未使用的导入并生成报告”。
  2. 降低工具使用门槛 ：很多强大的命令行工具（如 ffmpeg , imagemagick , jq ）参数复杂。通过为这些工具封装成Codex Skill，你可以用“把这张图片转换成WebP格式，宽度调整为800px”这样的指令来操作。
  3. 上下文感知的编程辅助 ：与传统的代码补全插件不同，Codex Agent可以理解你整个项目的上下文、正在进行的对话历史，并主动执行一些重构、调试、测试生成等操作，而不仅仅是补全下一行代码。

因此，安装Codex不仅仅是安装一个软件，更是为你引入一个 可编程的AI协作者 。理解了这一点，后面的环境配置和Skill使用才会更有目的性。

2. 环境准备与前置条件

在开始安装前，请确保你的系统满足以下条件。这是后续所有步骤能顺利进行的基础。

2.1 硬件与操作系统要求

  • 操作系统 ：官方对Windows 10/11、macOS (10.15+) 和主流Linux发行版（如Ubuntu 20.04+）都提供了良好支持。本文将以 Windows 和 macOS 环境为主要演示。
  • 内存 ：建议至少 8GB 可用内存。运行大型语言模型需要一定内存开销。
  • 存储空间 ：预留至少 2GB 的可用磁盘空间用于安装和缓存。
  • 网络 ：这是国内用户最需要关注的一点。你需要一个 稳定、能够访问国际互联网的网络环境 ，用于下载安装包、模型以及调用某些在线API。请自行准备合规的网络工具。

2.2 软件依赖

Codex的运行依赖于几个关键组件，请按顺序安装：

  1. Python ：Codex的核心运行时和CLI工具基于Python。请安装 Python 3.8 至 3.11 之间的版本。不建议使用3.12+，可能存在未完全兼容的依赖。

    • 检查安装 ：打开终端（Windows CMD/PowerShell， macOS/Linux Terminal），输入： 
      python --version
或
python3 --version
    • 安装 ：前往 Python官网 下载对应版本，安装时务必勾选“Add Python to PATH”。

  2. Git ：用于克隆代码仓库和版本管理。

    • 检查安装 ： 
      git --version
    • 安装 ：前往 Git官网 下载安装。

  3. Node.js (可选但推荐) ：许多前端相关的Skill以及桌面版应用可能需要Node.js环境。

    • 检查安装 ： 
      node --version
npm --version
    • 安装 ：建议安装LTS版本，可从 Node.js官网 下载。

2.3 获取访问凭证（API Key）

Codex本身是开源平台，但其“大脑”（AI模型）通常需要接入一个后端。目前主流且对开发者友好的选择是 DeepSeek 或 OpenAI 的API。

  • DeepSeek ：对国内用户友好，提供免费额度，是当前性价比极高的选择。
  • OpenAI ：模型能力强，但需要国际支付方式且涉及网络访问。

以获取DeepSeek API Key为例：

  1. 访问 DeepSeek 开放平台 。
  2. 注册并登录账号。
  3. 在控制台中，找到“API Keys”部分，创建一个新的密钥。
  4. 妥善保管 这个密钥，它就像你的密码，不要直接提交到代码仓库中。

3. 安装Codex CLI（命令行工具）

Codex提供了多种使用方式，最灵活、最开发者友好的是其命令行工具（CLI）。我们将首先安装它。

3.1 通过pip安装（推荐）

这是最直接的方式。打开你的终端，执行以下命令：

pip install codex-cli

如果你系统中有多个Python版本，请使用 pip3 ：

pip3 install codex-cli

为了确保环境隔离，更推荐的做法是使用虚拟环境（venv）：

# 创建虚拟环境
python -m venv codex-env

# 激活虚拟环境
# Windows (CMD)
codex-env\Scripts\activate.bat
# Windows (PowerShell)
codex-env\Scripts\Activate.ps1
# macOS/Linux
source codex-env/bin/activate

# 在激活的虚拟环境中安装
pip install codex-cli

3.2 验证安装

安装完成后，运行以下命令验证是否成功：

codex --version
# 或
codex --help

如果成功，你会看到Codex CLI的版本信息和帮助命令列表。

4. 配置Codex：连接AI大脑

安装好CLI只是第一步，接下来需要配置Codex使用哪个AI模型作为引擎。

4.1 设置API Key环境变量

将之前获取的DeepSeek API Key设置为环境变量。这是保护密钥安全的最佳实践之一。

在终端中临时设置（会话有效）： 

# Windows (PowerShell)
$env:DEEPSEEK_API_KEY="你的实际API密钥"

# macOS/Linux
export DEEPSEEK_API_KEY="你的实际API密钥"

永久设置（推荐）：

  • Windows ：在“系统属性”->“高级”->“环境变量”中，新建用户变量，变量名 DEEPSEEK_API_KEY ，变量值为你的密钥。
  • macOS/Linux ：将 export DEEPSEEK_API_KEY="你的密钥" 添加到 ~/.bashrc , ~/.zshrc 或 ~/.profile 文件末尾，然后执行 source ~/.zshrc （根据你的shell）。

4.2 初始化Codex配置

运行初始化命令，CLI会引导你完成基本配置。

codex init

根据提示，你需要：

  1. 选择模型提供商（Provider）。这里输入 deepseek 。
  2. 输入模型名称。DeepSeek最新且免费的模型是 deepseek-chat ，输入即可。
  3. 当询问API Key时，如果你已经正确设置了环境变量 DEEPSEEK_API_KEY ，可以直接按回车，它会自动读取。否则，在此处粘贴你的密钥。

初始化成功后，会在你的用户目录下生成一个配置文件（通常是 ~/.codex/config.yaml ）。你可以随时编辑这个文件来调整配置。

5. 运行你的第一个Codex Agent

配置完成后，让我们通过一个最简单的交互来验证一切是否正常。

5.1 启动交互式会话

在终端中输入：

codex chat

如果一切顺利，你会看到类似以下的提示符，表示已经进入了一个与Codex Agent的对话会话中：

>

现在，你可以像和ChatGPT聊天一样，用自然语言向它提问。例如：

> 用Python写一个函数，计算斐波那契数列的第n项。

Codex会生成代码并显示。但这只是“聊天”，它并没有真正执行任何操作。

5.2 执行一个简单的Skill：文件操作

Codex的真正能力在于执行Skill。让我们尝试一个内置的、无需额外配置的Skill。

首先，退出聊天模式（输入 /exit 或按 Ctrl+C）。然后在普通终端中，尝试让Codex帮你创建一个文件：

codex run --skill file_system "在当前目录下创建一个名为test_hello.txt的文件，内容写上Hello from Codex!"

执行这个命令后，Codex会：

  1. 理解你的指令。
  2. 调用 file_system 这个内置技能。
  3. 在你的当前目录生成 test_hello.txt 文件。

用 cat test_hello.txt （或Windows的 type test_hello.txt ）命令检查文件内容。如果看到“Hello from Codex!”，恭喜你，你的第一个Codex Agent任务成功执行了！

6. 探索与安装更多Skill

内置技能有限，Codex的生态强大在于社区贡献的众多Skill。你可以将它们理解为这个AI协作者的“武器库”。

6.1 查找可用的Skill

Codex CLI内置了Skill发现功能。运行：

codex skill search <关键词>

例如，搜索与网络相关的技能：

codex skill search http

这会列出所有名称或描述中包含“http”的Skill。

6.2 安装Skill

找到想要的Skill后，使用 install 命令安装。例如，安装一个用于发送HTTP请求的Skill：

codex skill install http_request

安装后，这个Skill就可以在你的 codex run 命令中使用了。

6.3 使用已安装的Skill

让我们用刚安装的 http_request Skill 来查询一个公开API：

codex run --skill http_request "向 https://api.github.com/users/octocat 发送一个GET请求，获取用户信息，并把响应中的‘login’和‘public_repos’字段打印出来。"

Codex会规划并执行以下步骤：

  1. 使用 http_request Skill 构造请求。
  2. 发送请求并获取响应。
  3. 解析JSON响应。
  4. 提取指定字段并格式化输出。

通过组合不同的Skill，你可以完成极其复杂的自动化任务。

7. 进阶：Codex桌面版与IDE插件

除了CLI，Codex还提供了更直观的桌面应用和IDE插件，适合不同的使用场景。

7.1 Codex桌面版安装与使用

桌面版提供了图形化界面，方便管理对话、Skill和查看执行历史。

安装： 通常可以通过包管理工具安装，或从GitHub Releases页面下载。

  • macOS (Homebrew) : 
    brew install --cask codex
  • Windows/Linux : 访问Codex的GitHub仓库，在Releases页面下载对应系统的安装包（.exe, .deb, .rpm等）。

使用：

  1. 安装后打开Codex桌面应用。
  2. 首次启动需要配置API Key和模型（与CLI配置类似，在设置中完成）。
  3. 你可以在界面中直接聊天，也可以创建“工作流”（Workflow），以可视化方式串联多个Skill。

7.2 IDE插件（以VSCode为例）

对于开发者，在IDE中直接集成Codex效率最高。

  1. 打开VSCode，进入扩展市场（Ctrl+Shift+X）。
  2. 搜索“Codex”或“Codex Agent”。
  3. 找到官方或高星插件（例如 Codex 或 Continue ），点击安装。
  4. 安装后，插件通常会要求你配置API Endpoint和Key。根据插件文档，填入你的DeepSeek API信息。
  5. 配置完成后，你可以在代码编辑器中通过快捷键（如 Ctrl+I ）唤醒Codex，针对选中的代码块进行解释、重构、生成测试等操作，体验深度集成的编程辅助。

8. 常见问题与排查思路（避坑指南）

在这一部分，我们集中解决安装和使用过程中最常见的问题。

问题现象 可能原因 排查方式 解决方案
codex --version 命令未找到 1. pip安装失败或未添加到PATH。
2. 虚拟环境未激活。		 1. 运行 pip list | grep codex 检查是否安装。
2. 检查终端提示符前是否有 (codex-env) 等虚拟环境标识。		 1. 重新安装： pip install --upgrade codex-cli 。
2. 确保在安装的虚拟环境中操作。
codex init 或 codex chat 时报网络连接错误 1. 网络环境问题，无法访问模型API。
2. API Key无效或未设置。
3. 模型提供商URL配置错误。		 1. 使用 curl 或浏览器测试能否访问 api.deepseek.com 。
2. 运行 echo $DEEPSEEK_API_KEY (macOS/Linux) 或 echo %DEEPSEEK_API_KEY% (Windows CMD) 检查密钥。
3. 检查 ~/.codex/config.yaml 中的 base_url 配置。		 1. 确保使用合规的网络工具。
2. 重新设置正确的API Key环境变量。
3. DeepSeek的 base_url 应为 https://api.deepseek.com 。
运行Skill时提示 Skill ‘xxx‘ not found 1. Skill名称拼写错误。
2. 该Skill未安装。		 运行 codex skill list 查看所有已安装的Skill。 1. 检查拼写。
2. 使用 codex skill install <skill_name> 安装。
Codex生成的代码或操作有误 1. 指令描述不够清晰。
2. 模型理解有偏差。
3. 缺少必要的上下文。		 1. 回顾指令是否模糊。
2. 在 codex chat 交互中，提供更多背景信息。		 1. 尝试更具体、分步骤的指令。
2. 在对话中先提供相关代码或文件内容，再要求操作。
3. 对于关键操作，先让Codex解释它的计划（“你打算如何完成这个任务？”），确认无误后再执行。
桌面版或插件无法连接 1. 桌面版/插件的配置与CLI不一致。
2. 防火墙或安全软件阻止。		 1. 对比桌面版设置与 ~/.codex/config.yaml 的内容。
2. 查看应用日志。		 1. 确保桌面版和插件中配置的API Key、模型名称、Base URL与CLI配置一致。
2. 临时关闭防火墙或安全软件测试。
执行文件操作等技能时权限被拒绝 Codex Agent进程没有足够的权限读写目标目录或文件。 检查目标文件/目录的权限（ ls -l 或文件属性）。 1. 将工作目录切换到有权限的路径。
2. 以管理员/root权限运行（不推荐，有安全风险）。

9. 最佳实践与安全建议

将Codex集成到你的工作流中时，请遵循以下原则以确保高效和安全：

  1. 从沙盒环境开始 ：初期尝试时，在一个独立的、不重要的项目目录或虚拟机中操作。避免直接在核心生产代码或敏感数据目录中运行具有文件写入、命令执行能力的Skill。
  2. 最小权限原则 ：不要轻易授予Codex过高权限。例如，避免让它拥有直接执行 rm -rf / 或格式化磁盘等危险命令的能力。仔细审查你安装的Skill的源代码和权限要求。
  3. 审查计划再执行 ：对于复杂的、尤其是涉及修改或删除的操作，先使用 codex chat 模式，让它“解释它将如何做”，审查其计划步骤，确认无误后再在 run 模式中执行。
  4. 善用上下文 ：Codex的强大在于理解上下文。在聊天或执行任务前，可以通过上传文件、切换工作目录等方式，为它提供充足的背景信息，这将极大提高任务完成的准确率。
  5. 组合Skill实现复杂功能 ：不要期望一个指令完成所有事。将大任务拆解，思考如何组合不同的Skill。例如，先用 file_system 遍历文件，再用 code_analysis 分析代码，最后用 http_request 将结果发送到服务器。
  6. 管理API成本 ：即使是免费额度的API，也有调用次数或Token限制。在 config.yaml 中可以考虑设置频率限制，并关注你的API使用情况仪表板。
  7. 版本控制你的配置和Skill ：将你的 ~/.codex/config.yaml 和自定义的Skill定义文件纳入版本控制（如Git），方便在不同机器间同步和回滚。

Codex代表的是一种新的范式：从“人适应工具”到“工具理解人”。它的安装和配置只是起点，真正的价值在于你如何将它融入你的开发流程，用它来自动化那些重复、繁琐的任务，从而释放你的精力去关注更具创造性的设计和解法。现在，你已经拥有了启动这一切的钥匙。不妨从一个具体的、你日常工作中耗时的小任务开始，尝试用Codex来解决它，亲身体验AI协作为开发效率带来的变革。

Logo
亚马逊云科技技术品牌专区

更多推荐

cover

别再只聊大模型！AI的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区
cover

别再只聊大模型！人工智能的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区
cover

别再只聊大模型！AI的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区