---
title: "通过 Databricks 连接模型服务"
summary: "用户层 [model_providers.Databricks]，base_url 以 /ai-gateway/codex/v1 结尾，wire_api = responses。短时令牌走 [model_providers.Databricks.auth]，避免重复配置 env_key。"
category: config
level: intermediate
surfaces: [cli, app, ide]
tags: ["model_providers", "Databricks", "wire_api", "profile"]
canonical: /tips/databricks-codex-gateway/
---

# 通过 Databricks 连接模型服务

用户层 [model_providers.Databricks]，base_url 以 /ai-gateway/codex/v1 结尾，wire_api = responses。短时令牌走 [model_providers.Databricks.auth]，避免重复配置 env_key。

Databricks 官方 Codex 网关：profile 写 [model_providers.Databricks]，base_url 以 /ai-gateway/codex/v1 结尾，令牌走 [model_providers.Databricks.auth]。

这是换 Codex **使用的模型**，流量打到 workspace 的 Unity Gateway `/ai-gateway/codex/v1`，不是添加 MCP 服务。MCP 仍走已有的 `ug mcp add --agents codex`。推荐入口是 Unity Gateway CLI（主命令 `ug`，`ucode` 只是别名）帮你写配置：

```bash
uv tool install git+https://github.com/databricks/unity-gateway
databricks auth login --host YOUR_WORKSPACE
ug codex
```

需要 Codex CLI 0.118+、Python 3.12+ 和 `uv`。`ug` 会写 agent 配置；日常用 `ug codex` 启动。OSS 模型例如 `ug codex --model system.ai.glm-5-2`，这是网关托管的 Responses 模型，**不是** `--oss`。

手写时供应商表放**用户** `~/.codex/config.toml`。官方示例还在写 `[profiles.default]`；0.134 起这张表会被拒绝。更稳妥是独立 profile（用户层 `$CODEX_HOME`，不是项目 `.codex`）。**不要**同时写 `env_key`：`[model_providers.*.auth]` 和 `env_key` / `experimental_bearer_token` / `requires_openai_auth` 互斥。**Codex 不会在 `base_url` 里展开环境变量**，主机名要写成字面量。

```toml
# ~/.codex/databricks.config.toml
model_provider = "Databricks"

[model_providers.Databricks]
name = "Databricks AI Gateway"
base_url = "https://YOUR_WORKSPACE/ai-gateway/codex/v1"
wire_api = "responses"

[model_providers.Databricks.auth]
command = "sh"
args = ["-c", "databricks auth token --host YOUR_WORKSPACE --output json | jq -r '.access_token'"]
timeout_ms = 5000
refresh_interval_ms = 1800000
```

```bash
codex --profile databricks
```

自定义供应商必须 `wire_api = "responses"`。项目 `.codex/config.toml` 无法修改 `model_provider` / `model_providers`。不要写 `openai_base_url`。先 `databricks auth login --host YOUR_WORKSPACE`；令牌短时有效，`refresh_interval_ms = 1800000` 让长会话到期前重跑命令。

把流量打到你在 Unity Catalog 登记的外部供应商时，用 `ug codex --provider CATALOG.SCHEMA.SERVICE`。CLI 会在供应商表加头 `Databricks-Model-Provider-Service`。不要把 OpenAI / Anthropic 密钥写进 Codex。

配置说明：

- 不要再写 `[profiles.default]` 或 `[profiles.databricks]`。
- 不要把这张表当成 MCP。MCP 是 `ug mcp add --agents codex`。
- 不要覆盖内置 ID `openai`、`ollama`、`lmstudio`。`Databricks` 是新 ID，可以。
- 不要写进项目 `.codex/config.toml`。
- 不要给 `auth` 表再叠 `env_key` 或把 PAT 写进 TOML。

改完新开会话。`codex --profile databricks` 或 `ug codex` 启动后，发送一条简短请求验证连接。401 先看 `databricks auth login` 是否还有效。

## 来源

- [Databricks · Integrate with coding agents](https://docs.databricks.com/aws/en/ai-gateway/coding-agent-integration-model-services)
- [Databricks · Model provider services](https://docs.databricks.com/aws/en/ai-gateway/coding-agent-integration-model-provider-services)
- [Databricks GCP · Integrate with coding agents](https://docs.databricks.com/gcp/en/ai-gateway/coding-agent-integration-model-services)