Codex 使用教程：安装 CLI、IDE 插件与 App，config.toml 配置、AGENTS.md 与常用命令

第一步

先选用哪种形态：CLI、IDE 插件、桌面 App 还是 Codex Cloud

四种形态调用的是同一个 Codex 智能体，差别在运行位置、能访问的文件和登录要求。CLI 和 IDE 插件读同一份 ~/.codex/config.toml 和同一份登录缓存，在一处登录后另一处直接可用。

数据只在本机或课题组服务器上时，选 CLI 或 IDE 插件。Codex Cloud 的任务只能访问云端环境里的仓库和服务，本机文件、已登录的浏览器和 VPN 不会带过去，大体量原始数据也不适合放进 GitHub 仓库。

在课题组服务器上工作时，先把 CLI 在服务器上跑通，再配 IDE 插件的 Remote-SSH。CLI 能单独验证代理、证书和登录，插件出问题时更容易定位。

免费版和 Go 套餐只能在桌面 App 中使用 GPT-6 Luna（逐步开放）；Plus（每月 20 美元）起可以在网页、CLI、IDE 插件和 iOS 上使用，并包含 GPT-6.1 Sol。

安装

安装 Codex CLI 与安装失败的处理

官方给出四种安装方式，安装和升级用同一条命令。装完先运行 codex --version 和 codex doctor，确认二进制、配置、登录和网络。

# macOS / Linux：官方安装脚本（安装与升级相同）
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows：在新的 PowerShell 窗口中运行
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# npm（Node 16+；国内可加 --registry=https://registry.npmmirror.com）
npm install -g @openai/codex

# Homebrew
brew install --cask codex      # 升级：brew upgrade --cask codex

# 验证
codex --version                # 本页核对版本：codex-cli 0.162.1
codex doctor --summary         # 安装、配置、登录、网络、沙箱逐项检查

登录

ChatGPT 账号登录与 API Key 登录的差异

本机的 CLI、IDE 插件和桌面 App 两种方式都支持。选择取决于你按套餐额度用还是按 token 付费，以及是否需要 Codex Cloud。

登录信息缓存在 ~/.codex/auth.json 或系统钥匙串，由 cli_auth_credentials_store（file / keyring / auto / ephemeral）决定。CLI 和 IDE 插件共用这份缓存，在任一处退出后两处都要重新登录。

设备码登录需要先在 ChatGPT 的安全设置中开启（工作区账号由管理员在工作区权限中开启）。登录失败时查看日志目录下的 codex-login.log。

在国内使用，操作层面需要稳定的国际网络和 ChatGPT 账号或 OpenAI API Key。代理建议写成 HTTP 代理变量：有用户在 Windows 上把 SOCKS5 代理变量改成 HTTP 代理变量并设置 NO_PROXY 后，ChatGPT 后端请求的断流消失（GitHub #20844）。接第三方网关时，网关需要支持 Responses 协议，只提供 Chat Completions 接口的服务无法接入当前版本。官方订阅、API 中转站、国产模型三种路线的比较见 /compare/codex-claude-code-china。

codex login                    # 浏览器登录 ChatGPT 账号
codex login --device-auth      # 设备码登录：服务器、无浏览器环境
printenv OPENAI_API_KEY | codex login --with-api-key   # API Key 登录
codex login status             # 已登录返回 0，未登录打印 Not logged in 并返回 1
codex logout

# 服务器无浏览器且设备码不可用：把回调端口转发到本机后再登录
ssh -L 1455:localhost:1455 user@server
codex login                    # 在本机浏览器打开终端打印的地址

# 或把本机的登录缓存复制过去（auth.json 等同密码）
ssh user@server 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json

# Linux / macOS 终端：用 HTTP 代理变量，本机地址不走代理
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,::1

# macOS 上从程序坞启动的 ChatGPT 桌面 App 不读 shell 变量，需要设到 launchd 后重启 App
launchctl setenv HTTPS_PROXY http://127.0.0.1:7890
launchctl setenv HTTP_PROXY http://127.0.0.1:7890

# 公司代理或自签根证书
export CODEX_CA_CERTIFICATE=/path/to/root-ca.pem   # 未设置时回退到 SSL_CERT_FILE

# 只换内置 OpenAI 服务的地址（不新建 provider），写在 ~/.codex/config.toml
openai_base_url = "https://gateway.example.com/v1"

配置

~/.codex/config.toml 常用配置逐项说明

配置按以下顺序生效，排在前面的覆盖后面的：命令行参数与 -c 覆盖 → 项目内 .codex/config.toml（从项目根到当前目录，越近越优先，只对信任的项目生效）→ --profile 选择的 ~/.codex/<名称>.config.toml → ~/.codex/config.toml → 系统 /etc/codex/config.toml → 内置默认值。

# ~/.codex/config.toml  （Codex CLI 0.162.1 用 --strict-config 校验通过）
# 根级键必须写在第一个 [表] 之前，写在表后会变成该表的字段并被忽略
model = "gpt-6.1-sol"              # 账号无权限时改为 gpt-6-luna
model_reasoning_effort = "medium"  # low / medium / high / xhigh，取决于模型
approval_policy = "on-request"     # 只有 on-request、never 两个值
sandbox_mode = "workspace-write"   # read-only / workspace-write / danger-full-access
web_search = "cached"              # cached（默认）/ live / indexed / disabled
file_opener = "vscode"             # 输出里的文件路径可点击打开
project_doc_max_bytes = 65536      # AGENTS.md 合计上限，默认 32768

[sandbox_workspace_write]
network_access = false             # 需要 pip/conda 联网安装时改为 true
writable_roots = []                # 额外可写目录，例如 ["/Users/me/scratch"]

[history]
persistence = "save-all"           # "none" 不在本机保存会话记录

# MCP：本地 stdio 服务器
[mcp_servers.papers]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/papers"]
startup_timeout_sec = 20           # 默认 10
tool_timeout_sec = 60              # 默认 60

# MCP：远程 HTTP 服务器，暂时停用
[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
bearer_token_env_var = "CONTEXT7_API_KEY"
enabled = false

# 自定义模型网关（只支持 Responses 协议）
[model_providers.mygateway]
name = "My OpenAI-compatible gateway"
base_url = "https://gateway.example.com/v1"
env_key = "MYGATEWAY_API_KEY"      # 写环境变量名，不写 Key 本身
wire_api = "responses"
request_max_retries = 4
stream_idle_timeout_ms = 300000

# 信任某个项目，使其 .codex/config.toml 生效
[projects."/Users/me/research/rnaseq-2026"]
trust_level = "trusted"

# ~/.codex/gateway.config.toml  ——  codex -p gateway
model_provider = "mygateway"
model = "gpt-6.1-sol"

# ~/.codex/deep.config.toml  ——  codex -p deep
model_reasoning_effort = "high"

# 单次覆盖，值按 TOML 解析，字符串要带引号
codex -c model_reasoning_effort='"high"' -s read-only
codex exec -p deep "复核 scripts/02_model.py 的统计方法"

• 改完配置运行 codex exec --strict-config "hi"：配置中有当前版本不认识的字段时会报 unknown configuration field 并指出行号，配置无误时开始正常运行（未登录时随后报 401）。
• codex doctor --all 的 config 一项会列出被忽略的字段，例如 Codex is ignoring 2 unrecognized configuration settings。
• 交互会话中 /status 显示当前模型、审批策略、可写目录和剩余上下文；/debug-config 显示每一层配置来自哪个文件。
• 项目内 .codex/config.toml 不能设置 model_provider、model_providers、openai_base_url、profile 等，写了会在启动时警告并忽略。
• codex mcp add <名称> -- <命令> 或 codex mcp add <名称> --url <地址> 会写入 config.toml；codex mcp list 查看已配置的服务器及启用状态。

版本差异

旧教程照抄会出错的写法

Codex CLI 更新频繁，2025 年到 2026 年上半年的教程中有不少写法已经失效。下表的报错原文均为本页在 Codex CLI 0.162.1 中实际触发的输出。

AGENTS.md

AGENTS.md：放在哪里、怎么合并、怎么写

AGENTS.md 是普通 Markdown 文件，Codex 在每次启动会话时读取并放进第一轮上下文。它用来写这个项目长期有效的规则：目录约定、运行命令、哪些文件不能动、完成的标准。

本页用 codex debug prompt-input 查看实际注入模型的内容（Codex CLI 0.162.1，不需要登录）：在项目根启动时，只加载全局文件和根目录 AGENTS.md，analysis/ 等子目录里的 AGENTS.md 不会加载；在 analysis/deseq/ 启动时，路径上的四个文件全部加载；analysis/ 中同时有 AGENTS.override.md 时，该目录只取 override。把根目录 AGENTS.md 加到 40 KB 后，在默认上限下根文件被截断，analysis/ 和 deseq/ 的规则都没有进入上下文。

因此，子目录专用的规则只有在该子目录启动 Codex（codex -C analysis/deseq）时才生效；需要始终生效的规则写在根目录，根目录文件保持精简。

/init 会在当前目录生成一份 AGENTS.md 草稿，提交前删到只剩必要规则。ETH Zürich 对 AGENTS.md 的评测（arXiv 2602.11988，ICLR 2026）发现，在 SWE-bench 等代码任务中，上下文文件总体略微降低任务成功率，推理成本增加 20% 以上；智能体会认真执行文件中的要求，多余的要求让任务更难。作者建议人工编写、只写最少的必要要求。官方计费文档也把“缩小 AGENTS.md”列为节省额度的方法。

检查加载了哪些文件：在交互会话中问“列出你加载的指令文件”，或用 codex -c log_dir=./.codex-log 启动后查看 codex-tui.log。

# AGENTS.md（放在课题仓库根目录）

## 目录约定
- data/raw/：原始数据，只读。不修改、不移动、不覆盖、不重新编码。
- data/processed/：由 scripts/ 中的脚本从 data/raw 生成，可以整体删除重建。
- scripts/：按编号命名（01_qc.py、02_model.R），每个脚本只读上一步的输出。
- results/<日期>_<简述>/：每次运行一个目录，图表、表格、日志都放在里面。

## 运行要求
- 环境：conda 环境 rnaseq-2026（environment.yml）。缺包时先说明，不自行升级已有包。
- 随机过程固定种子 20261010，并写入运行日志。
- 每次运行在结果目录写 RUN.md：执行的命令、输入文件及其 md5、软件与包版本、参数、耗时、输出文件列表。
- 统计检验写明检验方法、多重校正方法和阈值，阈值不在运行中途修改。

## 修改范围
- 只改 scripts/ 和 results/。改动共享函数前先说明影响哪些脚本。
- 结果和预期不符时报告差异，不通过改阈值或删样本让结果"变好"。

## 完成标准
- 脚本可以从干净的 data/processed 重新跑出同样的结果。
- 回复中列出改动的文件和需要我人工核对的地方。

1. 01

   全局层

   ~/.codex/AGENTS.override.md 存在时只读它，否则读 ~/.codex/AGENTS.md。适合写跨项目的个人习惯，例如回复语言、常用包管理器。

2. 02

   项目层

   从项目根（默认是含 .git 的目录，可用 project_root_markers 修改）一路走到你启动 Codex 的当前目录，每个目录依次找 AGENTS.override.md、AGENTS.md、project_doc_fallback_filenames 中的文件，每个目录最多取一个。

3. 03

   合并

   按“全局 → 根目录 → 当前目录”的顺序拼接，离当前目录越近的越靠后，冲突时以后出现的为准。空文件跳过。

4. 04

   上限

   合计超过 project_doc_max_bytes（默认 32 KiB）时截断，路径上更深的文件会被整份丢掉。

命令

常用命令、斜杠命令与快捷键

下表按 codex --help 与官方 Developer commands 文档整理，只列日常会用到的部分。

非交互与会话

codex exec 非交互运行与恢复会话

codex exec 运行完一个任务就退出，进度写到 stderr，只有最终回复写到 stdout，可以直接重定向或接管道。它和交互模式有三处默认值不同，写脚本前先确认。

会话记录保存在 ~/.codex/sessions 下。codex resume --last 默认只在当前目录的会话中找，换了目录要加 --all；会话保存的目录与当前目录不同时，Codex 会询问用哪个，可用 tui.resume_cwd 固定选择。--ephemeral 运行的会话不落盘，之后无法恢复。

需要固定格式的结果（例如每个样本的 QC 判定）时，用 --output-schema schema.json 约束最终回复为指定 JSON 结构，再配合 -o 写入文件。

# 在项目目录运行一次分析，最终回复写入文件（进度输出到 stderr）
cd ~/research/rnaseq-2026
codex exec --sandbox workspace-write \
  -o results/2026-10-10_qc/codex_summary.md \
  "按 AGENTS.md 运行 scripts/01_qc.py，结果写到 results/2026-10-10_qc/，并生成 RUN.md"

# 需要逐步事件（命令、文件改动、token 用量）时输出 JSONL
codex exec --json --sandbox workspace-write "..." > run_events.jsonl

# 接着上一次非交互会话继续（--last 只在当前目录范围内找）
codex exec resume --last "把 01_qc 的过滤阈值改成 min_counts=10 并重跑"

# 交互会话
codex resume              # 列表选择
codex resume --last       # 当前目录最近一次
codex resume --all        # 跨目录查找
codex fork --last         # 复制一份会话，尝试另一种做法

审批与沙箱

审批模式与沙箱：权限越大，出错的代价越大

沙箱决定命令在技术上能做什么（写哪些目录、能否联网），审批策略决定什么时候停下来问你。两者独立设置。CLI 和 IDE 插件的沙箱由操作系统实现：macOS 用 Seatbelt，Linux 和 WSL2 用 bubblewrap / Landlock，原生 Windows 用专门的沙箱用户。

workspace-write 下仍有几处只读：工作区内的 .git、.codex、.agents 目录（因此 git commit 需要审批），以及主目录下的 ~/.cache 等位置。本页用 codex sandbox 实测：在工作区内写文件成功，写 ~/.cache 与 git commit 均报 Operation not permitted，curl 外网报 Could not resolve host。Python 包把缓存写到 ~/.cache 时会因此失败，可在 AGENTS.md 中约定把 MPLCONFIGDIR、HF_HOME 等缓存目录设到项目内或 /tmp。

/undo 已经从 CLI 移除。维护者在 GitHub #9203 中说明原实现问题较多，要恢复需要重新设计；社区的替代做法是让 Codex 用补丁逆向撤销本轮改动，但被删除的未跟踪文件无法找回。开始一轮任务前提交一次 git，是目前最可靠的回退方式。

需要比 sandbox_mode 更细的控制时，可以用权限 profile（beta）：在 [permissions.<名称>] 中按路径设置 read、write、deny，并为网络设置域名白名单。下一节给出把原始数据设为只读的写法。

科研代码

用 Codex 写科研代码：保护原始数据、留下可复现记录、管理上下文

科研分析和普通软件开发的差别在于：原始数据不可再生，结果需要能追溯到具体命令和参数，任务时间长。下面按这三点给出做法。

# ~/.codex/config.toml：用权限 profile 把 data/raw 设为只读
# 这一段与 sandbox_mode / [sandbox_workspace_write] 二选一，两者同时存在时 profile 不生效
default_permissions = "research"

[permissions.research]
extends = ":workspace"              # 继承默认工作区权限（.git/.codex 只读、网络关闭）

[permissions.research.filesystem.":workspace_roots"]
"data/raw" = "read"                 # 相对每个工作区根目录
"**/*.env" = "deny"

# 本页实测（Codex CLI 0.162.1，macOS arm64，codex sandbox -P research）：
#   echo ok > results/out.txt         -> 成功
#   echo x >> data/raw/counts.csv     -> Operation not permitted
#   rm data/raw/counts.csv            -> Operation not permitted
# 对照：使用内置 :workspace 时，追加写入 data/raw/counts.csv 成功

1. 01

   第一层：操作系统层面把原始数据设为只读

   最简单的是 chmod -R a-w data/raw。只在 Codex 中生效的做法是权限 profile：继承 :workspace 后把 data/raw 设为 read（见下方代码）。这一段与 sandbox_mode 二选一，配置中任一层出现 sandbox_mode 或命令行传了 --sandbox，profile 就不生效。

2. 02

   第二层：AGENTS.md 写明目录约定

   说明哪些目录只读、生成文件放哪里、怎样算完成。智能体会按文件要求执行，但规则本身不能阻止写入，所以要和第一层一起用。

3. 03

   第三层：git 与运行目录

   原始数据不进 git 时，至少把脚本、配置和 RUN.md 纳入 git。每次运行写到新的 results/<日期>_<简述>/ 目录，不覆盖旧结果。

4. 04

   要求可复现记录

   在 AGENTS.md 中规定每次运行生成 RUN.md：命令、输入文件 md5、软件与包版本（conda env export 或 sessionInfo()）、随机种子、参数、耗时、输出文件列表。审阅时先看 RUN.md，再看结果。

5. 05

   环境先装好

   workspace-write 默认不联网，pip / conda 安装会失败。在开始任务前自己建好环境，或只在装包的那一轮打开 network_access，装完关闭。

6. 06

   上下文过长时

   用 /status 看剩余上下文；到达阈值后 Codex 会自动压缩（阈值可用 model_auto_compact_token_limit 调整），也可手动 /compact。GitHub #36642 报告 0.145 起自动压缩偶发丢失全部历史，0.150 仍有复现且 issue 未关闭。长任务中让 Codex 把进度、已确认的参数和待办写进 NOTES.md，压缩出问题或开新会话时让它先读这个文件。

排错

常见报错与解决

先看报错里的 URL 或路径：它说明请求实际发到了哪里、哪个文件被拒绝。然后运行 codex doctor，它会分别检查登录、WebSocket、代理变量和沙箱。

中文社区经验

中文社区经验：代理、实验室服务器与配置排查

以下经验来自含报错原文或作者实测记录的帖子，已与官方文档或 GitHub issue 交叉核对，写明适用条件。

交给 Agent

把这套流程交给 Agent

指令示例：“这是我的 RNA-seq 课题仓库，原始计数在 data/raw。请先阅读 AGENTS.md 和 scripts/，在不修改 data/raw 的前提下跑通 01_qc 到 03_deseq，每一步写 RUN.md，最后列出结果与上一次运行的差异和需要我核对的地方。”

智能体会执行的步骤：在以 Codex 为基座的隔离云电脑中读取仓库和 AGENTS.md；使用预装的 pandas、SciPy、statsmodels、scikit-learn 等环境，缺少的 R 或 Python 包在工作区内安装；按编号运行脚本并记录命令、版本和参数；对结果做对抗审阅；任务持续运行，关闭本机后不中断，空闲时暂停并保留现场。

产出文件：修改后的脚本、每次运行的 results 目录与 RUN.md、日志，以及一份说明改动和异常的记录。

你仍需自己核对：统计方法和阈值是否符合你的研究设计，样本分组与批次信息是否正确，以及结果中的生物学解释。