跳至正文

文件

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