跳到主要内容

Codex 常见问题

本页适用于 Codex CLI 和 VS Code 中的 Codex 插件。ChatGPT 桌面端请查看 ChatGPT 常见问题。

先按报错判断
  • error sending request for url：先检查配置目录中的 .env，再检查代理或网络。
  • 当前服务暂不支持该模型 / model_not_found：检查模型名称和 CODEX 令牌分组。
  • 403 Forbidden：检查令牌的 模型可用列表。

按教程配置后没有生效​

教程默认将配置写入 Windows 的 %userprofile%\.codex 或 macOS / Linux 的 ~/.codex。如果系统中设置了 CODEX_HOME，Codex 会改为读取该变量指向的目录；此时继续修改默认目录中的文件不会生效。

请先完全退出 Codex CLI 或 VS Code，再重新打开终端，并按当前系统执行下面的命令。命令会显示 Codex 实际使用的配置目录，并打开该目录中的 config.toml 和 auth.json。

在 PowerShell 中执行：

$codexDir = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME '.codex' }
New-Item -ItemType Directory -Force $codexDir | Out-Null
$codexDir
notepad (Join-Path $codexDir 'config.toml')
notepad (Join-Path $codexDir 'auth.json')

如果显示的目录不是默认的 .codex，请将 Codex 配置教程中的完整配置写入这里打开的文件。保存后完全退出客户端，再重新启动。

如果使用 VS Code 中的 Codex 插件，也可以点击 Codex 面板右上角的齿轮，选择 Codex Settings → Open config.toml，直接打开当前配置文件。

仍未生效时检查配置优先级​

Codex 可能同时读取多层配置。当前官方优先级从高到低依次为：启动命令中的参数、受信任项目内的 .codex/config.toml、通过 --profile 选择的配置、用户目录中的 config.toml、系统级配置、Codex 内置默认值。高优先级配置会覆盖低优先级的同名设置。

在 Codex CLI 中输入：

/debug-config

可以查看实际加载的配置层和生效来源；再输入 /status，确认当前模型、工作目录和权限设置是否符合预期。

APINebula 的 model_provider 和 [model_providers.codex] 必须保存在用户级 config.toml 中。按照 Codex 官方规则，项目内的 .codex/config.toml 不能覆盖模型供应商配置，但可以覆盖 model 等普通设置。如果只有某个项目中的模型不一致，请检查该项目是否存在 .codex/config.toml，以及启动 Codex 时是否使用了 --model、--config 或 --profile。

Codex CLI：出现 error sending request for url​

如果 Codex CLI 显示下面这类报错：

error sending request for url (...)

Codex CLI 连接失败示例

这通常是本地网络或代理连接异常。请先检查 Codex 配置目录中是否有 .env 文件；如果有，请确认其中没有覆盖代理或接口相关的旧环境变量。检查完成后，再按下面顺序处理：

  1. 完全退出 Codex CLI，并关闭当前终端窗口。
  2. 如果配置目录中没有 .env，再关闭并重新开启代理工具，也就是常说的“开关魔法”。
  3. Windows 下确认代理工具的 TUN 模式已经开启，否则浏览器可以联网，但终端可能无法使用代理。
  4. 如果问题是突然出现的，切换一个可用节点或网络出口后再试。
  5. 重新打开终端并启动 Codex CLI。

如果网页可以正常访问，但 Codex CLI 仍然报错，优先确认终端进程是否实际使用了代理；不要因为这一类连接错误立即更换令牌。

如何设置全局或项目工作规则​

Codex 会读取 AGENTS.md 作为长期工作规则。两种常用位置分别是：

  • 全局规则：放在 Codex 配置目录中，对所有项目生效。
  • 项目规则：放在项目根目录中，只对当前项目生效；更靠近当前工作目录的规则优先级更高。

创建或打开全局 AGENTS.md：

在 PowerShell 中执行：

$codexDir = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME '.codex' }
New-Item -ItemType Directory -Force $codexDir | Out-Null
notepad (Join-Path $codexDir 'AGENTS.md')

如果希望为当前项目创建规则，可在 Codex CLI 中进入项目目录后输入 /init，生成项目级 AGENTS.md 模板。Codex 通常在每次启动会话时重新读取规则，修改后请新建会话或完全重启客户端。

Windows 下沙盒或目录访问异常​

Codex 当前支持在 Windows 中原生运行，不必为了使用沙盒而强制切换到 WSL。官方建议优先使用 Windows 11；较新的 Windows 10 可以使用，但兼容性相对有限。

如果 Codex 提示当前使用的是降级沙盒，或原生沙盒尚未完成设置，可在 Codex CLI 中输入：

/setup-default-sandbox

然后按提示完成管理员授权。官方推荐使用 elevated 原生沙盒；如果设备策略不允许完成管理员设置，可以在 config.toml 末尾加入下面的回退配置：

[windows]
sandbox = "unelevated"

如果只是某个项目外目录无法读取，并且该目录确实需要用于当前任务，可在当前 Codex CLI 会话中输入：

/sandbox-add-read-dir C:\需要读取的\绝对路径

该路径必须是已经存在的绝对目录。不要为了省去确认而直接关闭全部沙盒保护。

如何使用实时联网搜索​

Codex 本地会话默认使用缓存搜索。需要读取最新网页内容时，Codex CLI 可以通过下面的命令启动一次实时搜索会话：

codex --search

如果希望 Codex CLI 和 VS Code 插件默认使用实时搜索，请将下面一行写在用户级 config.toml 顶层，也就是 [model_providers.codex] 之前：

web_search = "live"

旧版的 [features] web_search_request = true 已被官方标记为弃用，不建议继续写入新配置。

返回 503：服务暂时不可用​

使用当前测试 Key 请求 gpt-5.6-sol 时，接口返回：

服务暂时不可用，请稍后重试
error.code: get_channel_failed

这表示当前模型没有可用通道，属于服务端模型路由暂时不可用，不是 API Key 格式错误。请稍后重试；如果持续出现，再联系客服并提供请求时间和 request id。

如果接口返回模型不支持或 model_not_found，请按下面步骤检查：

  1. 在模型广场搜索配置中的模型名称。
  2. 确认该模型支持 CODEX 分组。
  3. 在令牌管理创建或更换为 CODEX 分组令牌。
  4. 确认 Codex 配置中的 model 与模型广场显示的名称完全一致。

返回 403：该令牌无权访问模型​

这通常表示创建令牌时填写的 模型可用列表 不包含当前模型。建议将该列表留空；如果必须限制模型，请填写与 Codex 配置完全一致的模型名称。

Codex CLI 常用排查命令​

命令用途
/status查看当前模型、工作目录、权限和上下文使用情况
/debug-config查看配置层级及每项配置的实际来源
/model切换当前会话使用的模型和推理强度
/diff查看当前 Git 变更，包括未跟踪文件
/review让 Codex 审查当前工作区变更
/compact总结较长的会话，释放上下文空间
/init在当前项目生成 AGENTS.md 模板
/mcp查看当前已配置的 MCP 工具

继续阅读​

微信扫码联系我们