OpenConnector OAuth app 配置指南

OAuth2 provider 需要用户授权时，OOMOL OpenConnector 使用你自己在 provider 后台创建的 OAuth app。你需要在 provider 的 developer console 中创建 app，把 OpenConnector runtime 给出的准确 callback URL 填到 provider app 里，再把 app 的 client 配置保存到 OpenConnector。

这篇指南适用于 Gmail、Google Drive、Google Calendar、Slack、HubSpot、GitHub、Microsoft Outlook、Notion、Zoom、Zendesk、Jira、Dropbox，以及 OpenConnector provider catalog 中展示的其他 OAuth2 provider。

本文只覆盖 OAuth app 配置。使用其他认证方式的 provider，请按 OpenConnector provider 页面展示的 credential 字段配置。

你需要准备什么

一个正在运行的 OOMOL OpenConnector runtime。
可以访问 OpenConnector Web 控制台。
如果设置了 OOMOL_CONNECT_ADMIN_TOKEN，需要准备 admin token。
拥有在目标 provider developer 或 admin console 中创建 OAuth app 的权限。
一个用于测试连接的 provider 账号、workspace、tenant、organization 或 portal。

如果 runtime 通过公开域名、tunnel 或 Cloudflare Worker URL 访问，请先设置 OOMOL_CONNECT_ORIGIN，再创建 provider OAuth app。Redirect URI 会基于这个 origin 生成。

OOMOL_CONNECT_ORIGIN="https://connect.example.com" \
OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_ENCRYPTION_KEY="replace-with-a-long-random-secret" \
docker compose up --build

第 1 步：确定 OpenConnector callback URL

用用户在浏览器中打开的 OpenConnector origin 拼出 callback URL：

<openconnector-origin>/oauth/callback

默认本地 runtime 下，多数 OAuth provider 使用：

http://localhost:3000/oauth/callback

设置 OOMOL_CONNECT_ORIGIN 后，callback URL 会使用对应公开 origin：

https://connect.example.com/oauth/callback

把这个准确 callback URL 填入 provider OAuth app。除非你的 OpenConnector origin 自身带结尾斜杠，否则不要额外添加结尾斜杠。

第 2 步：创建 provider OAuth app

打开 provider 的 developer console，创建 OAuth app、integration、connected app、public app 或 application registration。不同 provider 的命名不同，但通常需要填写同一类字段。

Provider app 字段	填写内容
App name	你能识别的名称，例如 `OpenConnector Local` 或内部工具名称。
Homepage 或 website URL	你的产品、内部工具、代码仓库或 runtime URL。使用用户和管理员能识别的值。
Redirect URI、callback URL 或 reply URL	OpenConnector 的准确 callback URL，例如 `https://connect.example.com/oauth/callback`。
Scopes 或 permissions	OpenConnector provider 需要的 scopes。可从 provider 页面或 action guide 中复制。
Distribution、install 或 visibility	如果 provider 允许，并且你只连接自己的账号，可保持 private、test-only、internal 或 unlisted。

很多 provider 允许你在 marketplace 上架前，先授权自己的账号、测试用户、workspace 或 organization。某些 provider 仍会因为敏感 scopes、生产使用、广泛客户分发或受管理 workspace，要求验证、管理员审批或审核。Provider 授权页和 admin console 是最终准确信息。

第 3 步：复制 client 配置

创建 provider app 后，复制 OpenConnector 需要的 client 值。

值	是否必需	说明
`clientId`	是	通常叫 Client ID、App ID、Application ID 或 Consumer Key。
`clientSecret`	通常需要	某些 provider 使用 public-client flow，不要求 secret。如果 OpenConnector 把该 provider 的 secret 标为可选，且 provider 侧也明确不要求 secret，才可以留空。
Extra fields	有时需要	某些 provider 还需要额外 OAuth client 配置，例如 `tenant`、`subdomain`、`developerToken` 或账号标识。请使用能展示该 provider 所需字段的控制台版本。

不要把 OAuth client secret 放到浏览器代码、公开仓库、截图、issue 或 Agent prompt 中。

第 4 步：在 OpenConnector 中保存 OAuth client

普通配置优先使用 OpenConnector Web 控制台：

打开 OpenConnector Web 控制台，例如 http://localhost:3000。
打开 Providers，选择要连接的 provider。
点击 Configure OAuth Client 或 Edit OAuth Client。
粘贴 provider app 的 Client ID 和 Client Secret。
点击 Save OAuth Client。

如果 provider 需要额外 client 字段，请在同一个 OAuth client 表单中填写。例如 Microsoft provider 需要 tenant 值。如果你的控制台没有展示 provider 必需字段，请先升级到支持该 provider 完整 OAuth client 表单的 OpenConnector 版本，再继续配置。

保存后，provider 页面会显示 OAuth client 已配置。已保存的 client secret 不会再次显示。

第 5 步：连接测试账号

保存 OAuth client 后，停留在 provider 页面并点击 Connect 启动授权。在 provider 授权页批准授权。Provider 跳回 OpenConnector 后，确认 provider 页面显示账号已连接。

第 6 步：测试 action

使用 provider 页面或控制台 action 列表，运行一个低风险读取 action。Action 详情会显示输入 schema、需要的 scopes 和当前连接身份。

测试写入类 action 时请使用 demo data。

Provider 说明

创建 OAuth app 时，这些官方文档比较有用：

Provider 类型	官方文档	常见配置点
Google APIs	Using OAuth 2.0 for Web Server Applications	使用 web application OAuth client。把 OpenConnector 的准确 redirect URI 加入 authorized redirect URIs。敏感或受限 scopes 在广泛生产使用前可能需要 Google verification。
Slack	Installing with OAuth	把 OpenConnector 的准确 redirect URI 加到 app redirect URLs 中。如果 Slack 不接受本地 callback URL，请用公开 runtime origin 或 HTTPS tunnel。
GitHub	Creating an OAuth app	GitHub OAuth app 只有一个 authorization callback URL。如果本地、staging 和 production 需要不同 callback URL，建议创建多个 app。
Microsoft	Register an application with the Microsoft identity platform	配置 Web platform redirect URI，并创建 client secret。部分 OpenConnector Microsoft provider 需要 `tenant`，例如 `common`、`organizations` 或具体 tenant ID。
HubSpot	Working with OAuth	Authorization request 里的 scopes 必须匹配 app 已配置 scopes。生产 redirect URL 必须使用 HTTPS；localhost 测试可以使用 HTTP。
Notion	Authorization	创建 public connection，并在 OAuth configuration 中加入 OpenConnector redirect URI。在自己的 workspace 之外使用前，请检查 Notion 当前的 app type 和 capability 规则。

排查建议

现象	检查项
Provider 提示 `redirect_uri_mismatch`、invalid redirect URI 或 invalid callback URL。	确认 provider app 使用的是 `<openconnector-origin>/oauth/callback`。Scheme、host、port、path 和结尾斜杠必须和用户在浏览器中打开的 origin 一致。
Provider 拒绝 `http://localhost`。	使用支持 localhost 测试的 provider，或通过 HTTPS tunnel / 公开域名暴露 runtime，并在重启 OpenConnector 前把 `OOMOL_CONNECT_ORIGIN` 设置为该 origin。
Provider 提示 app 未验证、未审批或 workspace 不允许。	检查 provider 侧 app distribution、test users、workspace app approval 和敏感 scope review 要求。Marketplace 上架通常和私有测试是两件事，但具体规则以 provider 为准。
授权成功，但 action 因 missing 或 insufficient scopes 失败。	把该 action 需要的 scopes 加到 provider app 中，保存后重新连接 provider 账号，让新 scopes 生效。
OpenConnector 提示 `oauth_client_config_not_found`。	确认你已经在启动 Connect 的同一个 provider 页面保存了 OAuth client。
后续 token refresh 失败。	确认 provider 发放了 refresh token。某些 provider 需要 offline-access 参数或重新 consent。没有 refresh token 时，请重新连接账号。
执行 action 时用了错误账号。	使用已登录目标账号的浏览器 profile 重新连接，然后在控制台中选择目标连接再测试 action。

安全检查

保存 OAuth client secrets 或 connected account credentials 前，先设置 OOMOL_CONNECT_ENCRYPTION_KEY。
保护 OOMOL_CONNECT_ADMIN_TOKEN，/v1 和 /mcp 调用使用 runtime token。
在 provider 和 OpenConnector action set 允许时，使用最小权限 scopes。
如果 provider callback 规则让环境难以区分，为 local、staging 和 production 使用不同 OAuth app，方便审计。
删除不再使用的 provider app、旧 client secret 和过期 OpenConnector connection。