第15章 连接 Databricks · Omnigent

连接 Databricks

Omnigent 支持按用户连接 Databricks：服务器管理员注册 Databricks OAuth 应用后，登录用户可以进入 Settings → Sandbox Integrations → Connect Databricks，填写自己的 workspace URL 并授权其 Databricks workspace。此后托管沙箱会以该用户的身份，使用短效的按用户 OAuth token（而非共享的个人访问 token）访问 workspace 的 AI Gateway（MCP + 模型服务）。

这套机制与连接 GitHub 一致：同样的短效、绑定用户的 token 模型，同样的 Settings → Sandbox Integrations 入口。由于 Databricks 支持多 workspace，用户需要在连接时提供自己的 workspace 地址。

该功能仅在配置了凭据存储（Credential Store，即 OMNIGENT_CREDENTIAL_* / KMS）时才会启用。Token 由凭据存储加密后静态持久化，复用现有的连接存储——无需新建表或迁移。如果没有 KMS 密钥（OMNIGENT_CREDENTIAL_KMS_KEY_ID），Databricks 连接会记录错误并保持禁用状态。

工作原理

- 连接（用户 OAuth）：服务器生成一个短效的、绑定用户的状态参数（signed state），并通过 OAuth U2M（authorization-code + PKCE）将用户重定向到其 workspace 的 OAuth 授权页面。Workspace 回调 …/v1/connections/databricks/callback，用授权码换取按用户的 access token（外加来自 offline_access 的 refresh token），并以加密形式存入凭据存储。

- 按 workspace 主机：Databricks 是多 workspace 的，所以 OAuth 端点相对于 workspace（https:///oidc/v1/authorize 和 /oidc/v1/token）。用户填写的 workspace 主机地址会包含在签名状态中，并存入连接元数据。

- 沙箱内使用：沙箱启动时，宿主机会写入一个 ~/.databrickscfg，指向所有者的按用户凭据代理（只写 workspace 主机地址——token 绝不会持久化到沙箱磁盘）。基于命令的 harness（codex、claude、pi）会按需从代理获取新 token，并在临近过期时刷新，确保长时间会话对 AI Gateway 保持认证。

注册 Databricks OAuth 应用

必须由 Databricks 账户管理员注册 OAuth 自定义应用集成，以获取 client id / secret 并登记回调 URL。这是账户层面的操作，无法在 Omnigent 内完成（与 GitHub App 需要在外部注册的道理相同）。

``` databricks account custom-app-integration create --json '{ "name": "omnigent-connect", "redirect_urls": ["https:///v1/connections/databricks/callback"], "scopes": ["all-apis", "offline_access"], "confidential": true }' ```

- redirect_urls 中的条目必须与 OMNIGENT_DATABRICKS_REDIRECT_URI 一致（或与 Omnigent 从 OMNIGENT_DOMAIN 推导出的值一致，其格式正是如此）。 - 必须包含 offline_access，才能获取 refresh token 供服务端刷新。all-apis 覆盖 AI Gateway 所需的接口——确认网关所需的具体 scope 后可以收窄。 - confidential: true 会生成 client secret，这是 Omnigent 所必需的。

在服务器上配置

在服务器上设置以下环境变量。只要存在 client id + secret 以及可解析的 redirect URI（且凭据存储已配置），该功能会自动启用：

``` # 必填。 OMNIGENT_DATABRICKS_CLIENT_ID= OMNIGENT_DATABRICKS_CLIENT_SECRET=

# Redirect URI — 显式设置，或让 Omnigent 从 OMNIGENT_DOMAIN 推导， # 格式为 https://$OMNIGENT_DOMAIN/v1/connections/databricks/callback（相同格式）。 OMNIGENT_DATABRICKS_REDIRECT_URI=https:///v1/connections/databricks/callback

# 可选。 OMNIGENT_DATABRICKS_SCOPES="all-apis offline_access" # 默认值如示 OMNIGENT_DATABRICKS_ALLOWED_HOST_SUFFIXES=.databricks.com,.azuredatabricks.net # 默认值如示 ```

| 变量 | 必填 | 用途 | | --- | --- | --- | | OMNIGENT_DATABRICKS_CLIENT_ID | 是 | OAuth client id（即账户的 custom-app-integration id）。 | | OMNIGENT_DATABRICKS_CLIENT_SECRET | 是 | 应用的 client secret；同时用于签署 OAuth state 和派生 PKCE verifier。 | | OMNIGENT_DATABRICKS_REDIRECT_URI | 是* | OAuth 回调 URL。*未设置时从 OMNIGENT_DOMAIN 推导。 | | OMNIGENT_DATABRICKS_SCOPES | 否 | 以空格分隔的请求 scope。默认为 all-apis offline_access。 | | OMNIGENT_DATABRICKS_ALLOWED_HOST_SUFFIXES | 否 | 以逗号分隔、以点号开头的 workspace 主机后缀白名单。默认值见下。 |

由于 client secret 会被 POST 到用户填写的 workspace 主机，Omnigent 会限制该主机必须属于 Databricks 域：默认为 .databricks.com 和 .azuredatabricks.net。使用私有部署或政府区域环境的运维人员可以通过 OMNIGENT_DATABRICKS_ALLOWED_HOST_SUFFIXES 扩展该列表。

重启服务器。如果已设置 client id 和 secret，但无法解析出 redirect URI（OMNIGENT_DATABRICKS_REDIRECT_URI 和 OMNIGENT_DOMAIN 都未设置），功能会记录警告并保持禁用。CLI（omnigent server）和 Docker 镜像读取同一套环境变量。

验证

- 以真实用户身份登录 Omnigent，打开 Settings → Sandbox Integrations。可以看到 Connect Databricks 控件——只有配置了连接提供方时才会显示该导航项（通过 /v1/info 中的 enabled_connections 暴露）。 - 输入你的 workspace URL（如 your-workspace.cloud.databricks.com），点击 Connect Databricks → workspace 授权页面 → 返回 Omnigent。面板会显示 Connected to as 。断开连接会删除已存储的 token。 - 启动一个沙箱会话，确认 agent 的 Databricks 调用（模型服务 / MCP）以你的身份通过 workspace 的 AI Gateway 路由。