通过Unity Gateway在终端中使用Codex,配合模型、MCP工具和技能。 使用 Unity Gateway CLI (ug) 来配置访问,或手动配置连接。
通过 Unity Gateway 将 Codex CLI 与 支持的开源模型 配合使用,有助于降低编码代理的成本。
要将工具连接到现有的Codex设置,请前往 添加MCP工具。
Prerequisites
你需要你的 Azure Databricks workspace URL、你想用的模型、MCP 和技能访问权限,以及最新的 Codex CLI。
如果你的管理员已经配置了你的设备,请按照组织的启动说明操作。
使用Unity Gateway CLI(推荐)
安装 ug,然后从你的项目目录执行以下命令:
ug codex
按照提示选择你的工作区并登录。
ug 配置连接并在终端中打开Codex。 开始使用你已经在使用的相同提示词和命令。 要更改模型,请输入 /model。
继续 添加MCP工具 或 添加技能,使 Codex 能够访问数据和共享指令。
使用您自己的 ChatGPT 订阅
要通过Unity Gateway在您自己的ChatGPT Go、Plus、Pro或Enterprise订阅上运行Codex,请让管理员为您提供ChatGPT订阅模型提供商服务。 请参阅 ChatGPT订阅支持 ,了解需求、管理设置、工作原理和限制。
将模型提供程序服务的完全限定名称(<catalog>.<schema>.<name>)传递给 --provider,并将工作区 URL 传递给 --workspace:
ug codex --provider main.default.chatgpt_subscription --workspace https://<workspace>.databricks.com
如果 Codex 未使用 ChatGPT 登录,ug会运行codex login以打开浏览器进行登录。 API密钥登录不算数。
ug 配置Codex发送 Databricks-Model-Provider-Service 头部,并将Codex指向本地刷新代理,而非直接到Unity Gateway端点。 代理会将每个请求转发到 https://<workspace-url>/ai-gateway/codex/v1,并添加 X-Databricks-AI-Gateway-Token 标头。 由于服务不存储凭证,代理会透传你的 ChatGPT 登录信息,且不会存储它。
如果你遇到问题,使用codex logout注销,然后重新运行命令再次登录。
Note
ChatGPT 订阅模型提供程序服务的--provider仅在与ug codex配合使用时受支持。 智能路由不支持ChatGPT订阅模型提供商服务。
手动配置ChatGPT订阅
只有在你不能使用 ug时才使用手动设置。
获取 Azure Databricks 令牌。 该
X-Databricks-AI-Gateway-Token标头携带一个 Azure Databricks 令牌,用于对发往 Unity Gateway 的请求进行身份验证。 Unity Gateway 会将访问控制和使用日志记录归因于与此令牌绑定的身份,因此请使用属于发起查询的用户的令牌。 请选择以下选项之一:通过 Databricks CLI 实现 OAuth 用户到机器 (U2M)(推荐) 用CLI登录一次,然后铸造一个短命的OAuth令牌:
databricks auth login --host https://<workspace-url> databricks auth token --host https://<workspace-url> | jq -r .access_token参见 Authorize user access to Azure Databricks with OAuth and Authentication for the Databricks CLI。 U2M OAuth 令牌大约在1小时后过期,所以对于交互式使用,你需要在它到期时替换它。 要自动化令牌刷新,可以使用
ug,它运行一个本地代理,每次请求都会帮你刷新 OAuth 令牌。个人访问令牌(PAT),作为备份。 如果无法使用 OAuth,请创建 PAT,并将其用作
<databricks-token>。 PAT 不会像 OAuth 那样按 1 小时周期失效,但它是一种与你的身份关联的长期有效凭证。 请参阅 使用 Azure Databricks 个人访问令牌(旧版)进行身份验证。
关闭Codex,然后打开或创建
~/.codex/config.toml。 在 Windows 上,使用%USERPROFILE%\.codex\config.toml。 将以下设置合并到文件中。 保持model_provider在顶层,在任何表格标题之前,并保留无关的设置。model_provider = "databricks" [model_providers.databricks] name = "Databricks" base_url = "https://<workspace-url>/ai-gateway/codex/v1" wire_api = "responses" requires_openai_auth = true http_headers = { "X-Databricks-AI-Gateway-Token" = "Bearer <databricks-token>", "Databricks-Model-Provider-Service" = "<catalog>.<schema>.<name>" }- 用你的工作区 URL 替换
<workspace-url>。 - 用上一步的 Azure Databricks 令牌替换
<databricks-token>。 - 用模型提供程序服务的完全限定名称替换
<catalog>.<schema>.<name>。
requires_openai_auth = true让 Codex 发起自己的 ChatGPT 登录。 不要向此提供程序添加auth表。 保持文件私密,因为它存储了你的 Azure Databricks 令牌。- 用你的工作区 URL 替换
开始 Codex:
codex如果你还没登录,Codex会提示你进行身份验证。 选择“使用ChatGPT登录”,并使用您的ChatGPT账户登录。 API 密钥登录不适用于 ChatGPT 订阅模型提供程序服务。 如果你遇到问题,使用
codex logout注销并再次登录。
你的Codex请求现在会通过Unity Gateway路由。 请求将按你的 ChatGPT 订阅计费,并且你可以获得集中访问、路由和使用管理。
在 Azure Databricks 计算资源上运行
要在无服务器计算或专用集群上运行Codex而不安装 ug,请通过SSH隧道连接并运行 codex。 该代理已预先配置用于 Unity Gateway。 参见 “在 SSH 会话中运行编码代理”。
手动配置模型
关闭Codex,然后打开或创建 ~/.codex/config.toml。 在 Windows 上,使用 %USERPROFILE%\.codex\config.toml。
将以下设置合并到文件中。 将 model 和 model_provider 保持在顶层,位于任何表头之前,并保留其他无关设置。
model = "<catalog>.<schema>.<model-name>"
model_provider = "databricks"
[model_providers.databricks]
name = "Databricks"
base_url = "https://<workspace-hostname>/ai-gateway/codex/v1"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
http_headers = { Authorization = "Bearer <databricks-pat>" }
将模型占位符替换为其完整的 Unity Catalog 名称,将 <workspace-hostname> 替换为你的工作区主机名,并将 <databricks-pat> 替换为你的个人访问令牌。 本示例将令牌存储在本地;保持文件私密,使用您自己的令牌。
从你的项目目录里运行 codex 。 如果你的设备有托管服务商设置,请让你的管理员更新;这些设置优先于用户配置。
有关字段详情,请参见OpenAI的配置参考。
添加MCP工具
system.ai.dbsql, system.ai.sandbox, 和 system.ai.web_search 都处于 测试阶段。 要使用这些内容,账户管理员必须在账户控制台的 预览 页面启用 增强版 Unity Gateway 预览。 Unity Gateway 本身已正式发布。 请参阅管理帐户预览。
- 在你的工作区中打开 Unity Gateway > MCP 。 选择 内置的MCP 或 注册你的外部MCP服务器。
- 复制MCP的全名,如
system.ai.github或<catalog>.<schema>.<service>。 - 确认你能 访问MCP。
使用 Unity Gateway CLI
安装 ug,然后将MCP添加到Codex:
ug mcp add --agents codex --names <catalog>.<schema>.<service>
把占位符替换成你复制的名字。 比如,对 GitHub 使用 --names system.ai.github。 要以交互方式选择服务,请省略 --names。
在首次设置时,按照提示选择你的工作区,登录并选择模型。
ug 配置模型和MCP访问,并刷新凭证。 如需使用您自己的OAuth应用访问MCP,请使用下面的手动设置。
使用 ug codex 重启 Codex CLI,然后 测试一个工具。
手动配置 MCPs
使用公共的 Azure Databricks OAuth 应用登录并刷新凭据。
使用默认的 Codex 客户端 ID(无需账户管理员创建 OAuth 应用):
在Codex中注册MCP,替换占位符:
codex mcp add databricks-tools \ --url "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>?o=<workspace-id>" \ --oauth-client-id https://chatgpt.com/oauth/codex/client.json登录后重新打开Codex:
codex mcp login databricks-tools --scopes ai-gateway,offline_access
然后 测试一个工具。
搭建一个自定义的OAuth应用
关闭 Codex。 在
~/.codex/config.toml中,将这些设置添加到顶层,任何表页头之前。 它们为本地OAuth回调提供固定端口:mcp_oauth_callback_port = 8080 mcp_oauth_callback_url = "http://127.0.0.1:8080/callback"让账户管理员在账户控制台中打开设置 > 应用连接 > 添加连接。 使用诸如
codex-mcp的名称,清除“生成客户端机密”,将重定向 URL 设置为http://127.0.0.1:8080/callback,并选择ai-gateway范围。 保存并复制 客户端ID。 参见 创建OAuth应用。在Codex中注册MCP,替换占位符:
codex mcp add databricks-tools \ --url "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>?o=<workspace-id>" \ --oauth-client-id <client-id>请查看Codex打印的回调链接。 它可以包含服务器特定的后缀。 让管理员在登录前把这个确切的URL添加到OAuth应用的重定向URL里。 添加另一台服务器时重复这个检查。
登录后重新打开Codex:
codex mcp login databricks-tools --scopes ai-gateway,offline_access
有关回调设置,请参见 OpenAI的MCP认证说明。 然后 测试一个工具。
使用个人访问令牌进行本地测试
将以下内容添加到 ~/.codex/config.toml 中,替换主机名、工作区 ID 和令牌:
[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql?o=<workspace-id>"
http_headers = { Authorization = "Bearer <databricks-pat>" }
对于另一个MCP,请在 mcp_servers 下使用唯一名称,并将 system.ai.dbsql 替换为其全名。 保持文件私密,然后重启Codex测试工具。
测试MCP工具
- 在Codex中输入
/mcp并检查服务器是否已连接。 - 让Codex列出该服务器的工具,然后请求读取操作。 对于 GitHub,让它在你可以访问的仓库中查找一个 Issue。 对于自定义服务器,使用你注册时测试过的工具和输入。
- 如果工具调用提示你登录,请打开 MCP 返回的登录链接,完成提供程序同意,然后重试调用。 登录后,MCP可以访问你的外部账户。
- 检查Codex是否调用工具并返回结果。 仅凭文字回复并不能验证该连接。
要使用 Azure Databricks 数据,请连接 system.ai.genie_one_mcp 用于业务问题,或连接 system.ai.dbsql 用于 SQL。 例如,要求SQL MCP运行 SELECT 1 AS result。
有关权限、策略和使用情况,请参见 管理MCP。
添加技能
使用 Unity Gateway CLI
运行互动选择器:
ug skills add
或者下载一个特定的已发布技能:
ug skills add --names <catalog>.<schema>.<skill-name>
重启Codex CLI。 下载的技能可在 ~/.agents/skills/ 本地使用。 重新运行下载以获取更新版本。
若要改为通过 MCP 公开架构的技能,请运行:
ug skills add --location "<catalog>.<schema>" --via mcp
手动连接技能注册表
请将以下内容添加到 ~/.codex/config.toml:
[mcp_servers.databricks-skill-registry]
url = "https://<workspace-hostname>/ai-gateway/skills/"
http_headers = { Authorization = "Bearer <databricks-pat>" }
替换主机名和令牌。 保留 URL 末尾的斜杠。 重启Codex并要求使用已发布的技能,比如 Use <catalog>.<schema>.<skill-name> to review this query.
注册表通过 MCP 加载技能指令。 要安装你已有的技能文件,请将完整的 SKILL.md 技能文件夹,包括捆绑文件,放入 ~/.agents/skills/。
Unity Gateway 技能还处于测试阶段。 请参见 治理技能 中的赋能和权限。
故障排除
请求失败时出现WebSocket错误:在活跃的Azure Databricks提供者表中设置
supports_websockets = false。 如果你的管理员管理该配置,请让他们更新。 之后重启应用。缺少一个模型: 检查你的模型权限。 在当前活动配置中,将
model设置为其完整的 Unity Catalog 名称,然后开启新对话。MCP或技能连接失败: 检查URL、权限和连接器错误。 手动连接时,也要检查令牌过期。 如果
ug设置有问题,请运行ug doctor。 即使注册表连接失败,下载的技能仍可保留。工作区登录是正常的,但有个工具要求你登录: 打开MCP返回的登录链接,登录外部提供商,然后重试该调用。 工作区登录和身份提供商登录是分开的步骤。
OAuth 报告重定向不匹配或连接超时: 将 OAuth 应用的重定向 URL 与 Codex 报告的准确 URL 匹配,包括任何后缀,并检查 网络访问。 OAuth 应用的更改可能需要 长达30分钟 才能生效。