Codex 默认调用本地 Ollama 模型：config.toml 配置指南

1. 为什么要把 Codex 默认模型切到本地 OllamaCodex 这类编码 Agent 默认走云端模型好处是开箱即用坏处也很明显一旦触发额度限制正写到一半的重构任务直接中断提示Youve hit your usage limit。对于经常在离线环境、内网机器或者想彻底掌控推理成本的开发者来说把默认模型指向本地 Ollama 是更稳的选择。Codex 的模型路由完全由全局主配置文件~/.codex/config.toml决定。只要在这个文件里把model和model_provider指向本地 Ollama 服务Codex 启动后就会把请求发到http://localhost:11434/v1不再消耗云端额度。这篇就围绕这个配置文件展开给出可直接复制的骨架、关键项含义、验证命令以及我实际踩过的几个坑。适合谁看已经装好 Ollama、手头有能跑 20B 级别模型的机器、想让 Codex 默认离线运行的开发者。如果你还没决定要不要本地跑也可以先用 TaoToken 的统一 Key 通道把云端和本地两条路都留着后面按场景切换。2. 前置准备Ollama 服务与 TaoToken 通道2.1 确认 Ollama 在跑配置之前先确认本地服务活着端口默认 11434curl http://localhost:11434/v1/models返回一个 JSON 列表就说明服务正常。如果连不上先ollama serve起服务或者检查是不是被别的进程占了端口。2.2 准备一个上下文够大的模型Codex Agent 的提示词很长系统提示、工具定义、文件上下文叠起来轻松超过 4K token。基础模型如果上下文太小请求会被 Ollama 截断表现为 502 或者任务莫名其妙失败。所以通常要派生一个num_ctx更大的模型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-codexollama create完成后用ollama list应该能看到gpt-oss-codex:20b。这个名字必须和后面 config.toml 里的model完全一致差一个字符都会找不到模型。2.3 TaoToken 统一 Key 通道可选但推荐本地模型适合离线和大批量任务但有些场景你仍然需要云端模型兜底比如本地机器跑不动的大模型、或者需要更强推理能力的复杂重构。这时候可以用 TaoToken 的统一 Key 通道把云端模型也接进同一套配置体系切换时只改model_provider一行。TaoToken 的 API 入口是https://taotoken.net/api兼容 OpenAI 协议。你可以在控制台创建 Key然后在 config.toml 里加一个云端 provider 段。这样本地和云端两条路都通按任务类型选。创建 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite3. 可复制的 config.toml 骨架3.1 先备份改配置前养成备份习惯出问题能秒回滚cp ~/.codex/config.toml ~/.codex/config.toml.bak.$(date %Y%m%d-%H%M%S)3.2 完整配置骨架用nano ~/.codex/config.toml或你顺手的编辑器打开写入下面内容。注意把[projects....]里的路径换成你自己的项目目录# 默认使用的模型必须与 ollama create 的名字一致 model gpt-oss-codex:20b model_provider ollama-local # 上下文与输出长度Codex Agent 提示词长8192 起步 model_context_window 8192 model_max_output_tokens 2048 # 审批与沙箱策略 approval_policy on-request sandbox_mode workspace-write oss_provider ollama # 本地 Ollama provider 定义 [model_providers.ollama-local] name Ollama Local base_url http://localhost:11434/v1 wire_api responses requires_openai_auth false # 可选把常用项目目录标记为可信 [projects./Users/your_username/Documents/daily] trust_level trusted3.3 关键项逐个说清楚配置项作用注意点modelCodex 默认调用的模型名必须和ollama create的名字完全一致model_provider指定 provider必须和下方[model_providers.xxx]节名匹配model_context_window最大上下文 token 数低于 8192 容易截断导致任务失败base_urlOllama API 地址端口默认 11434要和实际服务一致wire_api通信协议新版 Codex 用responses旧的chat已弃用requires_openai_auth是否需要 OpenAI 认证本地服务必须false注意不要添加[profiles.ollama-launch]这种旧式 Profile 节。新版 Codex 在主配置里遇到它会报 legacy profile 错误直接删掉。3.4 想同时保留云端通道如果你用 TaoToken 做云端兜底可以在同一个文件里再加一段 provider[model_providers.taotoken] name TaoToken base_url https://taotoken.net/api wire_api responses requires_openai_auth true env_key TAOTOKEN_API_KEY然后把 Key 放进环境变量export TAOTOKEN_API_KEY你的Key需要切云端时把顶部model_provider改成taotoken、model改成对应云端模型名即可。本地和云端共用一套配置结构切换成本很低。4. 验证 Codex 是否真的走了本地 Ollama4.1 从项目目录启动别在配置目录里启动从实际项目目录起这样 Codex 的工作区上下文才对cd ~/Documents/your_project codex app4.2 发一个测试命令在启动的 App 里输入一个简单 shell 任务比如执行 pwd然后执行 ls -la。不要修改任何文件。4.3 看结果判断成功标志App 输出类似Ran pwd ls -la的结果并且没有出现Youve hit your usage limit. Upgrade to Pro...的云端额度提示。如果还提示额度限制说明 App 仍在走云端配置没生效。往下看排查部分。4.4 最硬的证据看 Ollama 日志想确认请求真的到了本地直接盯 Ollama 日志tail -f /opt/homebrew/var/log/ollama.log在 App 里发测试命令后日志里应该出现POST /v1/responses的记录。看到这条就证明 Codex 的请求确实打到了本地 Ollama。5. 常见报错与排查动作5.1 启动后仍报 usage limit最常见的原因是主配置没生效或者旧 Profile 还在干扰。按顺序做# 确认主配置里的 model 和 model_provider grep -E ^(model|model_provider) ~/.codex/config.toml # 搜有没有残留的旧 profile 配置 grep -R profiles.ollama-launch ~/.codex # 彻底关掉 App 再重启 pkill -f Codex找到旧 profile 相关行就删掉然后重启 App。5.2 出现 502 Bad Gateway多半是模型上下文不够请求被 Ollama 拒绝。查日志有没有truncating input prompt提示。有的话重新派生一个num_ctx更大的模型比如 16384同时把model_context_window同步改大cat /tmp/Modelfile.big EOF FROM gpt-oss:20b PARAMETER num_ctx 16384 EOF ollama create gpt-oss-codex:20b -f /tmp/Modelfile.big5.3 报 API key login is required配置里可能混进了forced_login_method api。在主配置里删掉这一行并确认requires_openai_auth false。5.4 报 Model metadata not found自定义派生模型缺少 Codex 内置的元数据这个警告可以暂时忽略不影响核心功能。只要请求能正常发到 Ollama 并返回结果就不用管它。5.5 改了配置没反应Codex 不会热加载配置改完必须完全退出再启动。pkill -f Codex之后重新codex app别只关窗口。6. 本地与云端怎么选按场景分流本地 Ollama 的优势是离线、零边际成本、数据不出机器适合大批量代码扫描、内网项目、以及不想被额度打断的长时间重构。但它对机器有要求20B 级别模型在普通笔记本上跑起来会比较吃力。如果你需要更强的推理能力或者本地机器带不动大模型可以用 TaoToken 的 Coding Plan 做长期编码和 Agent 任务的云端通道配置方式就是上面那段[model_providers.taotoken]。想先验证模型效果、对比本地和云端输出差异可以直接在模型对话里试模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite我自己的做法是日常小改动和离线任务走本地 Ollama遇到复杂架构重构或者本地跑不动的模型时把model_provider切到 TaoToken 通道配置只改一行不用重装任何东西。这样两边的优势都能吃到也不会被单一通道卡住。