Codex默认调用本地Ollama模型配置指南

要让 Codex Desktop App 默认使用本地 Ollama 模型，核心在于正确修改其全局主配置文件 ~/.codex/config.toml。以下是详细的配置步骤、关键配置项说明以及验证方法。

1. 核心配置步骤与代码示例

首先，强烈建议在修改前备份原始配置文件。

bash 复制代码

# 备份原配置文件
cp ~/.codex/config.toml ~/.codex/config.toml.bak.$(date +%Y%m%d-%H%M%S)

然后，使用文本编辑器（如 nano、vim 或 code）编辑主配置文件。

bash 复制代码

# 使用 nano 编辑配置文件
nano ~/.codex/config.toml

在配置文件中，需要写入或修改以下关键配置段。请确保你的配置文件包含这些内容。

toml 复制代码

# 1. 指定默认使用的模型及其提供者 
model = "gpt-oss-codex:20b"
model_provider = "ollama-local"

# 2. 配置模型上下文和输出长度，以适应 Codex Agent 的需求 
model_context_window = 8192
model_max_output_tokens = 2048

# 3. 其他相关策略配置 
approval_policy = "on-request"
sandbox_mode = "workspace-write"
oss_provider = "ollama"

# 4. 定义名为 "ollama-local" 的模型提供者 
[model_providers.ollama-local]
name = "Ollama Local"
# 指向本地运行的 Ollama 服务 API 端点
base_url = "http://localhost:11434/v1"
# 指定使用的 API 协议版本
wire_api = "responses"
# 本地服务无需 OpenAI 认证
requires_openai_auth = false

# 5. (可选) 配置对新模型可用性的引导提示 
[tui.model_availability_nux]
"gpt-5.5" = 1

# 6. (可选) 将特定项目目录标记为可信，以放宽安全限制 
[projects."/Users/your_username/Documents/daily"]
trust_level = "trusted"

重要提示 ：请将上述配置中的 /Users/your_username/Documents/daily 替换为你实际的项目工作目录路径。

2. 关键配置项解析

下表详细说明了上述配置中各个关键项的作用和注意事项：

配置项	作用说明	注意事项与参考来源
`model`	指定 Codex 默认使用的模型名称。	必须与通过 `ollama create` 创建的本地模型名完全一致。
`model_provider`	指定模型提供者（Provider）。	必须与下方定义的 `[model_providers]` 节名称匹配，此处为 `ollama-local` 。
`model_context_window`	定义模型的最大上下文长度（Token数）。	Codex Agent 的提示词较长，必须设置为 8192 或更高，否则会因截断导致任务失败。
`base_url`	指向本地 Ollama 服务的 API 地址。	确保端口（默认为11434）与本地 Ollama 服务一致。
`wire_api`	指定与 Ollama 通信的 API 协议。	必须设置为 `"responses"` 。旧版的 `"chat"` 已被新版本 Codex 弃用。
`requires_openai_auth`	标识该提供者是否需要 OpenAI 格式的 API 密钥认证。	对于本地 Ollama 服务，必须设置为 `false` 。
`[profiles.ollama-launch]`	（需避免）旧式的 Profile 配置节。	在新版 Codex 中，在主配置中使用此格式会导致 `legacy profile` 错误，请勿添加。

3. 前置条件与模型准备

在应用上述配置前，请确保满足以下条件：

Ollama 服务已运行 ：确保本地 Ollama 服务正在运行，并且 API 可访问。
bash 复制代码
```
# 检查服务状态
curl http://localhost:11434/v1/models
```

拥有合适上下文的本地模型 ：Codex 需要较大的上下文窗口。如果基础模型（如 gpt-oss:20b）的上下文不足，需要创建一个派生模型。

bash 复制代码

# 创建一个上下文为 8192 的派生模型 
cat > /tmp/Modelfile.gpt-oss-codex <<'EOF'
FROM gpt-oss:20b
PARAMETER num_ctx 8192
EOF
ollama create gpt-oss-codex:20b -f /tmp/Modelfile.gpt-oss-codex

4. 验证配置生效

配置完成后，通过以下步骤验证 Desktop App 是否成功切换至本地模型：

从项目目录启动 App ：最佳实践是从一个具体的项目目录启动，而非配置目录。
bash 复制代码
```
cd ~/Documents/your_project
codex app
```
执行测试命令 ：在启动的 Desktop App 中，输入一个简单的 shell 命令进行测试。
复制代码
```
执行 pwd，然后执行 ls -la。不要修改文件。
```
检查运行结果 ：
- 成功标志 ：App 输出类似 Ran pwd && ls -la 的结果，并且没有出现 You've hit your usage limit. Upgrade to Pro... 的云端额度提示。
- 失败排查 ：如果仍然提示额度限制，说明 App 仍在走云端。请检查 ~/.codex/config.toml 中 model 和 model_provider 的配置是否正确，并确保重启了 App。
监控 Ollama 日志（高级） ：最直接的证据是查看 Ollama 服务是否收到了请求。
bash 复制代码
```
# 实时查看 Ollama 日志（macOS Homebrew 安装路径示例）
tail -f /opt/homebrew/var/log/ollama.log
```
在 App 中发送测试命令后，如果日志中出现 POST "/v1/responses" 的记录，则证明请求已成功发送至本地 Ollama 服务。

5. 常见问题与解决方案

问题现象	可能原因	解决方案
启动 App 仍报 `usage limit`	主配置未生效，或仍在使用旧 Profile。	1. 确认 `~/.codex/config.toml` 中 `model` 和 `model_provider` 已正确设置。 2. 运行 `grep -R "profiles.ollama-launch" ~/.codex` 检查并删除相关旧配置。 3. 彻底关闭 App (`pkill -f Codex`) 后重启。
出现 `
502 Bad Gateway`	模型上下文不足，导致请求被 Ollama 拒绝。	检查 Ollama 日志是否有 `truncating input prompt` 提示。如果是，需要创建上下文更大的模型（如 16384）并更新 `model_context_window` 配置。
出现 `API key login is required`	配置中可能包含了 `forced_login_method = "api"`。	在主配置中删除此行，并确保 `requires_openai_auth = false` 。
出现 `Model metadata not found`	自定义的派生模型缺少 Codex 内置的元数据。	此警告可暂时忽略，不影响核心功能使用。

通过以上步骤，你可以将 Codex Desktop App 的默认行为从使用云端模型切换到本地 Ollama 模型，从而完全在本地环境中运行，避免云端额度的限制。整个过程的核心是正确编辑全局 config.toml 文件，并确保本地拥有一个上下文足够大的 Ollama 模型。

Codex默认调用本地Ollama模型配置指南

1. 核心配置步骤与代码示例

2. 关键配置项解析

3. 前置条件与模型准备

4. 验证配置生效

5. 常见问题与解决方案

参考来源