跳至主要內容

文件

從第一個工作流程到每個連接器的設定細節。

快速開始

  1. 註冊並登入 Web 版。
  2. 建立新的工作流程，畫布上已有作為起點的「觸發」節點。
  3. 拖出「動作」節點，選擇連接器（例如 Email），並填寫設定。
  4. 將觸發器節點連接到動作節點，然後儲存。
  5. 點選「執行」，輸入測試資料，然後在執行紀錄中查看各節點的結果。

工作流程編輯指南

工作流程由三種節點組成：

  • 觸發：起點——每個工作流程恰好有一個。執行時收到的資料會成為它的輸出。
  • 條件：做出一個判斷，輸出「是」和「否」；只有符合條件的分支會執行。
  • 動作：呼叫連接器，例如寄送郵件、呼叫 API 或寫入資料庫。

儲存時會檢查：觸發器節點恰好一個、每條連線兩端都已連接、沒有循環、條件輸出標記為「是／否」，以及每個動作的必要欄位都已填寫。問題會逐項列出。

執行時會從觸發器節點開始沿著連線執行；任何節點失敗，整次執行會立即停止並標記為失敗。

條件

條件包含左值、運算子和右值；兩側都可以是固定值或參照值（請參閱下一節）。

運算子含義範例
eq / ne等於 / 不等於$.input.status eq "paid"
gt / gte大於 / 大於等於$.input.amount gt 1000
lt / lte小於 / 小於等於$.input.stock lt 10
in左邊在右邊列表裡$.input.city in ["北京", "上海"]
contains左邊包含右邊$.input.tags contains "VIP"
exists欄位存在且不為空$.input.coupon exists

如果參照的欄位不存在，exists 會判定為「否」，其他運算子也會判定為「否」。

節點間傳值

在條件或動作的設定中，任何以 $. 開頭的值都會替換為執行時資料：

$.input.amount          运行时传入数据的 amount 字段
$.query.data.0.name     节点 query 输出中 data 列表第 1 项的 name
$.notify.status         节点 notify 输出的 status

當欄位的完整值恰好是一個參照時，會保留原本的型別（數字、清單和物件都支援）。若要將資料插入文字中間，請使用 {{$.path}}：

大额订单 {{$.input.order_id}}：金额 {{$.input.amount}}，请风控复核
  • 字串會原樣插入；數字、清單和物件會轉換為 JSON；空值會以空字串插入。
  • 如果路徑不存在，會替換為空內容（完整值參照也會變成空值）；這不會使節點失敗，但會在執行記錄的對應步驟中標記。
  • 只有以 $. 開頭的值會被視為參照，例如「$100 優惠」只是一般文字。
  • Email 主旨和內文也支援 {{variable}} 範本，變數取自上游節點的輸出。

連接器指南

說明各連接器的地址和憑證來源、官方文件以及常見錯誤的處理方式。應用程式連接器表單上方的「在哪裡取得？」面板是本指南的簡版。

HTTP

設定步驟

  1. 準備好介面地址（url）和請求方法（GET、POST 等）。
  2. 介面需要驗證時，在 auth_type 選擇 basic 或 bearer，再填入帳號密碼或 Token；不要將金鑰直接寫進 headers，否則會以明文儲存。

官方文件 ↗

必填
url
選填
method（預設 GET）、headers、body、query_params、auth_type（none / basic / bearer）、timeout、retries

body 為空時，發送上游節點的輸出。只能存取公開網路地址。

常見錯誤

  • 報「not a public address」：目標是內部網路或本機地址（包括跳轉後落到內部網路的情況），出於安全被攔截。
  • 只支援 http 和 https 地址。
  • body 留空時，發送的是上游節點的輸出。
  • 超時預設 30 秒，最長 60 秒。

钉钉

設定步驟

  1. 打開釘釘群 → 群設定 → 智能群助手 → 新增機器人 → 自訂（通過 Webhook 接入）。
  2. 安全設定可選擇「加簽」或「自訂關鍵字」，也可以同時啟用。選擇「加簽」時，複製以 SEC 開頭的金鑰並填入 secret；選擇關鍵字時，填入訊息中一定會出現的詞。建議將 Opengency 加入關鍵字，因為「測試連線」傳送的訊息內容是「Opengency 连接测试」。
  3. 複製生成的 Webhook 地址，填到 webhook_url。

官方文件 ↗

必填
webhook_url
選填
secret（加簽金鑰）、msg_type（text / markdown / link / card）、message、at_mobiles、at_all

webhook_url 可在釘釘群組的「設定 → 智慧群組助理 → 新增機器人」中取得。「測試連線」會實際傳送一則訊息到群組，訊息內容固定為「Opengency 连接测试」。如果機器人啟用了自訂關鍵字，請將 Opengency 納入關鍵字，否則測試訊息會遭拒；只啟用簽章則不受影響。

常見錯誤

  • 提示簽名不相符（sign not match）：機器人選了“加簽”，但 secret 沒填或填錯了。要填以 SEC 開頭的那串加簽金鑰，不是 Webhook 地址裡的 access_token。
  • 提示關鍵字不相符：訊息內容裡沒有機器人設定的關鍵字。把關鍵字寫進訊息，或者在機器人設定裡補一個訊息裡會出現的詞。
  • 提示時間戳無效（timestamp）：執行 Opengency 的伺服器時鐘和釘釘相差超過 1 小時，請校準伺服器時間。
  • 「測試連線」會實際傳送一則「Opengency 连接测试」訊息到群組。

企业微信

設定步驟

  1. 打開企業微信群 → 右上角“…” → 群機器人 → 新增機器人。
  2. 機器人建立後會直接顯示 Webhook 地址。
  3. 複製這個地址，填到 webhook_url。

官方文件 ↗

必填
webhook_url
選填
msg_type（text / markdown / card）、message、at_mobiles、at_all、url 與 title（card 用）

webhook_url 在企業微信群 → 群機器人裡取得，URL 裡的 key 就是憑據。@ 只對 text 生效。「測試連線」會真的往群裡發一條測試訊息。

常見錯誤

  • Webhook 地址裡的 key 就是憑據，拿到地址的人都能往群裡發訊息。洩露了就在群裡移除這個機器人，重新新增一個。
  • @ 成員只對 text 類型生效；card 類型必須同時填 url（點擊卡片跳轉的地址），否則儲存時會報錯。
  • 發送太頻繁會被企業微信限流，訊息發不出去；定時任務不要排得太密。
  • 「測試連線」會真的往群裡發一條測試訊息。

飞书

設定步驟

  1. 打開飛書群 → 設定 → 群機器人 → 新增機器人 → 自訂機器人。
  2. 安全設定可以開啟“簽名校驗”，把頁面上的金鑰填到 secret；也可以用“自訂關鍵字”，同樣建議把 Opengency 加成關鍵字。
  3. 複製生成的 Webhook 地址，填到 webhook_url。

官方文件 ↗

必填
webhook_url
選填
secret（機器人開啟簽名校驗時填）、msg_type（text / post / markdown / card）、message、title、at_open_ids、at_all

webhook_url 在飛書群設定 → 群機器人 → 自訂機器人裡取得。「測試連線」會真的往群裡發一條測試訊息。

常見錯誤

  • 開啟了簽名校驗，但 secret 沒填或填錯：飛書會拒絕訊息（提示簽名校驗失敗）。金鑰可以在機器人設定頁重新查看。
  • 設定了自訂關鍵字，但訊息裡沒有這個詞：訊息會被拒絕。
  • at_open_ids 要填 ou_ 開頭的 open_id，不是手機號，也不是姓名。
  • 「測試連線」會真的往群裡發一條測試訊息。

Slack

設定步驟

  1. 打開 https://api.slack.com/apps，建立一個 App（或選已有的），在 Features 裡打開 Incoming Webhooks 開關。
  2. 點 Add New Webhook to Workspace，選擇要發訊息的頻道並授權。
  3. 複製生成的 Webhook URL（以 https://hooks.slack.com/services/ 開頭），填到 webhook_url。

官方文件 ↗

必填
webhook_url
選填
message、username、icon_emoji、channel

webhook_url 本身就是憑據（誰拿到都能往該頻道發訊息），Opengency 加密儲存，在介面和記錄裡脫敏。新版 Slack App 的 Webhook 固定發到建立時選的頻道，username、icon_emoji、channel 會被忽略；想發到別的頻道，就再建立一個 Webhook。「測試連線」會真的往頻道發一條測試訊息。

常見錯誤

  • 提示 no_service：Webhook 被刪除、停用或地址不對。回到 Slack App 的 Incoming Webhooks 頁面確認它還在，必要時重新建立並更新連接。
  • 提示 channel_not_found：頻道不存在，或這個 Webhook 沒有權限。確認頻道名，或重新建立 Webhook 選對頻道。
  • 提示 channel_is_archived：頻道已歸檔。先取消歸檔，或換一個頻道的 Webhook。
  • 提示 action_prohibited：工作區管理員限制了這個 Webhook 發訊息，請聯繫 Slack 管理員。
  • 提示 invalid_payload 或 no_text：訊息內容為空或格式不對，檢查 message 不為空。
  • HTTP 429：發得太頻繁被 Slack 限流，稍後再試；不要把定時間隔設得太密。
  • 「測試連線」會實際傳送一則「Opengency connection test」訊息到頻道。

Teams

設定步驟

  1. 在 Teams 裡打開要發訊息的頻道 → 頻道名旁的「…」→ 工作流程（Workflows）。
  2. 選「Send webhook alerts to a channel」範本（發送 webhook 警報到頻道），依提示選好團隊和頻道，再點選儲存。
  3. 建立完成後在流程詳情頁複製 webhook 地址，填到 webhook_url。

官方文件 ↗

必填
webhook_url
選填
message、title

webhook_url 本身就是憑據（地址裡的 sig 是流程的簽名），Opengency 加密儲存，在介面和記錄裡脫敏。只支援 Workflows（Power Automate）的 webhook；舊的 Office 365 連接器 webhook（outlook.office.com/webhook/…）微軟正在下線，不支援。訊息以 Adaptive Card 發送：title 顯示為卡片頂部的加粗標題，message 是正文（支援基礎 Markdown）。單條訊息不能超過 28 KB，過長的正文會被截斷。「測試連線」會真的往頻道發一條測試訊息。

常見錯誤

  • HTTP 401 / 403（地址無效或已被撤銷）：webhook 地址裡的簽名不對，或被重新生成過。回到 Teams 裡打開這個流程，複製最新的地址並更新連接。
  • HTTP 404（找不到流程）：流程可能已刪除。請用範本重新建立流程，並更新連線中的地址。
  • 提示流程被關閉（disabled / turned off）：到 Teams 的工作流程應用或 Power Automate 裡把它重新打開。流程是跟著建立者走的，建立者離職或失效後流程可能被停用，請讓管理員把它交給其他人。
  • HTTP 400（觸發器未接受訊息）：確認流程是以「Send webhook alerts to a channel」範本建立，觸發器為 When a Teams webhook request is received，且未更改其接收的訊息格式。
  • HTTP 429：Teams 對 webhook 限流（大致每秒 4 次以內），發得太頻繁會被拒絕。稍後再試，不要把定時間隔設得太密。
  • 「測試連線」會實際傳送一則「Opengency connection test」訊息到頻道。

Email

設定步驟

  1. 在信箱服務商的設定裡開啟 SMTP 服務。
  2. 生成“授權碼”（有的服務商叫“應用專用密碼”）。QQ、163、Gmail、Outlook 等大多數信箱都不允許第三方應用用登入密碼發信。
  3. 記下 SMTP 伺服器地址和連接埠，例如 QQ 信箱是 smtp.qq.com:465，Gmail 是 smtp.gmail.com:587。
  4. sender_email 填你的信箱地址，sender_password 填第 2 步生成的授權碼。

官方文件 ↗

必填
smtp_server、sender_email、sender_password、to
選填
smtp_port（預設 587）、smtp_ssl（auto / implicit / starttls / none）、use_tls、cc、bcc、subject、body、format（text / html / markdown）

subject 和 body 支援 {{variables}}，變數取自上游節點的輸出。QQ / 163 信箱請填入授權碼，而非登入密碼。

常見錯誤

  • 認證失敗：sender_password 填的是登入密碼。換成授權碼或應用專用密碼。
  • 連線逾時或握手失敗：連接埠和加密方式不相符。465 連接埠用隱式 TLS，587 連接埠用 STARTTLS；smtp_ssl 保持 auto 時會按連接埠自動選，一般不用改。
  • 報「not a public address」：SMTP 伺服器地址指向內部網路或本機（公司內部郵件伺服器常見），出於安全被攔截。需要換成公開網路可存取的 SMTP 伺服器。
  • to 至少要有一個收件人；多個收件人用逗號分隔。

SQLite

設定步驟

  1. 不需要帳號或密碼：資料庫檔案儲存在你自己的資料目錄裡。
  2. database_path 只填檔案名，例如 orders.db；檔案不存在時會自動建立。

官方文件 ↗

必填
database_path、sql
選填
params、operation（select / insert / update / delete / execute）、return_type（預設 dict）、timeout

database_path 只填檔案名（如 orders.db），檔案自動存放在你的專屬資料目錄裡。SQL 用 ? 佔位，值放 params。

常見錯誤

  • 提示 no such table：檔案名拼錯時不會報“找不到檔案”，而是新建一個空資料庫，所以查不到表。先核對檔案名。
  • database_path 只是檔案名。資料庫只在你自己的資料目錄裡，存取不到其它位置的檔案。
  • 參數用 ? 佔位，值放進 params。

MySQL

設定步驟

  1. 準備好主機地址、連接埠（預設 3306）、使用者名、密碼和資料庫名。
  2. 為這個連接單獨建一個資料庫帳號；只做查詢的話，只給 SELECT 權限。
  3. 確認資料庫能從公開網路存取：防火牆或雲廠商的安全組要放行對應連接埠。

官方文件 ↗

必填
host、user、password、database、sql
選填
port（預設 3306）、ssl（disabled / required / verify）、params、read_only（預設開啟）、max_rows（預設 1000）、timeout

SQL 使用 %s 作為佔位符，值放在 params（有 params 時，字面上的 % 要寫成 %%）。預設為唯讀；如需寫入，請關閉 read_only。唯讀節點建議使用只有 SELECT 權限的帳號。每次只執行一條語句，且只能連線至公開網路地址。

常見錯誤

  • 報「not a public address」：host 是內部網路地址（10.x、172.16–31.x、192.168.x、127.0.0.1）。連接器只能連公開網路地址，需要給資料庫配一個公開網路存取入口。
  • 寫入被拒絕：read_only 預設開啟，SQL 在唯讀事務裡執行。確實要寫入時關閉 read_only，並確認帳號有寫權限。
  • 查詢結果不全：預設最多返回 1000 行（max_rows，最大 10000），超出的會被截斷並標記 truncated。
  • 一次只能執行一條 SQL；參數用 %s 佔位、值放進 params，不要把值拼進 SQL。
  • 連線逾時：多半是防火牆或安全組沒有放行連接埠。

Webhook

設定步驟

  1. 準備一個能接收 POST 請求的公開網路地址，填到 webhook_url。
  2. 需要讓接收方確認請求來自你的工作流程時，約定一個金鑰，填到 secret_key。
  3. 接收方校驗：每個請求都帶 X-Webhook-Timestamp；填了 secret_key 時還帶 X-Webhook-Signature，值是用這個金鑰對(timestamp + "." + raw_body)做 HMAC-SHA256 得到的十六進制串。
必填
webhook_url
選填
secret_key、verify_signature、event_types、retry_count、timeout

填了 secret_key 時，請求頭帶 X-Webhook-Signature（HMAC-SHA256），接收方可據此驗簽。

常見錯誤

  • 「測試連線」會真的向接收方發一條 event_type 為 ping 的事件。
  • 接收方返回 4xx 或 500、或者超時，不會重發（接收方可能已經處理過）；只有 429、502、503、504 和連接沒建立起來時才會重試。
  • 報「not a public address」：接收地址是內部網路或本機地址。
  • event_types 留空表示全部轉發；填了之後，event_type 不在列表裡的資料會被跳過。

安全限制：HTTP、DingTalk、WeCom、Feishu、Slack、Teams、Email、MySQL 和 Webhook 只能連線至公開地址（127.0.0.1、10.x、192.168.x 等內部網路地址會被拒絕）；SQLite 只能存取你自己的資料目錄。

API Key

供腳本和其他系統呼叫 API，例如由排程腳本觸發工作流程。請在應用程式的「帳戶 → API 金鑰」中建立金鑰；完整金鑰只會顯示一次，請立即儲存，之後清單只會顯示前幾個字元供識別。限制：Free 1 個、Pro 5 個、Business 和 Enterprise 無限制（只計算尚未撤銷的金鑰）。

curl -X POST https://app.opengency.ai/api/executions/workflows/<工作流 ID>/execute \
  -H "Authorization: Bearer ofk_…" \
  -H "Content-Type: application/json" \
  -d '{"input_data": {"order_id": 7}}'
  • 權限與建立它的帳號相同；用它觸發的執行會在執行紀錄中標為「API」，並顯示 Key 的前幾個字元。
  • 管理 API Key、修改密碼和註銷帳號都必須以帳號密碼登入；API Key 無法執行這些操作。
  • 撤銷後立即失效（傳回 401）。修改密碼不會使現有的 Key 失效；若懷疑金鑰外洩，請逐一撤銷。
  • 請只將金鑰儲存在伺服器端，不要寫進網頁前端程式碼，也不要傳到群組。

常見問題

為什麼我的 HTTP 節點報「not a public address」？
目標是內部網路或本機地址，出於安全被攔截。請使用公開網路可存取的地址。
工作流程執行失敗時能通知我嗎？
可以，所有方案都支援。在「帳戶 → 失敗通知」中，選擇寄送至帳戶信箱，或傳送至已儲存的釘釘、企業微信、飛書或電子郵件連線。約 10 分鐘內的多次失敗會合併成一則訊息，附上各工作流程的失敗次數、出錯節點與詳細資訊連結；手動取消的執行不會發送通知。
能做循環嗎？
暫不支援。工作流程不能成環，儲存時會提示。
可以定時自動執行嗎？
可以。在編輯器中將觸發器改為「定時」，選擇頻率（每 N 分鐘、每小時、每天、每週），或直接輸入 cron，並選擇時區；儲存後，在工作流程詳細資訊頁開啟「啟用」開關。Free 版可同時啟用 1 個定時工作流程，Pro 版可啟用 10 個。