---
author: OOMOL
author_url: https://oomol.com/zh-cn/about/
title: OpenConnector OAuth app 配置指南
description: 创建 provider OAuth app，配置回调地址，并连接到自部署的 OOMOL OpenConnector runtime。
lang: zh-CN
canonical_url: https://oomol.com/zh-cn/docs/openconnector-oauth-apps/
markdown_url: https://oomol.com/zh-cn/docs/openconnector-oauth-apps.md
---

# 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 生成。

```bash
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：

```text
<openconnector-origin>/oauth/callback
```

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

```text
http://localhost:3000/oauth/callback
```

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

```text
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 控制台：

1. 打开 OpenConnector Web 控制台，例如 `http://localhost:3000`。
2. 打开 **Providers**，选择要连接的 provider。
3. 点击 **Configure OAuth Client** 或 **Edit OAuth Client**。
4. 粘贴 provider app 的 **Client ID** 和 **Client Secret**。
5. 点击 **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](https://developers.google.com/identity/protocols/oauth2/web-server) | 使用 web application OAuth client。把 OpenConnector 的准确 redirect URI 加入 authorized redirect URIs。敏感或受限 scopes 在广泛生产使用前可能需要 Google verification。 |
| Slack | [Installing with OAuth](https://docs.slack.dev/authentication/installing-with-oauth) | 把 OpenConnector 的准确 redirect URI 加到 app redirect URLs 中。如果 Slack 不接受本地 callback URL，请用公开 runtime origin 或 HTTPS tunnel。 |
| GitHub | [Creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) | GitHub OAuth app 只有一个 authorization callback URL。如果本地、staging 和 production 需要不同 callback URL，建议创建多个 app。 |
| Microsoft | [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/graph/auth-register-app-v2) | 配置 Web platform redirect URI，并创建 client secret。部分 OpenConnector Microsoft provider 需要 `tenant`，例如 `common`、`organizations` 或具体 tenant ID。 |
| HubSpot | [Working with OAuth](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth) | Authorization request 里的 scopes 必须匹配 app 已配置 scopes。生产 redirect URL 必须使用 HTTPS；localhost 测试可以使用 HTTP。 |
| Notion | [Authorization](https://developers.notion.com/guides/get-started/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。