跳至正文

文档

OpenConnector 凭据、Runtime Token 与 OAuth

了解自托管 OpenConnector 的应用凭据、runtime 访问权限、OAuth 回调和命名连接配置。

由 OOMOL 维护·

源码核对日期：2026-09-09. 示例已按链接中的源码版本核对，不代表通过了真实上游 API 验证；你部署的版本可能有所不同。

区分 runtime 访问权限与应用凭据

管理员凭据保护控制台和 /api 接口，Runtime Token 授权 /v1 和 /mcp 客户端。应用凭据属于已连接的应用账号，并保存在 runtime 内部；这些凭据不能互相替代。

注册自己的 OAuth 应用

自托管时，在服务商处注册 OAuth 应用，并从 /api/oauth/configs 复制准确的 expectedRedirectUri。配置远程回调前，先将 OOMOL_CONNECT_ORIGIN 设为公开访问源地址。按工作流需要选择授权范围。

选择要使用的账号连接

不指定别名时使用服务商的默认连接。使用 x-oo-connector-alias 选择命名连接；Runtime Token 的连接授权可能限制客户端可使用的账号。

持久化并保护凭据

Docker 镜像将本地 runtime 数据放在 /app/data，应挂载持久化卷。使用 OOMOL_CONNECT_ENCRYPTION_KEY 加密存储凭据，并妥善保存恢复所需的密钥；公开部署前请阅读部署指南。

完成 OAuth 账号连接

  1. 先将 OOMOL_CONNECT_ORIGIN 设置为浏览器访问的地址。读取 /api/oauth/configs，将对应服务的 expectedRedirectUri 原样填入 OAuth 应用。启用管理端认证时，请附带管理端 Bearer 令牌。
  2. 在本地控制台保存服务的 OAuth Client ID 和 Secret。按需从服务声明的 scopes 中选择子集，发起授权，并在服务提供方的浏览器页面批准访问。
  3. 回调完成后，检查 /api/connections，确认账号身份和连接名称，再调用 Action。命名连接必须事先存在，选择别名不会自动创建连接。

下面第一个请求用管理端令牌检查账号连接，第二个请求用运行时令牌和已有的 work 连接调用只读 Action。请替换成自己的连接名；使用默认连接时省略别名请求头。

GET /api/connections
curl -s http://localhost:3000/api/connections \
  -H "Authorization: Bearer $OOMOL_CONNECT_ADMIN_TOKEN"
HTTP · GitHub
curl -s -X POST \
  http://localhost:3000/v1/actions/github.get_current_user \
  -H "Authorization: Bearer $OOMOL_CONNECT_RUNTIME_TOKEN" \
  -H 'x-oo-connector-alias: work' \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

理解调用结果

HTTP 运行时响应包含 success、message、data 和 meta。请检查 success 及 Action 输出 Schema，不要只看 HTTP 状态码。执行元数据包含 executionId 时，可据此定位脱敏运行日志。下面仅展示响应结构，并非真实 API 调用结果。

示意响应
{
  "success": true,
  "message": "OK",
  "data": {},
  "meta": {}
}

调用失败时如何排查

  • 认证失败时，先核对接口和凭证类型：管理端凭证用于 /api，运行时 Bearer 令牌用于 /v1 和 /mcp。服务提供方的 API Key 不能替代运行时令牌。
  • 权限被拒绝时，检查 Action 所需 scopes、运行时 Action 规则和连接授权。令牌有效也不代表有权使用所选账号。
  • 结果为空或资源缺失时，检查连接账号及其对目标资源的访问权限。完成授权不代表能访问所有工作区、频道或文档。
  • 重试前先检查错误与运行日志。对于会修改服务数据的 Action，先确认操作是否已经完成，不要盲目重复请求。
阅读 Markdown