Codex 安装教程

前言

教程是基于Window操作系统，所有命令都是在PowerShell里面执行，不是CMD窗口。

升级 PowerShell

安装 PowerShell 7.x 版本，win10系统默认的是5.x，操作体验上与7.x有很大差距(命令类型/自动补全等)，提议升级（与5.x是独立的程序，新版本启动是 pwsh）。

set-ExecutionPolicy RemoteSigned #允许脚本执行（选A-全是）
$PSVersionTable  #查看当前版本
winget install --id Microsoft.PowerShell --source winget #安装PowerShell 7.x

如果失败或者无效，可以手动下载后双击安装：
https://github.com/PowerShell/PowerShell/releases/download/v7.6.0/PowerShell-7.6.0-win-x64.msi

安装 Windows Terminal

Window 11 有自带多窗口效果，但 Window 10 安装此工具之后启动则会带多窗口效果，使用更方便。

winget install --id=Microsoft.WindowsTerminal -e

如果无法安装，则可以手动下载
https://github.com/microsoft/terminal/releases

下载最新版本（zip包），安装完成后，可以直接搜索wt，即可启动，如果是手动下载的zip包，则解压启动WindowsTerminal.exe即可（可以直接将它创建快捷方式放到快速启动栏）。

安装 NodeJS

后续许多安装命令以及环境运行都依赖nodejs，属于必须安装的系统依赖。官网下载链接：
https://nodejs.org/zh-cn/download 。

页面往下滚动，找到“Windows安装程序 msi”，用安装包可以不用手动添加环境变量，更方便快捷，下载完成后双击安装即可，安装完成后就可以使用 node、npm、npx 命令。

node -v # 验证 Node.js 版本
npm -v # 验证 npm 版本
npx -v # 验证 npx 版本

安装 Codex

桌面端版本

访问官网下载安装包，双击安装即可（需要代理）：
https://openai.com/zh-Hans-CN/codex/

【可选】如果没有代理的话，可以从微软商店里面安装，Micrsoft Store 直接搜索 codex 。

命令行CLI版本

通过npm包管理器来安装（依赖nodejs环境），不用使用代理即可安装。

npm install -g @openai/codex    #安装codex
npm update -g @openai/codex     #更新codex

初次使用

桌面端直接启动程序，即可正常使用。命令行CLI版本则输入 codex 即可进入使用。后续以自然语言对话即可。

首次使用时，会提示选择登录方式：

1. 官方订阅；
2. 官方订阅临时登录；
3. 官方APIKEY。

如果是使用官方订阅或官方APIKEY的可以直接选择对应选项下一步即可，如果是第三方API，大家可以直接退出，然后按下一章节进行配置即可。

第三方API配置

补充基础知识，目前市面上的模型所支持的协议，主要分为两个阵营，如下所示（各类中转站一般都是同时兼容两种协议），国内模型大都属于OpenAI阵营（由于它上市最早，确定行业标准，更为主流）：

• OpenAI (Chat Completions / Response) 协议：以gpt为代表，其中 codex、gemini则是支持这种协议，如果要使用claude模型，那么则需要通过中转站代理中转；
• Anthropic (Messages API) 协议：以claude为代表，其中claude则是支持这种协议，如果要使用gpt模型，那么则需要通过中转站代理中转；

第一 cluade、codex、gemini 三大主流AI编程CLI，其相关配置的目录都是在 当前用户目录 下，linux/window都可以通过 cd ~/ 即可进入当前用户目录，后续所有提到的路径中 ~/ 字符都是指当前用户目录。

• window：C:Usersapliu 其中'apliu'是系统用户名称；
• linux: /home/ubuntu 其中'ubuntu'是系统用户名称；

codex主要涉及到 ~/.codex/ 文件夹，大致目录结构如下所示（刚开始没有这么多，随着使用会陆续生成）：

● .codex
  ├─ .sandbox/                  # 沙箱相关目录
  ├─ .sandbox-bin/              # 沙箱可执行文件或辅助工具目录
  ├─ .sandbox-secrets/          # 沙箱使用的敏感信息/密钥目录
  ├─ .tmp/                      # 隐藏临时目录
  ├─ log/                       # 日志目录
  ├─ memories/                  # 记忆数据目录
  ├─ rules/                     # 规则配置目录
  ├─ sessions/                  # 会话数据目录
  ├─ skills/                    # 技能/扩展能力目录
  ├─ sqlite/                    # SQLite 相关数据目录
  ├─ tmp/                       # 临时文件目录
  ├─ vendor_imports/            # 外部导入资源目录
  ├─ .codex-global-state.json   # Codex 全局状态文件
  ├─ .personality_migration     # 人格/配置迁移标记文件
  ├─ AGENTS.md                  # Agent 行为说明文件
  ├─ auth.json                  # 认证信息配置文件
  ├─ cap_sid                    # 会话或能力标识文件
  ├─ config.toml                # 主配置文件
  ├─ history.jsonl              # 历史记录文件
  ├─ logs_1.sqlite              # 日志数据库
  ├─ logs_1.sqlite-shm          # SQLite 共享内存文件
  ├─ logs_1.sqlite-wal          # SQLite WAL 日志文件
  ├─ models_cache.json          # 模型缓存信息文件
  ├─ sandbox.log                # 沙箱运行日志
  ├─ state_5.sqlite             # 状态数据库
  ├─ state_5.sqlite-shm         # SQLite 共享内存文件
  ├─ state_5.sqlite-wal         # SQLite WAL 日志文件
  └─ version.json               # 版本信息文件

虽然目录许多，但对于我们配置来说只需要关注 ~/.codex/config.toml 和 ~/.codex/auth.json 两个文件，config.toml 文件中配置 base_url （接口调用URL），auth.json 文件中配置了 api_key （接口认证KEY），所有第三方API都是修改这两个参数即可，所以使用第三方API，就是获取到这两个参数就行。

如下所示格式，如果文件不存在，则可以手动新建一个txt重命名后，再将下方内容拷贝到文件中修改 base_url 以及 api_key 保存，然后重新启动codex就可以跳过登录直接使用了。

codex的base_url 一般包含/v1，且末尾符不要/

config.toml 文件格式如下：

model_provider = "customapi"
model = "gpt-5.4"
model_reasoning_effort = "medium"


[model_providers.customapi]
name = "customapi"
base_url = "https://api.xxxxxx.com/v1"
wire_api = "responses"

auth.json 文件格式如下：

{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxx"
}

参考资料

官方文档相关资料（需要有代理才可以访问）：
https://developers.openai.com/codex/cli/reference