本页说明
教程- 这页解决什么
- 你的课题数据在本机或服务器上,想让 Codex 帮你读懂分析脚本、运行一步分析并记录结果。但它装好后启动失败,或者每次都不知道项目里的约定,动手前也不清楚怎样保护原始数据。
- 适合谁
- 第一次使用 Codex 的研究生或科研人员。你用过 ChatGPT 或命令行,但没有写过 config.toml 和 AGENTS.md。
- 读完你会得到
- 读完会得到:一个能启动的 Codex CLI、一份 ~/.codex/config.toml、项目根目录的 AGENTS.md,以及一次运行留下的 RUN.md 和结果目录。
- 覆盖
- 安装 Codex CLI,并用 ChatGPT 账号或 API Key 登录
- 写出一份能正常启动的 config.toml 和科研项目的 AGENTS.md
- 在项目里完成第一个任务,保护原始数据并留下运行记录
- 不覆盖
- 分子动力学、AlphaFold 等具体科研工具的用法,见对应教程
- IDE 插件、桌面 App、Codex Cloud 的操作细节,只在选择分区简要说明
- 国内网络方案的费用与风险比较,见《国内怎么用 Codex 和 Claude Code》
主线步骤
第 1 步
为什么做这一步CLI 是在终端里运行 Codex 的程序。后面的登录、配置和任务都在它上面完成,所以先装它。本页以 CLI 为主线;IDE 插件、桌面 App 和云端版本的选择见后文选择分区。
macOS 和 Linux 用官方安装脚本最省事,安装和升级用同一条命令。npm 与 Homebrew 同样可用,适合本来就用这两种工具管理软件的人。
装的时候如果遇到 Missing optional dependency,或者 npm 安装很慢,见排错:Missing optional dependency,以及排错:npm 安装耗时十几分钟。
# 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 # 安装、配置、登录、网络、沙箱逐项检查第 2 步
为什么做这一步Codex 要调用模型,必须知道你的账号或 API Key。登录一次后,凭据保存在本机,之后直接运行 codex 即可。
在终端运行 codex login,浏览器会打开 ChatGPT 登录页。登录信息缓存在 ~/.codex/auth.json 或系统钥匙串,由配置项 cli_auth_credentials_store 决定(可选 file、keyring、auto、ephemeral)。CLI 和 IDE 插件共用这份缓存,在任一处退出后两处都要重新登录。
想用 API Key 登录,或在没有浏览器的服务器上登录,见ChatGPT 账号还是 API Key,以及选择:无外网、无 root 的服务器。登录后仍然报 401,见排错:401 Unauthorized。
codex login # 浏览器登录 ChatGPT 账号
codex login status # 已登录返回 0,未登录打印 Not logged in 并返回 1
codex logout第 3 步
为什么做这一步config.toml 是 Codex 的默认设置文件,决定用哪个模型、什么时候让你确认、能在哪些目录里写文件。没写的项目使用内置默认值。第一次只需要设好下面四项,其余的见“config.toml 配置项与生效顺序”。
文件使用 TOML 格式:键 = 值,字符串要加双引号。新建 ~/.codex/config.toml,把下面的内容复制进去,再按注释修改。
启动时报 unknown configuration field 或 ignoring 提示,见排错:Codex is ignoring N unrecognized configuration settings。
# ~/.codex/config.toml
# 根级键必须写在第一个 [表] 之前,否则会被当成该表的字段而被忽略
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 = "project-write" # read-only / project-write / danger-full-access
[sandbox_workspace_write]
network_access = false # 需要 pip/conda 联网安装时改为 true第 4 步
为什么做这一步Codex 不知道你的课题有哪些约定,每次启动都要从头了解。AGENTS.md 是一个普通 Markdown 文件,Codex 在每次启动会话时读取并放进第一轮上下文。它用来写这个项目长期有效的规则:目录约定、运行命令、哪些文件不能动、什么算完成。
把文件放在课题仓库的根目录,也就是含 .git 的目录。在项目根目录运行 codex 后输入 /init,可以生成一份草稿,再删到只剩必要的规则。规则越具体越有用,例如“data/raw 只读”比“注意数据安全”更能让 Codex 照做。
检查 Codex 实际读到了哪些文件:在交互会话中问“列出你加载的指令文件”,或用 codex -c log_dir=./.codex-log 启动后查看 codex-tui.log。规则没生效,尤其是子目录里的规则,见排错:子目录里的 AGENTS.md 没有生效。
# 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 重新跑出同样的结果。
- 回复中列出改动的文件和需要我人工核对的地方。第 5 步
为什么做这一步前面的配置都为这一步服务:让 Codex 在项目里读、改、运行,同时保证原始数据不被改动,并且每次运行都能追溯。科研数据通常无法重新获得,所以先保护数据,再开始任务。
- 01
开始前保护原始数据
先把仓库当前状态提交到 git,再运行 chmod -R a-w data/raw,把原始数据设为只读。chmod 是操作系统层面的限制,不依赖 Codex 的规则。提交 git 的原因见“为什么先提交 git,而不依赖 /undo”。
- 02
在项目根目录启动
cd 到仓库根目录再运行 codex,它才会读到根目录的 AGENTS.md。第一次建议先给一个只读任务,例如“解释 scripts/ 里每个脚本的作用”,确认它读到了项目规则。
- 03
下达任务并要求记录
任务里写明输入、输出位置和需要的记录,例如“按 AGENTS.md 运行 scripts/01_qc.py,结果写到 results/<日期>_qc/,并生成 RUN.md”。RUN.md 记录命令、输入文件 md5、软件版本、随机种子、参数和输出列表。审阅时先看它,再看结果。
- 04
确认环境已经装好
project-write 默认不联网,pip 和 conda 安装会失败。在开始任务前自己建好环境;必须在任务中安装时,只在那一轮打开 network_access,装完关闭。
按你的情况选择
选择
四种形态调用的是同一个 Codex 智能体,差别在运行位置、能访问的文件和登录要求。CLI 和 IDE 插件读同一份 ~/.codex/config.toml 和同一份登录缓存,在一处登录后另一处直接可用。如果你不确定,就按本页主线使用 CLI。
数据只在本机或课题组服务器上时,选 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 | install.sh / PowerShell 脚本、npm、Homebrew | 本机终端;也可装在 SSH 登录的服务器上 | ChatGPT 账号或 API Key | 实验室服务器、脚本批量运行、需要精确控制权限 |
| IDE 插件 | VS Code / Cursor / Windsurf 扩展市场搜索 openai.chatgpt;JetBrains 在 AI Assistant 的 AI Chat 中选择 Codex | 本机或 Remote-SSH 连接的服务器 | ChatGPT 账号或 API Key | 边看代码边改,审阅改动 |
| ChatGPT 桌面 App | chatgpt.com/download(macOS、Windows),Linux 另有安装说明 | 本机;可选 Local、Worktree 或 Cloud | ChatGPT 账号或 API Key | 多个课题并行、要看图表和文件预览 |
| Codex Cloud | ChatGPT 网页、桌面 App 或手机中选择 Work in > Cloud | OpenAI 托管的云端容器,需要先创建环境并连接 GitHub 仓库 | 只能 ChatGPT 账号 | 代码在 GitHub 上、关机后仍要继续的任务 |
选择
两种方式在本机的 CLI、IDE 插件和桌面 App 中都可用。选择取决于你按套餐额度用还是按 token 付费,以及是否需要 Codex Cloud。
printenv OPENAI_API_KEY | codex login --with-api-key # 从环境变量 OPENAI_API_KEY 读取 Key| 比较项 | ChatGPT 账号登录 | API Key 登录 |
|---|---|---|
| 计费 | 使用 ChatGPT 套餐内的额度,用完可在 Plus、Pro 购买额外额度 | 按标准 API 价格从 OpenAI Platform 账户扣费 |
| 可用模型 | 取决于套餐,Plus 起包含 GPT-6.1 Sol 和 GPT-6 Luna | 取决于这把 Key 在 API 中可用的模型 |
| Codex Cloud、GitHub 代码审阅、Slack | 可用 | 不可用 |
| 适合 | 日常交互使用 | CI、定时脚本、套餐额度用完后的补充 |
| 自动化中的写法 | 在可信机器上维护 auth.json | 只给 Codex 这一条命令设置 CODEX_API_KEY,不设成整个任务的环境变量 |
选择
操作上需要稳定的国际网络,以及 ChatGPT 账号或 OpenAI API Key。下面是常用的代理和证书设置。
代理建议使用 HTTP 代理变量。SOCKS5 代理下 ChatGPT 连接断流更常见,见排错:stream disconnected before completion(chatgpt.com 地址)。macOS 上从程序坞启动的 ChatGPT 桌面 App 不读终端里的 export,需要用 launchctl setenv 单独设置,见排错:桌面 App 连不上。
官方订阅、API 中转站、国产模型三种路线的比较见 /compare/codex-claude-code-china。
# 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
# 公司代理或自签根证书
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"选择
服务器上没有浏览器时,可以改用设备码登录。服务器无外网时,需要借用本机的代理。
设备码登录需要先在 ChatGPT 的安全设置中开启(项目账号由管理员在项目权限中开启)。登录失败时查看日志目录下的 codex-login.log。
CSDN 作者在无外网、无 root 的实验室服务器上的做法:在本机 ~/.ssh/config 中为服务器加 RemoteForward 17891 127.0.0.1:7890,把本机代理映射到服务器;服务器上导出 HTTP(S)_PROXY 指向 127.0.0.1:17891;缺根证书时用 certifi 的 cacert.pem 设置 SSL_CERT_FILE;VS Code 扩展通过 ~/.vscode-server/server-env-setup 加载同一组变量,修改后执行 Remote-SSH: Kill VS Code Server on Host 再重连。作者建议先跑通 CLI 再配扩展。
登录最后一步失败,见排错:Token exchange failed。缺少根证书,见排错:no native root CA certificates found。
codex login --device-auth # 设备码登录:服务器、无浏览器环境
# 服务器无浏览器且设备码不可用:把回调端口转发到本机后再登录
ssh -L 1455:localhost:1455 user@server
codex login # 在本机浏览器打开终端打印的地址
# 或把本机的登录缓存复制过去(auth.json 等同密码)
ssh user@server 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json选择
沙箱决定命令在技术上能做什么,比如能写哪些目录、能否联网;审批策略决定什么时候停下来问你。两者独立设置,下表列出常见组合。日常使用推荐第二行。
需要比 sandbox_mode 更细的控制时,可以用权限 profile(beta),见用权限 profile 让 data/raw 只读。沙箱为什么有些目录仍然只读,见“沙箱的实现与只读目录”。
| 组合 | 能做什么 | 实际后果 |
|---|---|---|
| read-only + on-request | 读文件、运行只读命令;写入和联网需要你批准 | 适合第一次打开别人的代码或只做讲解;每次改动都要点批准 |
| project-write + on-request(默认的 Auto) | 在工作目录、/tmp、$TMPDIR 内读写和运行命令;目录外写入和联网需要批准 | 日常推荐。工作目录内的文件包括原始数据都可能被改动或删除 |
| project-write + never | 同上,越界操作直接失败 | codex exec 的常见设置。越界失败后模型可能改用其他做法绕开 |
| project-write + approvals_reviewer = "auto_review" | 越界请求先交给审查智能体判断 | 减少打断;审查会额外消耗额度,审查拒绝后可用 /approve 放行一次 |
| danger-full-access 或 --yolo(--dangerously-bypass-approvals-and-sandbox) | 无沙箱、无审批,可读写整台机器并联网 | 官方只建议在已隔离的容器或虚拟机中使用。误删的未跟踪文件无法通过 Codex 恢复 |
选择
默认情况下 Codex 只连接 OpenAI,下面三类设置只在需要时添加。
接文献库、数据库、浏览器等外部工具时添加 MCP 服务器。每个 MCP 服务器都会占用上下文和额度,不用时设 enabled = false。也可以用命令添加:codex mcp add <名称> -- <命令>,或 codex mcp add <名称> --url <地址>,两者都会写入 config.toml;codex mcp list 查看已配置的服务器及启用状态。
接自定义网关时,网关必须支持 Responses 协议,并写 wire_api = "responses"。只提供 Chat Completions 接口的服务无法接入当前版本,需要换一个支持 Responses 的网关。Codex 按 OpenAI 模型调优,换模型后效果可能下降。
项目内 .codex/config.toml 只在信任该项目后生效,且不能设置 model_provider、model_providers、openai_base_url、profile 等键。
# 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"选择
同一台机器上常见三种用法:日常使用、高推理强度、通过网关使用。每一种写成一个独立文件,用 -p 切换。
0.134.0 起每个 profile 是一个独立文件,文件中写顶层键,不再使用 [profiles.<名称>] 表。旧写法见排错:legacy profile 配置。
# ~/.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 的统计方法"选择
chmod 是操作系统层面的限制,对所有程序都有效。如果你希望只在 Codex 内部限制某些路径,可以用权限 profile。它与 sandbox_mode 二选一。
这一段与 sandbox_mode 二选一:配置中任一层出现 sandbox_mode,或命令行传了 --sandbox,profile 就不生效。需要比 sandbox_mode 更细的控制(按路径设置 read、write、deny,并为网络设置域名白名单)时,才使用权限 profile(beta)。
# ~/.codex/config.toml:用权限 profile 把 data/raw 设为只读
# 这一段与 sandbox_mode / [sandbox_workspace_write] 二选一,两者同时存在时 profile 不生效
default_permissions = "research"
[permissions.research]
extends = ":project" # 继承默认项目权限(.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
# 对照:使用内置 :project 时,追加写入 data/raw/counts.csv 成功选择
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 project-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 project-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 # 复制一份会话,尝试另一种做法| 默认行为 | 处理 |
|---|---|
| 没有配置文件时沙箱为 read-only | 加 --sandbox project-write,或在 config.toml 设 sandbox_mode |
| 审批策略固定为 never | 把所需权限事先写进配置(可写目录、网络) |
| 要求在 git 仓库或已信任目录中运行 | 在数据分析目录 git init,或加 --skip-git-repo-check |
选择
上下文是模型一次能看到的全部内容。任务越长,越需要主动管理。
用 /status 看剩余上下文。到达阈值后 Codex 会自动压缩(阈值可用 model_auto_compact_token_limit 调整),也可以手动输入 /compact。
长任务中,让 Codex 把进度、已确认的参数和待办写进 NOTES.md。压缩出问题或开新会话时,让它先读这个文件。压缩后历史丢失的情况见排错:压缩后忘记前面的参数和进度。
交给 Agent
指令示例:“这是我的 RNA-seq 课题仓库,原始计数在 data/raw。请先阅读 AGENTS.md 和 scripts/,在不修改 data/raw 的前提下跑通 01_qc 到 03_deseq,每一步写 RUN.md,最后列出结果与上一次运行的差异和需要我核对的地方。”
智能体会执行的步骤:在隔离云电脑中读取仓库和 AGENTS.md;使用预装的 pandas、SciPy、statsmodels、scikit-learn 等环境,缺少的 R 或 Python 包在项目内安装;按编号运行脚本并记录命令、版本和参数;对结果做对抗审阅;任务持续运行,关闭本机后不中断,空闲时暂停并保留现场。
产出文件:修改后的脚本、每次运行的 results 目录与 RUN.md、日志,以及一份说明改动和异常的记录。
你仍需自己核对:统计方法和阈值是否符合你的研究设计,样本分组与批次信息是否正确,以及结果中的生物学解释。
原理与判断
原理
ETH Zürich 对 AGENTS.md 的评测(arXiv 2602.11988,ICLR 2026)发现,在 SWE-bench 等代码任务中,上下文文件总体略微降低任务成功率,推理成本增加 20% 以上。智能体会认真执行文件中的要求,多余的要求让任务更难。作者建议人工编写、只写最少的必要要求。官方计费文档也把“缩小 AGENTS.md”列为节省额度的方法。
所以规则只写本项目长期有效、必须遵守的内容。只有某个子目录用到的规则,放在子目录的 AGENTS.md 中,并在该子目录启动 Codex。
原理
/undo 已经从 CLI 移除。维护者在 GitHub #9203 中说明,原实现问题较多,要恢复需要重新设计。社区的替代做法是让 Codex 用补丁逆向撤销本轮改动,但被删除的未跟踪文件无法找回。
因此,开始一轮任务前提交一次 git,是目前最可靠的回退方式。Codex 改坏的已跟踪文件可以用 git 恢复,原始数据不在 git 中时,仍然需要靠 chmod 保护。
原理
CLI 和 IDE 插件的沙箱由操作系统实现:macOS 用 Seatbelt,Linux 和 WSL2 用 bubblewrap / Landlock,原生 Windows 用专门的沙箱用户。
在 project-write 模式下,仍有几处保持只读:项目内的 .git、.codex、.agents 目录,因此 git commit 需要审批;以及主目录下的 ~/.cache 等位置。本页用 codex sandbox 实测:在项目内写文件成功,写 ~/.cache 与 git commit 均报 Operation not permitted,curl 外网报 Could not resolve host。
参考与附录
参考
配置按以下顺序生效,排在前面的覆盖后面的:命令行参数与 -c 覆盖 → 项目内 .codex/config.toml(从项目根到当前目录,越近越优先,只对信任的项目生效)→ --profile 选择的 ~/.codex/<名称>.config.toml → ~/.codex/config.toml → 系统 /etc/codex/config.toml → 内置默认值。
# 根级键
web_search = "cached" # cached(默认)/ live / indexed / disabled
file_opener = "vscode" # 输出里的文件路径可点击打开
project_doc_max_bytes = 65536 # AGENTS.md 合计上限,默认 32768
[sandbox_workspace_write]
writable_roots = ["/Users/me/scratch"] # 额外可写目录,按实际路径修改
[history]
persistence = "save-all" # "none" 不在本机保存会话记录| 配置项 | 可选值与默认值 | 什么时候改 |
|---|---|---|
| model | 账号可用的模型 ID,例如 gpt-6.1-sol、gpt-6-luna;未设置时 0.162.1 默认 gpt-6.1-sol | 账号无权限或要省额度时改为 gpt-6-luna。GPT-5.5 将于 2026-10-14 在 ChatGPT 登录的 Codex 中下线,写死 gpt-5.5 的配置需要更换 |
| model_reasoning_effort | low / medium / high / xhigh 等,可用档位取决于模型 | 统计方法推导、复杂调试用 high;批量改格式用 low。档位越高耗时和用量越大 |
| approval_policy | on-request、never,或 { granular = {...} } | 交互使用 on-request;codex exec 自动使用 never |
| sandbox_mode | read-only / project-write / danger-full-access | 只看代码用 read-only;跑分析、改脚本用 project-write |
| [sandbox_workspace_write] | network_access 默认 false;writable_roots 额外可写目录 | 需要联网装包时开 network_access;结果要写到项目外的目录时加 writable_roots |
| model_provider + [model_providers.<id>] | base_url、env_key(环境变量名)、wire_api(只能 responses)、http_headers、request_max_retries、stream_idle_timeout_ms 等 | 接公司网关、Azure、Bedrock 或本地 Ollama 时。只改地址用顶层 openai_base_url |
| --profile 与 <名称>.config.toml | 0.134.0 起每个 profile 是一个独立文件,写顶层键 | 在“日常”“高推理”“走网关”之间切换 |
| [mcp_servers.<id>] | stdio:command、args、env;HTTP:url、bearer_token_env_var;通用:startup_timeout_sec(默认 10)、tool_timeout_sec(默认 60)、enabled、required、enabled_tools / disabled_tools | 接文献库、数据库、浏览器等外部工具。每个 MCP 服务器都会占用上下文和额度,不用时设 enabled = false |
| project_doc_max_bytes | 默认 32768 字节 | AGENTS.md 总量超过 32 KiB 时调大,更好的做法是拆到子目录 |
| [projects."<路径>"] trust_level | trusted / untrusted | 让项目内 .codex/config.toml 生效,或对某个项目强制每条命令审批 |
- 改完配置运行 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 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)时才生效;需要始终生效的规则写在根目录,根目录文件保持精简。
- 01
全局层
~/.codex/AGENTS.override.md 存在时只读它,否则读 ~/.codex/AGENTS.md。适合写跨项目的个人习惯,例如回复语言、常用包管理器。
- 02
项目层
从项目根(默认是含 .git 的目录,可用 project_root_markers 修改)一路走到你启动 Codex 的当前目录,每个目录依次找 AGENTS.override.md、AGENTS.md、project_doc_fallback_filenames 中的文件,每个目录最多取一个。
- 03
合并
按“全局 → 根目录 → 当前目录”的顺序拼接,离当前目录越近的越靠后,冲突时以后出现的为准。空文件跳过。
- 04
上限
合计超过 project_doc_max_bytes(默认 32 KiB)时截断,路径上更深的文件会被整份丢掉。
参考
下表按 codex --help 与官方 Developer commands 文档整理,只列日常会用到的部分。
切换模型与回复风格
/model 切换模型与推理档位,/fast 切换 Fast 档,/personality 设置回复风格。
/permissions
在会话中切换 Auto(项目可写)与 Read Only,查看当前沙箱和可写目录。
查看状态与配置来源
/status 查看当前模型、审批策略、可写目录和上下文余量;/debug-config 查看配置分层来源。
管理上下文与会话
/compact 压缩历史释放上下文;/new 在同一终端开新会话;/clear 清屏并开新会话。
查看与审阅改动
/diff 查看包括未跟踪文件在内的 git diff;/review 让 Codex 审阅当前改动。
规划长任务
/plan 先出执行计划再动手;/goal 给长任务设置持续跟踪的目标。
准备项目上下文
/init 生成 AGENTS.md 草稿;/mention 把指定文件加入对话;/mcp 列出可用的 MCP 工具。
恢复与整理历史会话
/resume 恢复历史会话,/fork 复制当前会话,/rename 给会话改名便于之后查找。
管理后台终端
/ps 查看后台终端的输出,长时间运行的分析脚本可在这里查看;/stop 停止所有后台终端。
快捷键
@ 搜索文件并插入路径;行首 ! 直接运行 shell 命令;运行中按 Enter 插入新指令、按 Tab 排队到下一轮;输入框为空时连按两次 Esc 编辑上一条消息并从该处分叉;Ctrl+R 搜索历史提示词;Ctrl+O 复制最近一次输出。
| 命令 | 作用 | 常用参数 |
|---|---|---|
| codex [提示词] | 在当前目录开启交互会话 | -m 模型、-s 沙箱、-a 审批、-C 工作目录、--add-dir 额外可写目录、-i 附图、--search 实时联网搜索、-p profile |
| codex exec(别名 e) | 非交互运行,适合脚本 | -o 写出最终回复、--json、--output-schema、--ephemeral、--skip-git-repo-check、--ignore-user-config |
| codex resume / codex fork | 恢复或复制历史会话 | --last、--all、会话 ID 或名称 |
| codex review | 对未提交改动、某个提交或分支做代码审阅 | 也可在会话中用 /review |
| codex apply(别名 a) | 把 Codex Cloud 任务的 diff 用 git apply 应用到本地 | |
| codex mcp add / list / get / remove / login | 管理 MCP 服务器 | --url、--bearer-token-env-var、--env |
| codex login / logout | 登录与退出 | --device-auth、--with-api-key、status |
| codex doctor | 检查安装、配置、登录、网络、沙箱 | --summary、--all、--json |
| codex sandbox | 在 Codex 的沙箱里运行任意命令,用来测试权限设置 | -P 权限 profile、-C 目录 |
| codex features list / enable / disable | 查看和切换功能开关 | |
| codex completion | 生成 bash / zsh / fish 补全脚本 |
参考
平台包很大:0.162.1 的 darwin-arm64 包压缩后 136.6 MB,解压后 323 MB。
本页实测:2026-10-11 在 macOS arm64、Node 24.19、npm 11.17 上执行 npm install @openai/codex@0.162.1,耗时 16 分 55 秒后返回成功,但平台包未下载,运行时出现 Missing optional dependency 的报错;手动下载平台包后正常。npmmirror 已同步 0.162.1 各平台包(核对了元数据)。
排错
先看报错里的 URL 或路径:它说明请求实际发到了哪里、哪个文件被拒绝。然后运行 codex doctor,它会分别检查登录、WebSocket、代理变量和沙箱。下面的条目按出现频率排列。标注“旧写法”的条目是旧教程中照抄会出错的写法;标注“经验帖”的内容来自中文社区的实操记录,已与官方文档或 GitHub issue 交叉核对。
stream disconnected before completion: error sending request for url (http://127.0.0.1:端口/v1/responses)
原因:config.toml 残留了 model_provider,指向一个已经没有运行的本地代理。只把 model 改回官方模型不够,请求仍会走旧 provider。
怎么解决:删除 model_provider 行和对应的 [model_providers.x] 表,然后运行 codex logout、codex login。经验帖:CSDN 作者(0.142.0,Windows)按此处理后恢复;之后若报 token_exchange_failed,更换代理节点。
stream disconnected before completion: error sending request for url (https://chatgpt.com/backend-api/codex/responses)
原因:网络或代理中断了长连接,SOCKS5 代理变量下更常见。
怎么解决:改用 HTTP 代理变量并设置 NO_PROXY。codex doctor 中 websocket 失败时,Codex 会尝试 HTTPS 回退。GitHub #20844 中,Windows 用户把 SOCKS5 改为 HTTP 代理后断流消失。
Operation not permitted(写文件或 git commit 时)
原因:目标在沙箱可写范围之外,或在 .git、.codex 等受保护路径中(见“沙箱的实现与只读目录”)。Python 包把缓存写到 ~/.cache 时也会因此失败。
怎么解决:用 --add-dir 增加可写目录,或在会话中批准越界操作。缓存目录可以在 AGENTS.md 中约定设到项目内或 /tmp,例如 MPLCONFIGDIR、HF_HOME。
Could not resolve host(pip、curl、git clone)
原因:project-write 默认关闭网络。
怎么解决:设置 sandbox_workspace_write.network_access = true,或批准该次联网。装完包后改回 false。
运行 codex 报 Missing optional dependency @openai/codex-darwin-arm64(或 linux-x64 等)
原因:npm 包本身只有一个启动脚本,真正的程序在按平台拆分的可选依赖里。可选依赖下载失败时,npm 只记一条 reify failed optional dependency,仍然返回成功。
怎么解决:重新安装;网络不稳定时加 --registry=https://registry.npmmirror.com,或改用官方安装脚本或 Homebrew。
npm install -g @openai/codex --registry=https://registry.npmmirror.comCodex is ignoring N unrecognized configuration settings
原因:字段拼错、已废弃或层级放错。拼错的字段会被静默忽略,例如 model_reasoning_efort。
怎么解决:codex doctor --all 的 config 一项会列出被忽略的字段,按提示的字段路径修改。用 codex exec --strict-config 可以让它直接报错。
Not inside a trusted directory and --skip-git-repo-check was not specified.
原因:codex exec 要求在 git 仓库或已信任的目录中运行。
怎么解决:在数据分析目录执行 git init,或加 --skip-git-repo-check。
codex exec 跑完后,分析脚本没有写出结果文件
原因:没有配置文件时,非交互 exec 的沙箱为 read-only。
怎么解决:加 --sandbox project-write,或在 config.toml 中设 sandbox_mode。
codex exec 中需要审批的命令直接失败,没有停下来等你
原因:exec 的审批策略固定为 never。需要审批的操作会直接失败,并把错误返回给模型。
怎么解决:把所需权限事先写进配置,例如可写目录和网络。
子目录里的 AGENTS.md 没有生效
原因:Codex 只读取从项目根到启动目录这条路径上的 AGENTS.md。在根目录启动时,子目录里的文件不会加载。合计超过 32 KiB 时,路径上较深的文件会被整份丢掉。
怎么解决:到该子目录启动(codex -C 子目录),或把规则写进根目录的文件。检查合计大小是否超过 project_doc_max_bytes。
压缩后忘记前面的参数和进度
原因:GitHub #36642 报告 0.145 起自动压缩偶发丢失全部历史,0.150 仍有复现,issue 未关闭。
怎么解决:压缩前让 Codex 把进度、已确认的参数和待办写入 NOTES.md。出问题时开新会话,让它先读 NOTES.md。用 /status 查看剩余上下文。
npm 安装耗时十几分钟
原因:平台包很大:0.162.1 的 darwin-arm64 包压缩后 136.6 MB,解压后 323 MB。
怎么解决:使用镜像源(--registry=https://registry.npmmirror.com),或使用官方安装脚本。
Token exchange failed: error sending request for url (https://auth.openai.com/oauth/token)
原因:登录最后一步访问 auth.openai.com 失败。
怎么解决:检查代理是否覆盖该域名。在服务器上改用 codex login --device-auth。
从程序坞打开的 ChatGPT 桌面 App 连不上,终端里的 codex 却正常
原因:在 .zshrc 中 export 的代理只对终端里启动的 codex 生效。从程序坞启动的 GUI 程序不读 shell 变量。
怎么解决:用 launchctl setenv 设置代理后重启 App。经验帖:CSDN 作者按此处理。GitHub #20844 中 Windows 用户也是把系统代理和环境变量都设成 HTTP 代理后才稳定。
launchctl setenv HTTPS_PROXY http://127.0.0.1:7890
launchctl setenv HTTP_PROXY http://127.0.0.1:7890WSL 中 0.129.0 以后每个请求都 stream disconnected
原因:GitHub #24511 报告的 WSL 网络回归,0.128.0 正常,issue 未关闭。
怎么解决:社区做法:NodeSeek 用户启用 WSL mirrored 网络模式(networkingMode=mirrored、dnsTunneling=true)后解决;GitHub #24511 的报告者在 Enterprise 账号下回退到 0.128.0 后恢复。两者的共同点是先在 WSL 内单独运行 codex doctor,确认 WSL 与 Windows 使用的代理变量和配置不同。
no native root CA certificates found
原因:服务器缺少系统根证书。
怎么解决:设置 CODEX_CA_CERTIFICATE 或 SSL_CERT_FILE 指向一个 PEM 文件,可以使用 Python certifi 自带的证书。
export CODEX_CA_CERTIFICATE=/path/to/root-ca.pemSkipped loading 1 skill(s) due to invalid SKILL.md files ... missing YAML frontmatter
原因:本地 skill 文件缺少 --- 包围的 name 和 description。
怎么解决:在文件开头补上 YAML 头。
WSL1 中无法运行沙箱命令
原因:0.115 起 Linux 沙箱改用 bubblewrap,WSL1 只支持到 0.114。
怎么解决:运行 wsl --set-version <发行版> 2,升级到 WSL2。
Windows 10 上终端显示异常或无法启动
原因:Codex 需要 ConPTY。官方要求 Windows 10 1809 及以上,Windows 11 为推荐环境。
怎么解决:更新系统,或在 WSL2 中运行。
codex update 提示无法自更新
原因:codex update 只对支持自更新的安装方式生效。
怎么解决:用安装时的同一种方式升级:npm 重装、brew upgrade,或重新运行安装脚本。
Windows 沙箱命令报错误 1385
原因:系统策略拒绝沙箱用户所需的登录类型。
怎么解决:请 IT 授予登录权限;临时把 [windows] sandbox 设为 unelevated。
启动失败:approval_policy = "untrusted" is no longer supported; remove this setting
原因:旧写法。旧教程中的 approval_policy = "untrusted" 在当前版本已移除。
怎么解决:删除该行,改用 on-request。需要每条命令都审批时,在 [projects."<路径>"] 中设 trust_level = "untrusted"。
invalid value ... [possible values: on-request, never]
原因:旧写法。旧教程中的 codex -a untrusted 或 -a on-failure 在当前版本不再接受。
怎么解决:改为 codex -a on-request。
legacy `profile = "fast"` config is no longer supported; use `--profile fast` with `fast.config.toml` instead
原因:旧写法。旧教程在 config.toml 中写 profile = "fast",并加 [profiles.fast] 表。
怎么解决:把 [profiles.fast] 下的键移到 ~/.codex/fast.config.toml(写成顶层键),然后删除原表和 profile 行。
--profile `fast` cannot be used while ... config.toml contains legacy ... config
原因:旧写法。config.toml 中仍有旧的 [profiles.fast] 表,与 --profile 冲突。
怎么解决:同上:把表中的键移到 fast.config.toml,并删除 config.toml 中的旧表。
`wire_api = "chat"` is no longer supported. How to fix: set `wire_api = "responses"`
原因:旧写法。旧教程使用的 Chat Completions 协议在当前版本已不再支持。
怎么解决:改为 wire_api = "responses"。上游只支持 Chat Completions 时,需要换成支持 Responses 的网关。
model_providers contains reserved built-in provider IDs: `openai`
原因:旧写法。旧教程在 [model_providers.openai] 中修改 base_url,但 openai 是内置 ID,不能覆盖。
怎么解决:删掉该表,改用顶层 openai_base_url,或换一个自定义 ID。
error: unexpected argument '--full-auto' found
原因:旧写法。官方文档仍写“打印弃用警告”,但 0.162.1 已直接报错。
怎么解决:改为 codex exec --sandbox project-write。
string values must be quoted
原因:写成了 model = gpt-6.1-sol,字符串没有加引号。
怎么解决:给字符串加双引号,写成 model = "gpt-6.1-sol"。
too few unicode value digits(\U 被当作转义)
原因:双引号字符串中的反斜杠会被当作转义,例如 C:\Users 中的 \U。
怎么解决:改用单引号字面量 'C:\Users\me\data',或正斜杠 C:/Users/me/data。
模型设置无效,不报错;--strict-config 下报 unknown configuration field `sandbox_workspace_write.model`
原因:根级键写在了 [sandbox_workspace_write] 等表之后,因此被当成该表的字段。
怎么解决:把所有根级键移到第一个 [表] 之前。
字段被忽略,不报错;codex doctor 中显示 `mcp_servers.x.type` is ignored
原因:字段名拼错,例如 model_reasoning_efort;或从 Claude Code 迁移 MCP 配置时照搬了 type = "stdio"。Codex 根据 command 或 url 判断类型,不使用 type。
怎么解决:删掉 type,或改正拼写。经验帖:CSDN 文章记录的 mcp_servers.node_repl.type is ignored 警告与此相同。
参考资料
- Codex CLI 文档 — 四种安装方式与升级命令
- Codex IDE extension 文档 — VS Code、Cursor、Windsurf、JetBrains、Xcode 的入口
- Codex Cloud 与 Codex environments 文档 — Local、Worktree、Cloud 的区别,云端任务不带本机文件
- Authentication 文档 — 两种登录方式、设备码、1455 端口转发、CODEX_CA_CERTIFICATE、凭据存储
- Pricing 文档 — 各套餐可用的形态与模型,API Key 不含云端功能
- Models 文档 — 当前推荐模型与 GPT-5.5 退役日期
- Config basics / Advanced Configuration / Configuration Reference — 配置优先级、profile 文件、自定义 provider、MCP 字段、项目配置不能设置的键
- Custom instructions with AGENTS.md — AGENTS.md 发现顺序、override、32 KiB 上限
- Agent approvals & security — 沙箱与审批组合、受保护路径、untrusted 的迁移方法
- Permissions(beta) — 权限 profile 写法,与 sandbox_mode 不能混用
- Non-interactive mode — codex exec 的默认权限、输出、git 检查、CODEX_API_KEY
- Developer commands(CLI 参考与斜杠命令) — 子命令、斜杠命令、快捷键
- ChatGPT desktop app for Windows / Windows sandbox — WSL1 自 0.115 不再支持、Windows 版本要求、错误 1385
- Gloaguen et al. Evaluating AGENTS.md (arXiv 2602.11988, ICLR 2026) — 上下文文件对成功率与成本的影响
- GitHub openai/codex #9203:Please make /undo back — 维护者说明 /undo 移除原因;社区撤销做法
- GitHub openai/codex #36642:Auto-compaction silently discards history — 0.145 起自动压缩丢失历史的报告与自查命令
- GitHub openai/codex #20844:SOCKS5 proxy instability — 经验帖:SOCKS5 改 HTTP 代理后恢复
- GitHub openai/codex #24511:0.129.0+ fails in WSL — WSL 断流回归报告
- CSDN:本地 Codex 报错 stream disconnected before completion 的排查与修复记录 — 经验帖,作者实测(0.142.0,Windows):本地代理残留与 token_exchange_failed
- CSDN:远程服务器配置 Codex CLI 与 VSCode Codex 扩展流程 — 经验帖,作者实测:无外网服务器的 SSH 反向代理与证书
- CSDN:Mac 配置 Codex App 代理完整指南 — 经验帖:launchctl setenv 设置 GUI 程序代理
- CSDN:Codex 401 报错与配置不生效排查 — 经验帖:未识别字段警告原文;文中关于环境变量优先级的说法与官方文档不符,未采纳