---
title: "通过 NVIDIA NIM 连接模型服务"
summary: "官方主路径是用户层 [model_providers.nim]，wire_api = responses，env_key = NIM_API_KEY，base_url 是本机 NIM 的 /v1。再用 ~/.codex/nim.config.toml 和 --profile nim。"
category: config
level: intermediate
surfaces: [cli, app]
tags: ["model_providers", "NVIDIA", "NIM", "wire_api", "profile"]
canonical: /tips/nim-codex-gateway/
---

# 通过 NVIDIA NIM 连接模型服务

官方主路径是用户层 [model_providers.nim]，wire_api = responses，env_key = NIM_API_KEY，base_url 是本机 NIM 的 /v1。再用 ~/.codex/nim.config.toml 和 --profile nim。

NVIDIA NIM 官方 Codex 网关：用户层 [model_providers.nim]，base_url 是 http://localhost:8000/v1，env_key 读 NIM_API_KEY。

这是换 Codex **使用的模型**，不是添加 MCP 服务，也不是 `npx skills add nvidia/skills`。Codex 直接打 NIM 的 OpenAI Responses 入口 `/v1/responses`，中间不需要翻译代理。自定义供应商必须 `wire_api = "responses"`，不要写 `chat`。

官方示例把 `model` 和 `model_provider` 写进用户 `~/.codex/config.toml`，会变成**所有**会话的默认后端。更稳妥是独立 profile（用户层 `$CODEX_HOME`，不是项目 `.codex`）：

```toml
# ~/.codex/nim.config.toml
model = "nvidia/nemotron-3-super-120b-a12b"
model_provider = "nim"

[model_providers.nim]
name = "NVIDIA NIM"
base_url = "http://localhost:8000/v1"
env_key = "NIM_API_KEY"
wire_api = "responses"
```

```bash
export NIM_API_KEY="not-used"
codex --profile nim
```

`model` 必须和 NIM `/v1/models` 返回的 `id` **一字不差**。带斜杠的名字合法，例如 `nvidia/nemotron-3-super-120b-a12b`。换模型前先：

```bash
curl -s http://localhost:8000/v1/models
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8000/v1/health/ready
```

`base_url` 必须带 `/v1` 后缀。本机默认是 `http://localhost:8000/v1`；远程 NIM 换成主机名，端口跟 `NIM_SERVER_PORT` 走。`env_key` 是变量**名**。NIM **不校验**这把钥匙，但 Codex 要求进程里有非空值，占位字符串即可。必须出现在**启动 Codex 的那个进程**里。从已经 `export NIM_API_KEY` 的终端启动；Dock 打开的桌面不会读你刚改的 zshrc。拉镜像用的 `NGC_API_KEY` 不是这颗 `env_key`。

0.134 起不要再写 `[profiles.nim]`。profile 名跟文件名 `nim.config.toml` 对齐。供应商表也可以放进用户 `~/.codex/config.toml`，但不要写进项目 `.codex/config.toml`：项目文件无法修改 `model_provider` / `model_providers`。

NIM 默认**没开** Codex 依赖的 vLLM 参数。起容器时要同时带 `--enable-auto-tool-choice`、匹配模型的 `--tool-call-parser`，推理模型再加 `--reasoning-parser`。官方 Nemotron 3 Super 示例是 `qwen3_coder` 和 `nemotron_v3`。缺 tool parser 时模型会把工具调用写成散文，Codex 不动作；缺 reasoning parser 时思考文本会当成答案打印出来。用 `NIM_SERVED_MODEL_NAME` 钉住对外模型名，和 profile 里的 `model` 对齐。

gpt-oss 走 Harmony Responses，只接受 `function`、`web_search_preview`、`code_interpreter`、`container`。Codex 默认还会发 `web_search` 和 `namespace`（Skills / 子代理），会 400。官方要求一次关掉这些，而不是修一个再爆下一个。`web_search` 是**裸顶层键**，必须写在**所有** `[section]` 之前；写在 `[model_providers.nim]` 或 Codex 自动追加的 `[projects."…"]` 后面，会静默变成 `model_providers.nim.web_search`，`tool type web_search not supported` 还在：

```toml
# ~/.codex/nim.config.toml
web_search = "disabled"

model = "YOUR_GPT_OSS_MODEL_ID"
model_provider = "nim"

[model_providers.nim]
name = "NVIDIA NIM"
base_url = "http://localhost:8000/v1"
env_key = "NIM_API_KEY"
wire_api = "responses"

[agents]
enabled = false

[features]
multi_agent_v2 = false

[skills.bundled]
enabled = false

[orchestrator.skills]
enabled = false

[orchestrator.mcp]
enabled = false
```

非 gpt-oss 模型走普通 Responses，不必抄这段关闭项。

配置说明：

- 不要把这张表当成 `npx skills add nvidia/skills --agent codex`。那是 cuOpt / Jetson 技能，不是换模型。
- 不要覆盖内置 ID `openai`、`ollama`、`lmstudio`。`nim` 是新 ID，可以。
- 不要写 `wire_api = "chat"`，也不要省略 `base_url` 的 `/v1`。
- 不要把密钥写进 `http_headers`。
- 不要把 `OPENAI_BASE_URL` 当主路径。走 `[model_providers.nim]`。

改完新开会话。`codex --profile nim` 启动后，发送一条简短请求验证连接。404 先对照 `/v1/models` 改 `model`；连不上先看 `/v1/health/ready` 是不是 200。长会话把上下文超出限制时提高 `NIM_MAX_MODEL_LEN`，无关任务新开一轮。

## 来源

- [NVIDIA NIM · Use Codex CLI with NIM](https://docs.nvidia.com/nim/large-language-models/latest/ai-assistant-integrations/codex-cli.html)
- [NVIDIA NIM · Tool Calling and MCP Integration](https://docs.nvidia.com/nim/large-language-models/latest/advanced-use-cases/tool-calling-and-mcp.html)
- [NVIDIA NIM · API Reference](https://docs.nvidia.com/nim/large-language-models/latest/reference/api-reference.html)