Codex 排错完整教程：安装 · 登录 · 沙盒 · 配置 · 网络 15 类常见问题速查

写在前面

发布日期：2026-06-02 ｜ 适用版本：Codex v0.135.0（openai/codex）

Codex（OpenAI Codex CLI） 是以 Rust 编写的本地 AI 编程代理，配置体系和认证逻辑与 Claude Code 完全不同：

• 用户配置存放在 ~/.codex/config.toml
• 凭据缓存在 ~/.codex/auth.json
• 项目指令写在 AGENTS.md
• 沙盒通过 --sandbox 和 --ask-for-approval 两个参数控制

本文按问题类型分层整理 Codex 的常见报错和解决方法，所有命令和配置均来自 Codex 官方文档（developers.openai.com/codex，2026）。遇到未知问题时，优先用 codex --debug "问题描述" 开启调试日志，再按本文索引定位。

---

快速诊断索引

症状	跳转章节
command not found: codex / PATH 问题	§1 安装与 PATH
登录弹窗打不开、无浏览器环境、headless	§2 认证与登录
Codex 拒绝执行命令、一直要求审批	§3 沙盒与权限
配置写了但不生效	§4 配置文件问题
网络请求被 Codex 拒绝	§5 网络访问问题
上下文超限、会话卡死	§6 上下文与性能
Windows 特有问题	§7 平台差异

---

1. 安装与 PATH 问题

command not found: codex

安装成功但执行 codex 报找不到命令，说明安装目录未加入 PATH。

安装路径：

• macOS / Linux：~/.local/bin/codex
• Windows：%USERPROFILE%\.local\bin\codex.exe

# 检查是否在 PATH 中
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

# Zsh（macOS 默认）修复
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# Bash（Linux 默认）修复
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# 验证
codex --version

Windows PowerShell：

$p = [Environment]::GetEnvironmentVariable('PATH','User')
[Environment]::SetEnvironmentVariable('PATH', "$p;$env:USERPROFILE\.local\bin", 'User')
# 重启终端后验证
codex --version

Shell 补全报 command not found: compdef（Zsh）

# 在 ~/.zshrc 中，确保 compinit 在 eval 行之前
autoload -Uz compinit && compinit
eval "$(codex completion zsh)"

安装被 Killed（Linux 低内存服务器）

Codex 安装至少需要 4 GB 可用 RAM，内存不足时 OOM killer 会终止进程。

# 临时增加 swap
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile

# 重新安装
curl -fsSL https://chatgpt.com/codex/install.sh | sh

安装脚本返回 HTML 或 403

使用替代安装方式：

# macOS
brew install --cask codex

# Windows
winget install OpenAI.Codex

企业网络需要配置代理：

export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://chatgpt.com/codex/install.sh | sh

---

2. 认证与登录问题

Codex 支持的两种认证方式

方式	适用场景	命令
ChatGPT 订阅登录	日常使用（Plus/Pro/Business/Edu/Enterprise）	codex login
OpenAI API Key	CI/CD、程序化调用	printenv OPENAI_API_KEY | codex login --with-api-key

📌 注意：Codex Cloud（chatgpt.com/codex）只支持 ChatGPT 登录；API Key 可用 Fast mode 之外的所有功能。

浏览器打不开 / 无界面的 headless 环境

# 方法一：设备码登录（推荐，Beta）
codex login --device-auth
# 按提示在另一台有浏览器的机器上打开链接并输入验证码

# 方法二：从有浏览器的机器复制凭据
# 在有浏览器的机器上登录，然后复制 auth.json
ssh user@remote 'mkdir -p ~/.codex'
scp ~/.codex/auth.json user@remote:~/.codex/auth.json

# Docker 容器
CONTAINER_HOME=$(docker exec MY_CONTAINER printenv HOME)
docker exec MY_CONTAINER mkdir -p "$CONTAINER_HOME/.codex"
docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"

⚠️ ~/.codex/auth.json 包含访问令牌，等同密码——不要提交到 Git、不要粘贴到 Issue。

企业内网 TLS 证书错误

# 设置企业 CA 证书（登录和所有 HTTPS 请求均生效）
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

如果 CODEX_CA_CERTIFICATE 未设置，Codex 会回落到 SSL_CERT_FILE。

登录 token 过期或被撤销

codex logout
codex login

Codex 会在活跃会话中自动刷新 token，但网络中断或会话长时间暂停可能导致刷新失败。

凭据缓存位置配置

# ~/.codex/config.toml
# file | keyring | auto
cli_auth_credentials_store = "keyring"

• file：保存在 ~/.codex/auth.json（默认）
• keyring：保存在操作系统凭据管理器
• auto：有 keyring 用 keyring，否则用文件

企业管理员强制认证方式

# 仅允许 ChatGPT 登录或仅允许 API Key
forced_login_method = "chatgpt"  # 或 "api"

# 限定到指定企业 workspace
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

如果当前凭据不符合管理策略，Codex 会强制登出并退出。

---

3. 沙盒与权限问题

Codex 默认运行在 workspace-write 沙盒中，这是 “Auto” 预设（可读写当前工作目录，出界操作或网络访问需审批）。

沙盒三档速查

沙盒模式	参数	行为
工作区写入（默认）	--sandbox workspace-write	读写当前目录，出界需审批
只读	--sandbox read-only	只看文件，不改不执行
完全访问	--sandbox danger-full-access	无限制（仅用于隔离环境）

批准模式（--ask-for-approval / -a）

策略	参数值	行为
不确定时问	on-request（默认）	可疑操作暂停确认
只问不信任命令	untrusted	已知安全操作自动执行
从不询问	never	全自动（CI 场景）

常见组合

# 日常使用（默认 Auto 预设）
codex --sandbox workspace-write --ask-for-approval on-request

# CI 只读不交互
codex exec --sandbox read-only --ask-for-approval never

# 危险：完全跳过沙盒（仅隔离环境）
codex --dangerously-bypass-approvals-and-sandbox
# 或简写
codex --yolo

Codex 一直要求审批不肯自动执行

原因：当前 approval_policy 是 untrusted，Codex 对未知命令要求确认。

修复：改为 on-request 或在 config.toml 中持久化设置：

# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Codex 拒绝修改某个路径

workspace-write 模式默认保护 .git/ 和 .codex/ 目录，即使在工作区内也不能修改。这是设计行为，不是 bug。

调试沙盒是否允许某个命令

# 在当前沙盒设置下测试指定命令是否能执行
codex sandbox macos -- ls /etc
codex sandbox linux -- curl https://example.com
codex sandbox windows -- dir C:\

加 --log-denials（macOS）可以用系统日志捕获被拒绝的操作：

codex sandbox macos --log-denials -- your-command

使用 Auto-review 自动审批

如果不想每次手动确认，可以开启 AI 自动审批（需要 Codex 2.x 以上）：

approval_policy = "on-request"
approvals_reviewer = "auto_review"

Auto-review 会对每个需要审批的操作进行风险评估：低/中风险自动放行，高风险需要用户授权，关键风险直接拒绝。

---

4. 配置文件问题

Codex 配置的正确位置

Codex 使用 TOML 格式，不是 JSON，不是 ~/.claude/settings.json。

层级	路径	说明
系统级	/etc/codex/config.toml	管理员部署
用户级	~/.codex/config.toml	个人默认设置
Profile	~/.codex/<名称>.config.toml	多套配置切换（--profile <名称>）
项目级	.codex/config.toml	仓库根目录（需信任项目才加载）

优先级（从高到低）：

CLI 参数 > 项目 .codex/ > profile 文件 > 用户 ~/.codex/config.toml > 系统 > 内置默认

配置写了但 Codex 不理会

常见原因一：项目被标记为不可信

项目级 .codex/config.toml 只在可信项目中加载。不可信项目只加载用户级和系统级配置。

确认或修改项目信任状态：在 Codex 会话中使用 /permissions 切换，或通过 Desktop 的设置界面。

常见原因二：CLI 参数或 profile 文件覆盖了 config.toml

# 一次性覆盖（优先级最高）
codex -c approval_policy=never "your task"

# 使用特定 profile（覆盖用户级 config）
codex --profile ci "your task"

AGENTS.md 不生效

Codex 读取 AGENTS.md（不是 CLAUDE.md）。文件应放在项目根目录：

# 检查 AGENTS.md 是否存在于当前工作目录
ls AGENTS.md

# 如果同时有 CLAUDE.md，可以互相导入
# AGENTS.md 可以 @import CLAUDE.md（具体语法见 Codex 文档）

开启 debug 日志定位配置问题

# 全局 debug 模式
codex --debug "描述问题"

# 指定日志目录（也会生成 codex-tui.log）
codex -c log_dir=./.codex-debug-log "your task"

登录相关问题会写入 codex-login.log（在配置的日志目录下）。

---

5. 网络访问问题

默认行为：网络是关闭的

workspace-write（默认沙盒）下，Codex 生成的命令没有网络访问权限。如果你的代码需要访问网络（如 npm install、curl），需要显式开启。

开启命令的网络访问

# ~/.codex/config.toml 或 .codex/config.toml
[sandbox_workspace_write]
network_access = true

或临时一次性开启：

codex -c 'sandbox_workspace_write.network_access=true' "run npm install"

精细控制：只允许特定域名

[features.network_proxy]
enabled = true

[features.network_proxy.domains]
"api.openai.com" = "allow"
"registry.npmjs.org" = "allow"
"*.github.com" = "allow"
"*" = "deny"  # 拒绝其他所有

💡 注意：network_proxy 只在 network_access = true 的前提下生效；它是过滤层，不是开关。

Web 搜索相关问题

Codex 默认使用缓存模式的 web 搜索（pre-indexed 结果，防止 prompt injection）：

# ~/.codex/config.toml
web_search = "cached"  # 默认：缓存索引结果
# web_search = "live"  # 实时搜索（或用 --search 标志）
# web_search = "disabled"  # 完全关闭

如果搜索结果不够新 → 切换到 "live" 或使用 codex --search "task"。

---

6. 上下文与性能问题

会话上下文太长，AI 开始遗忘指令

# 压缩会话历史，保留关键信息
/compact

# 带焦点压缩（告诉 Codex 保留什么）
/compact focus on the API auth changes

# 查看当前 token 用量
/status

会话卡死 / 无响应

# 终止当前操作
Ctrl+C

# 强制关闭后恢复上次会话
codex resume --last
# 或
codex resume <SESSION_UUID>

上下文超限循环（context thrashing）

当一个大文件或工具输出立刻填满压缩后的上下文，Codex 停止自动压缩并报错。

解决步骤：

# 1. 带焦点压缩，丢弃大文件输出
/compact keep only the plan and the diff

# 2. 在对话中指定读取文件的特定行范围
# 例："只读取 app.log 的最后 50 行"

# 3. 用子代理处理大文件（独立上下文窗口）

---

7. 平台差异与特殊场景

Windows 沙盒配置

Windows 原生运行 Codex 时，需要在 config.toml 中指定 sandbox 模式：

[windows]
sandbox = "elevated"    # 推荐，需要管理员权限
# sandbox = "unelevated"  # 没有管理员权限时的备选

Windows 需要安装 Git for Windows（提供 bash）或 PowerShell。如果看到 Claude Code on Windows requires either Git for Windows (for bash) or PowerShell，先安装 Git for Windows。

WSL 性能问题

在 WSL 中跨 /mnt/c/ 访问 Windows 文件系统会有显著 I/O 损耗，导致代码搜索变慢。

解决方案：

• 将项目迁移到 Linux 文件系统（/home/user/ 下）
• 使用更具体的搜索指令减少文件扫描范围

CI/CD 非交互场景

# 正确的 CI 用法
codex exec --sandbox workspace-write "fix failing tests"
codex exec --sandbox read-only --ask-for-approval never "review code"

# 结构化输出（便于脚本解析）
codex exec --json --output-last-message result.txt "task"

# 注意：旧版 codex exec --full-auto 已废弃，会显示警告

---

8. 通用排错流程

遇到问题
    ↓
codex --debug "描述问题"      → 查看详细日志
    ↓
检查 ~/.codex/config.toml    → 确认配置语法和优先级
    ↓
codex sandbox macos -- cmd   → 测试沙盒是否阻断了目标命令
    ↓
codex execpolicy check --rules ~/.codex/rules.yaml -- cmd  → 检查 exec policy
    ↓
codex features list          → 确认相关 feature 是否开启
    ↓
GitHub Issues: github.com/openai/codex/issues  → 搜索已知问题（5k+ issues）

---

写在最后

Codex 排错的核心是三条路径：

• 配置层：优先级从 CLI 参数到系统级，~/.codex/config.toml 是用户级入口
• 沙盒层：--sandbox 控制文件系统边界，--ask-for-approval 控制自动化程度，codex sandbox 命令可测试具体命令是否被允许
• 认证层：~/.codex/auth.json 缓存凭据，headless 环境用 --device-auth 或复制 auth.json

codex --debug 是万能的第一步，它会输出详细日志，帮你快速定位问题所在。

最后聊一类排错文档里很少会写的"隐性故障"——国内开发者登录链卡死：OAuth 弹窗打不开、--device-auth 验证页打开很慢、token 在某些机房会被频繁刷新失败。这往往不是 Codex 本身的 bug，而是网络环境问题。如果不想每次都折腾代理和海外信用卡，可以试试 Code80——真实订阅账号转 API，换个 endpoint 就能在 Codex 里直接用，省掉了登录认证链上一半的排错工作。详情可以到官网了解：code.ai80.vip。

---

常见问题（FAQ）

Q1：Codex 和 Claude Code 的排错方法可以通用吗？

A：不能直接套用。两者配置体系完全不同：Codex 用 ~/.codex/config.toml（TOML 格式）和 AGENTS.md；Claude Code 用 ~/.claude/settings.json（JSON 格式）和 CLAUDE.md。排错命令也不同：Codex 用 /status、/permissions、codex sandbox；Claude Code 用 /doctor、/memory、/mcp。

Q2：Codex 配置写在 .codex/config.toml 里，但不生效？

A：检查项目是否被标记为**“不可信”**——不可信项目会跳过项目级 .codex/ 层（包括 config、hooks 和 rules）。可通过 /permissions 命令或 Desktop 设置界面管理项目信任状态。另外检查是否有 CLI 参数或 --profile 文件以更高优先级覆盖了该设置。

Q3：在远程服务器上如何不用浏览器登录 Codex？

A：两种方法：① codex login --device-auth，在另一台机器的浏览器上完成验证；② 在本地完成 codex login 后，将 ~/.codex/auth.json 通过 scp 复制到服务器相同路径。auth.json 包含访问令牌，传输时注意安全。

Q4：codex exec 中网络请求被沙盒拒绝怎么解决？

A：默认沙盒关闭网络。在 ~/.codex/config.toml 或项目 .codex/config.toml 中添加 [sandbox_workspace_write] network_access = true。若需精细控制，用 [features.network_proxy] 配置域名白名单，只允许必要的目标地址。

Q5：--yolo 模式安全吗？

A：不安全，官方明确标注 [Elevated Risk]。--yolo（即 --dangerously-bypass-approvals-and-sandbox）完全跳过沙盒和审批，等同于直接以你的身份运行 AI 生成的任意命令，只应在完全隔离的容器或 CI 环境中使用，绝对不要在个人开发机上使用。

Q6：国内开发者频繁遇到登录失败 / token 刷新失败怎么办？

A：这往往是网络环境问题，不是 Codex 本身的 bug。可以走 Code80 这种真实订阅账号转 API 的渠道——按拿到的 Base URL 和 Key 配进 Codex 配置就能直接跑，绕过 OAuth 链上的不稳定因素，体验跟官方一致。

---

相关资源

• Codex 官方文档 — CLI、App、配置参考全文
• Codex Config 基础 — config.toml 配置项说明