ドキュメント · Opengency

クイックスタート

Web版に登録してログインします。
ワークフローを新規作成すると、キャンバスにはすでに「トリガー」ノードが1つ配置されています。これがフローの起点です。
「アクション」ノードをドラッグして追加し、コネクタ（例：メール）を選んで設定を入力します。
トリガーノードからアクションノードへ線をつなぎ、保存します。
「実行」をクリックしてテストデータを入力し、実行記録で各ノードの結果を確認します。

ワークフロー編集ガイド

ワークフローは3種類のノードで構成されます：

トリガー：起点。1つのワークフローに必ず1つだけ存在します。実行時に渡されたデータがそのまま出力になります。
条件：1回の判定を行い、出力は「はい」と「いいえ」の2つに分かれ、条件に一致した方だけが実行されます。
アクション：コネクタを呼び出します。たとえばメール送信、API呼び出し、データベースへの書き込みなどです。

保存時には次を検証します：トリガーノードが1つだけであること、すべての接続の両端が存在すること、循環がないこと、条件の出力に「はい／いいえ」のラベルが付いていること、各アクションの必須項目がすべて入力されていること。問題があれば1つずつ表示されます。

実行時はトリガーノードから接続をたどって進みます。いずれかのノードが失敗すると、その時点で実行全体が停止し失敗としてマークされます。

条件判定

条件は「左辺・演算子・右辺」の3つで構成され、左右にはそれぞれ固定値または参照（次のセクション参照）を指定できます。

演算子	意味	例
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

フィールドの値全体が1つの参照そのものである場合、置き換え後も元の型（数値、リスト、オブジェクトいずれも可）が保たれます。文章の途中にデータを挿し込むには {{$.path}} を使います：

大额订单 {{$.input.order_id}}：金额 {{$.input.amount}}，请风控复核

文字列はそのまま挿入され、数値・リスト・オブジェクトはJSONに変換され、値が空の場合は空として挿入されます。
パスが存在しない場合は空に置き換わります（値全体を参照している場合は空値になります）。ノードは失敗しませんが、実行記録の該当ステップにその旨が表示されます。
$.で始まるものだけが参照として扱われます。たとえば「$100引き」は単なる通常の文字列です。
メールの件名と本文は {{variable}} テンプレートにも対応しており、変数は上流ノードの出力から取得されます。

コネクタガイド

各コネクタで入力するアドレスやアカウント情報がどこから来るのか、公式ドキュメントの場所、よくあるエラーへの対処法をまとめています。アプリ内の各コネクタフォーム上部にある「この情報はどこで確認できますか？」は、このガイドの簡易版です。

HTTP

設定手順

エンドポイントのURL（url）とリクエストメソッド（GET、POSTなど）を用意してください。
APIに認証が必要な場合は、auth_typeでbasicまたはbearerを選び、ユーザー名とパスワード、またはトークンを入力してください。認証情報をheadersに直接書かないでください。平文で保存されてしまいます。

公式ドキュメント ↗

必須: url
任意: method（デフォルト GET）、headers、body、query_params、auth_type（none／basic／bearer）、timeout、retries

bodyが空の場合、上流ノードの出力を送信します。公開アドレスにのみ接続できます。

よくあるエラー

「not a public address」：接続先が内部アドレスまたはローカルアドレスです（リダイレクトの結果そうなる場合を含む）。安全のためブロックされています。
httpとhttpsのURLのみサポートされています。
bodyが空の場合、上流ノードの出力が送信されます。
タイムアウトはデフォルトで30秒、最大60秒です。

DingTalk

設定手順

DingTalkグループを開く → グループ設定 → グループアシスタント → ボットを追加 → カスタム（Webhook経由）。
セキュリティ設定は「署名」または「カスタムキーワード」を選びます（両方を有効にしても構いません）。「署名」の場合は、SEC で始まるシークレットを secret に貼り付けます。キーワードの場合は、メッセージに必ず含まれる単語を入力し、「接続をテスト」が送信するテキストが「Opengency 连接测试」なので、Opengency もキーワードに追加してください。
生成されたWebhook URLをwebhook_urlにコピーしてください。

公式ドキュメント ↗

必須: webhook_url
任意: secret（署名シークレット）、msg_type（text／markdown／link／card）、message、at_mobiles、at_all

webhook_urlはDingTalkグループの設定 →スマートグループアシスタント →ボットを追加から取得します。「接続をテスト」を実行すると、実際にグループへテストメッセージが送信されます。テストメッセージの本文は「Opengency 连接测试」に固定されています。ボットでカスタムキーワードを使っている場合は、その中に「Opengency」を含めてください。含まれていないと、キーワード不一致でテストが拒否されます（署名のみの場合は影響ありません）。

よくあるエラー

署名が一致しません（sign not match）：ボットは署名を使っていますが、secret が空か誤っています。Webhook URL の access_token ではなく、SEC で始まる署名シークレットを入力してください。
キーワード不一致：メッセージにボットのキーワードが含まれていません。メッセージにキーワードを入れるか、あなたのメッセージに含まれる単語をボットのキーワードとして追加してください。
タイムスタンプが無効です：Opengency を実行しているサーバーの時計が DingTalk と 1 時間以上ずれています。サーバーの時刻を修正してください。
「接続をテスト」はドライランではなく、実際に「Opengency 连接测试」をグループに送信します。

WeCom

設定手順

WeComグループを開く → 右上の「…」→ グループボット → ボットを追加。
ボット作成後すぐにWebhook URLが表示されます。
そのURLをwebhook_urlにコピーしてください。

公式ドキュメント ↗

必須: webhook_url
任意: msg_type（text／markdown／card）、message、at_mobiles、at_all、url と title（card用）

webhook_urlはWeComグループ →グループボットから取得します。URL内のkeyが認証情報です。@メンションはtextのみ有効です。「接続をテスト」を実行すると、実際にグループへテストメッセージが送信されます。

よくあるエラー

Webhook URL内のkeyが認証情報です。このURLを持つ人は誰でもグループに投稿できます。漏洩した場合はグループからボットを削除し、新しく追加してください。
@メンションはtext形式でのみ機能します。card形式にはurl（カードのリンク先）も必要で、これがないと保存に失敗します。
投稿が多すぎるとWeComによってレート制限され、メッセージが届かなくなります。実行のスケジュールを詰めすぎないようにしてください。
「接続をテスト」は実際にグループへテストメッセージを送信します。

Feishu

設定手順

Feishuグループを開く → 設定 → グループボット → ボットを追加 → カスタムボット。
セキュリティのため署名検証を有効にし、そのページに表示される鍵をsecretに入力できます。カスタムキーワードも使用可能で、そちらにも「Opengency」をキーワードとして追加してください。
生成されたWebhook URLをwebhook_urlにコピーしてください。

公式ドキュメント ↗

必須: webhook_url
任意: secret（ボットで署名検証を有効にしている場合に入力）、msg_type（text／post／markdown／card）、message、title、at_open_ids、at_all

webhook_urlはFeishuグループ設定 →グループボット →カスタムボットから取得します。「接続をテスト」を実行すると、実際にグループへテストメッセージが送信されます。

よくあるエラー

署名検証が有効ですが、secretが空または誤っています：Feishuがメッセージを拒否します（署名検証失敗）。鍵はボット設定で再確認できます。
カスタムキーワードが設定されていますが、メッセージにそのキーワードが含まれていません：メッセージが拒否されます。
at_open_idsにはou_で始まるopen_idを指定します。電話番号や氏名ではありません。
「接続をテスト」は実際にグループへテストメッセージを送信します。

Slack

設定手順

https://api.slack.com/apps を開き、Appを作成する（または既存のものを選ぶ）。Featuresの中でIncoming Webhooksを有効にする。
Add New Webhook to Workspaceをクリックし、投稿先のチャンネルを選んで承認する。
生成されたWebhook URL（https://hooks.slack.com/services/ で始まる）をwebhook_urlに入力する。

公式ドキュメント ↗

必須: webhook_url
任意: message、username、icon_emoji、channel

webhook_url自体が認証情報です（持っている人は誰でもそのチャンネルに投稿できます）。Opengencyは暗号化して保存し、画面やログではマスクします。現行のSlackアプリのWebhookは作成時に選んだチャンネルに固定して投稿するため、username、icon_emoji、channelは無視されます。別のチャンネルに投稿したい場合は、別のWebhookを作成してください。「接続をテスト」を実行すると、実際にチャンネルへテストメッセージが送信されます。

よくあるエラー

no_service：Webhookが削除・無効化されたか、アドレスが間違っています。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

設定手順

Teamsで投稿先のチャンネルを開く → チャンネル名の横の「…」→ Workflows。
「Send webhook alerts to a channel」テンプレートを選び、案内に従ってチームとチャンネルを選択し、保存する。
作成後、フローの詳細ページでWebhookアドレスをコピーしてwebhook_urlに入力する。

公式ドキュメント ↗

必須: webhook_url
任意: message、title

webhook_url自体が認証情報です（アドレス内のsigはフローの署名です）。Opengencyは暗号化して保存し、画面やログではマスクします。対応しているのはWorkflows（Power Automate）のWebhookのみです。古いOffice 365コネクタのWebhook（outlook.office.com/webhook/…）はMicrosoftが廃止を進めており、対応していません。メッセージはAdaptive Cardとして送信されます：titleはカード上部の太字の見出し、messageは本文です（基本的なMarkdownが使えます）。メッセージは28 KBを超えられず、長すぎる本文は切り詰められます。「接続をテスト」を実行すると、実際にチャンネルへテストメッセージが送信されます。

よくあるエラー

HTTP 401 / 403（アドレスが無効または取り消された）：Webhook URL内の署名が間違っているか、再生成されています。Teamsでこのフローを開き、最新のアドレスをコピーして接続を更新してください。
HTTP 404（フローが見つからない）：フローが削除された可能性があります。テンプレートからフローを作り直し、接続のアドレスを更新してください。
フローが無効／オフになっているというメッセージ：Teams Workflowsアプリまたは Power Automate で再度有効にしてください。フローは作成者に紐づいており、作成者が退職したりアカウントが無効化されたりするとフローが停止することがあります。管理者に依頼して、他の人に引き継いでもらってください。
HTTP 400（トリガーがメッセージを受け付けなかった）：フローが「Send webhook alerts to a channel」テンプレートから作成されていること、トリガーが When a Teams webhook request is received であること、受信するメッセージ形式を変更していないことを確認してください。
HTTP 429：TeamsはWebhookをレート制限しており（おおむね1秒あたり4回程度）、投稿頻度が高すぎると拒否されます。しばらくしてから再試行し、実行のスケジュールを詰めすぎないようにしてください。
「接続をテスト」はドライランではなく、実際に「Opengency connection test」をチャンネルに送信します。

メール

設定手順

メールプロバイダーの設定でSMTPを有効にしてください。
アプリパスワードを発行してください（プロバイダーによっては認証コードと呼ばれます）。Gmail、Outlook、Yahooなど、ほとんどのプロバイダーはログインパスワードでのサードパーティアプリからの送信を許可していません。
SMTPサーバーとポートを控えておいてください。例：smtp.gmail.com:587、smtp.qq.com:465。
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}} に対応しており、変数は上流ノードの出力から取得されます。ほとんどのプロバイダーではログインパスワードではなくアプリ専用パスワードが必要です。

よくあるエラー

認証に失敗：sender_passwordにログインパスワードが入力されています。アプリパスワードまたは認証コードを使用してください。
接続タイムアウトまたはハンドシェイク失敗：ポートと暗号化方式が一致していません。ポート465は暗黙的TLS、ポート587はSTARTTLSを使用します。smtp_ssl をautoのままにしておけばポートに応じて自動選択されるため、変更が必要になることはほとんどありません。
「not a public address」：SMTPサーバーが内部アドレスまたはローカルアドレスに解決されています（社内メールサーバーでよくあるケース）。安全のためブロックされています。パブリックインターネットから到達可能なSMTPサーバーを使用してください。
toには少なくとも1つの宛先が必要です。複数指定する場合はカンマで区切ってください。

SQLite

設定手順

アカウントやパスワードは不要です。データベースファイルは自分のデータディレクトリ内に置かれます。
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

設定手順

ホスト、ポート（デフォルト3306）、ユーザー名、パスワード、データベース名を用意してください。
この接続専用のデータベースアカウントを作成してください。クエリのみ実行する場合はSELECT権限のみ付与してください。
データベースがパブリックインターネットから到達可能であることを確認してください。ファイアウォールまたはクラウドプロバイダーのセキュリティグループでポートを許可する必要があります。

公式ドキュメント ↗

必須: 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権限のみのアカウントの利用を推奨します。一度に実行できるSQL文は1つのみで、接続先は公開アドレスに限られます。

よくあるエラー

「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文は一度に1つしか実行されません。プレースホルダーには%sを使い、値はparamsに入れてください。値をSQL文字列に直接組み込まないでください。
接続タイムアウト：多くの場合、ファイアウォールまたはセキュリティグループでポートが許可されていません。

Webhook

設定手順

POSTリクエストを受け付けられる公開URLを用意し、webhook_urlに入力してください。
受信側でリクエストがあなたのワークフローから送られたことを確認できるようにしたい場合は、鍵を取り決めてsecret_keyに入力してください。
受信側では：すべてのリクエストにX-Webhook-Timestampが付与されます。secret_keyを設定すると、その鍵で(timestamp + "." + raw_body)をHMAC-SHA256で計算した16進数の値であるX-Webhook-Signatureも付与されます。

必須: 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」：受信先URLが内部アドレスまたはローカルアドレスです。
event_typesを空にするとすべて転送されます。値を設定すると、そのevent_typeがリストにないデータはスキップされます。

セキュリティ制限：HTTP、DingTalk、WeCom、Feishu、Slack、Teams、メール、MySQL、Webhookは公開アドレスにのみ接続できます（127.0.0.1、10.x、192.168.xなどの内部アドレスは拒否されます）。SQLiteは自分専用のデータディレクトリ内にのみアクセスできます。

APIキー

スクリプトや他システムからAPIを呼び出すために使用します。たとえば、定期実行スクリプトからワークフローをトリガーする場合などです。アプリ内の「アカウント →APIキー」から新規作成できます。完全なキーは作成時に一度だけ表示されるため、必ずその場で保存してください。以降は識別用に先頭の数文字のみ表示されます。上限：Freeは1個、Proは5個、Businessおよびエンタープライズは無制限（失効していないキーのみ数えます）。

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キーで実行されたものは実行記録に「API」と表示され、キーの先頭の数文字も併せて表示されます。
APIキーの管理、パスワードの変更、アカウントの削除にはアカウントのパスワードでのログインが必要です。APIキーではこれらの操作はできません。
失効させると即時に無効になります（401が返されます）。パスワードを変更しても既存のキーは無効になりません。漏えいが疑われる場合は個別に失効させてください。
APIキーはサーバー側にのみ保存し、フロントエンドのコードに書き込んだり、チャットで共有したりしないでください。

よくある質問

HTTPノードで「not a public address」と表示されるのはなぜですか？: 接続先が社内アドレスまたはローカルアドレスであるため、安全のためブロックされています。公開されているアドレスをご利用ください。
ワークフローの実行が失敗したときに通知を受け取れますか？: はい、すべてのプランで利用できます。「アカウント →失敗通知」で、アカウントのメールアドレス宛て、または保存済みのDingTalk、WeCom、Feishu、メール接続宛てに送信するよう設定できます。約10分以内に発生した複数の失敗は1件のメッセージにまとめられ、各ワークフローの失敗回数、エラーが発生したノード、詳細へのリンクが記載されます。手動でキャンセルした実行は通知されません。
ループ処理はできますか？: 現時点では対応していません。ワークフローは循環を作ることができず、保存時にその旨が表示されます。
定期的に自動実行できますか？: はい。エディタでトリガーを「スケジュール」に変更し、頻度（N分ごと、1時間ごと、毎日、毎週）を選ぶか直接cron式を入力し、タイムゾーンを選択します。保存後、ワークフロー詳細ページで「有効化」スイッチをオンにしてください。Freeプランでは同時に1個、Proプランでは10個のスケジュールワークフローを有効化できます。