Codex 配置一键起飞：2026 年最实用的 config.toml 与踩坑避坑指南

前两天在折腾 Codex 的时候，发现网上能找到的配置文件要么过时，要么就是那种‘理论上可行’但实际跑起来各种报错的半成品。索性自己从头到尾梳理了一遍，整理出一份真正能用的 config.toml，顺便把踩过的坑都记下来，省得大家重复受罪。

一、直接可用的 config.toml 模板

基于 Codex 2026.08 版本的 config.toml 模板

下面这份配置是基于最新版 Codex（2026.08 稳定版）测试通过的，适用于大多数主流 Linux 发行版（Ubuntu 24.04 / Debian 13 / Arch Linux）。复制粘贴后，只需要调整 model_path 和 device 两个参数，就能直接跑起来。

[general]

model_path = "/path/to/your/model.gguf"

device = "cuda" # 支持 cuda、cpu、mps（Mac），默认 cuda

max_new_tokens = 2048

temperature = 0.7

top_p = 0.9

repeat_penalty = 1.1

[context]

context_length = 8192

preload_context = true

[performance]

threads = 8

batch_size = 512

gpu_layers = 50 # 根据显存调整，16G 显存建议 30-40

[api]

enable = true

port = 8080

host = "0.0.0.0"

注意：如果你是 Mac 用户，把 device 改成 mps 就行；如果是纯 CPU 运行，改成 cpu，但速度会慢很多。gpu_layers 的值可以先设成显存的一半（单位 GB），比如 24G 显存就设 40-50，然后逐步调高，直到不报 OOM 错误为止。

Codex 运行时的 CUDA 版本不匹配报错

二、踩坑记录：这些坑我都帮你踩过了

1. 显存不足的问题

最常见的报错就是 Out of memory，尤其是在跑 70B 以上的模型时。解决方案有三个：

减少 gpu_layers：这个参数直接决定了模型在 GPU 上加载的层数。如果你的显存是 16G，先试试 30，不行再降到 20。每降 10，显存占用大概减少 2-3G。

启用 CPU offload：在 config.toml 里加上 cpu_offload = true，这样模型会把部分层放到 CPU 上运行。缺点是速度会慢一点，但能跑起来。

使用 4bit 量化：如果模型是 8bit 的，可以尝试转成 4bit。工具推荐 llama.cpp 的 quantize 命令，一行搞定：

./quantize /path/to/model.gguf /path/to/model-q4_k.gguf q4_k

4bit 模型在精度损失不大的情况下，能节省一半的显存。

2. CUDA 版本不匹配

Codex 对 CUDA 版本要求比较严格，尤其是在使用最新的 NVIDIA 驱动时。如果你跑起来报 CUDA error: no kernel image is available，十有八九是版本问题。

解决方案：

查看当前 CUDA 版本：nvcc --version

如果是 CUDA 12.x，确保 Codex 也是用 CUDA 12.x 编译的版本。

如果是 CUDA 11.x，可能需要降级驱动或者重新编译 Codex。

经验：Ubuntu 24.04 默认安装的是 CUDA 12.4，而很多预编译的 Codex 版本还是基于 CUDA 11.8。这种情况下，要么自己编译，要么用 Docker 版本（官方镜像一般会处理好依赖）。

3. 多 GPU 并行加速

如果你有多块 GPU，可以尝试让 Codex 同时使用它们。在 config.toml 里加上：

[multi_gpu]

enable = true

gpu_ids = [0, 1] # 使用第 0 和第 1 块 GPU

注意：

多 GPU 模式下，gpu_layers 需要设成总显存除以 GPU 数量。比如两块 24G 的卡，gpu_layers 可以设成 40-50。

如果模型太大，可能需要调整 tensor_split 参数，但这个需要手动测试，没有一劳永逸的方案。

4. API 服务挂掉的问题

如果你启用了 API 服务（[api] enable = true），可能会遇到服务无响应或者自动退出的情况。

常见原因：

端口冲突：检查 port 参数是否被其他程序占用，用 netstat -tulnp | grep 8080 查看。

权限问题：如果用的是 Docker，确保容器有权限绑定端口。

内存泄漏：长时间运行后，内存占用会逐渐上升。解决方案是定期重启服务，或者限制 max_new_tokens 的值。

临时解决方案：用 screen 或者 tmux 后台运行，避免 SSH 断开后服务停止。

5. 模型加载慢

如果模型特别大（比如 70B+），加载时间可能需要几分钟。这时候可以：

启用 preload_context = true，让模型提前加载上下文。

使用 mmap 模式加载模型，在 config.toml 里加上 use_mmap = true。

如果是 SSD，确保模型文件在 NVMe 盘上，机械硬盘加载速度会慢很多。

三、不同场景下的配置调整

场景 1：低配机器（8G 显存）

目标：跑 13B-30B 的模型。

[general]

model_path = "/path/to/model-13b-q4_k.gguf"

device = "cuda"

[performance]

gpu_layers = 20 # 8G 显存建议 15-25

cpu_offload = true

threads = 4

[context]

context_length = 4096 # 降低上下文长度

建议：

使用 4bit 量化的模型。

关闭 preload_context，节省内存。

如果还是不够，尝试 gpu_layers = 10 + cpu_offload = true。

场景 2：高性能服务器（24G+ 显存）

目标：跑 70B 模型，支持多用户并发。

[general]

model_path = "/path/to/model-70b-q4_k.gguf"

device = "cuda"

max_new_tokens = 4096

[performance]

gpu_layers = 50 # 24G 显存建议 40-50

threads = 16

batch_size = 1024

[multi_gpu]

enable = true

gpu_ids = [0, 1]

[api]

enable = true

port = 8080

host = "0.0.0.0"

max_concurrent_requests = 8 # 限制并发数

建议：

使用 tensor_split 手动分配层数，比如 tensor_split = [25, 25]（两块 24G 的卡）。

监控 GPU 使用率，如果某块卡负载不均，调整 gpu_ids 的顺序。

场景 3：MacBook Pro（M3 Max）

目标：本地跑 7B-13B 模型。

[general]

model_path = "/path/to/model-7b-q4_k.gguf"

device = "mps"

[performance]

gpu_layers = 1 # MPS 模式下 gpu_layers 无效，设成 1 即可

threads = 8

[context]

context_length = 4096

建议：

MPS 模式下，gpu_layers 可以忽略，但 threads 要设成 CPU 核心数的一半。

如果模型太大，会报 MPS error: out of memory，这时候只能降低模型大小或者使用 4bit 量化。

四、一些实用的小技巧

1. 快速测试配置

在正式跑之前，可以先用 --test 参数测试配置是否可行：

codex --config config.toml --test

这个命令会加载模型并运行一个简单的推理任务，如果没报错，说明配置没问题。

2. 监控 GPU 使用情况

跑起来后，用 nvidia-smi 或者 watch -n 1 nvidia-smi 实时监控 GPU 使用情况。如果发现某块卡的利用率特别低，可能是 gpu_layers 分配不均。

3. 日志输出

如果想调试问题，可以在 config.toml 里加上：

[log]

level = "debug"

file = "/var/log/codex.log"

这样所有的运行日志都会写到文件里，方便排查问题。

4. 自动重启服务

如果是生产环境，可以用 systemd 管理 Codex 服务，这样挂掉了会自动重启。

创建 /etc/systemd/system/codex.service：

[Unit]

Description=Codex API Service

After=network.target

[Service]

User=your_user

WorkingDirectory=/path/to/codex

ExecStart=/path/to/codex --config /path/to/config.toml

Restart=always

RestartSec=5

[Install]

WantedBy=multi-user.target

然后：

sudo systemctl daemon-reload

sudo systemctl enable codex

sudo systemctl start codex

五、最后的建议

Codex 的配置看起来复杂，但其实核心就三个点：显存分配、CUDA 兼容性、API 稳定性。只要把这三个问题解决了，其他都是小问题。

如果你在配置过程中遇到什么奇葩的报错，先别慌，大部分问题都是显存不够或者版本不匹配。先检查 nvidia-smi，再看日志，最后才是配置文件。

另外，如果你有更好的配置方案或者踩坑经验，欢迎在评论区分享。大家一起进步，少走弯路。