文档 · Opengency

快速开始

注册并登录 Web 版。
新建工作流，画布上已有一个「触发」节点，它是流程的起点。
拖出一个「动作」节点，选择连接器（比如钉钉），填好配置。
从触发节点连线到动作节点，保存。
点击运行，输入测试数据，在执行记录里查看每个节点的结果。

工作流编辑指南

工作流由三种节点组成：

触发：起点，每个工作流有且只有一个。运行时传入的数据就是它的输出。
条件：做一次判断，出边分为「是」和「否」两条，只走匹配的那条。
动作：调用一个连接器，比如发钉钉、发邮件、调接口。

保存时会检查：只有一个触发节点、连线两端都存在、没有形成环、条件的出边标了是/否、每个动作的必填项都已填写。有问题会逐条列出。

运行时从触发节点开始按连线往下走；任何一个节点失败，整次运行立即停止并标记为失败。

条件判断

条件由「左值、运算符、右值」三部分组成，左右两边可以填固定值，也可以填引用（见下一节）。

运算符	含义	示例
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 优惠」是普通文字。
邮件的主题和正文另外支持 {{variable}} 模板，变量取自上游节点的输出。

连接器指南

每个连接器要填的地址和账号从哪里来、官方文档在哪、常见报错怎么处理。应用里连接器表单上方的「怎么获取这些信息？」是这份指南的简版。

HTTP

配置步骤

准备好接口地址（url）和请求方法（GET、POST 等）。
接口需要认证时，在 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 秒。

钉钉

配置步骤

打开钉钉群 → 群设置 → 智能群助手 → 添加机器人 → 自定义（通过 Webhook 接入）。
安全设置选“加签”或“自定义关键词”都可以（也可以两个都开）。选“加签”时，复制以 SEC 开头的密钥，填到 secret；选关键词时，填一个消息里一定会出现的词，并建议把 Opengency 也加成关键词，因为「测试连接」发送的内容是“Opengency 连接测试”。
复制生成的 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 连接测试”。

企业微信

配置步骤

打开企业微信群 → 右上角“…” → 群机器人 → 添加机器人。
机器人创建后会直接显示 Webhook 地址。
复制这个地址，填到 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（点击卡片跳转的地址），否则保存时会报错。
发送太频繁会被企业微信限流，消息发不出去；定时任务不要排得太密。
「测试连接」会真的往群里发一条测试消息。

飞书

配置步骤

打开飞书群 → 设置 → 群机器人 → 添加机器人 → 自定义机器人。
安全设置可以开启“签名校验”，把页面上的密钥填到 secret；也可以用“自定义关键词”，同样建议把 Opengency 加成关键词。
复制生成的 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

配置步骤

打开 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 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

配置步骤

在 Teams 里打开要发消息的频道 → 频道名旁的「…」→ 工作流（Workflows）。
选「Send webhook alerts to a channel」模板（发送 webhook 警报到频道），按提示选好团队和频道，点保存。
创建完成后在流程详情页复制 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

配置步骤

在邮箱服务商的设置里开启 SMTP 服务。
生成“授权码”（有的服务商叫“应用专用密码”）。QQ、163、Gmail、Outlook 等大多数邮箱都不允许第三方应用用登录密码发信。
记下 SMTP 服务器地址和端口，例如 QQ 邮箱是 smtp.qq.com:465，Gmail 是 smtp.gmail.com:587。
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

配置步骤

不需要账号或密码：数据库文件保存在你自己的数据目录里。
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 权限的账号。一次只执行一条语句，只能连接公网地址。

常见错误

报「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

配置步骤

准备一个能接收 POST 请求的公网地址，填到 webhook_url。
需要让接收方确认请求来自你的工作流时，约定一个密钥，填到 secret_key。
接收方校验：每个请求都带 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、钉钉、企业微信、飞书、Slack、Teams、邮件、MySQL、Webhook 只能连接公网地址（127.0.0.1、10.x、192.168.x 等内网地址会被拒绝）；SQLite 只能访问你自己的数据目录。

API Key

给脚本和其他系统调用接口用，例如用定时脚本触发工作流。在应用的「账户 → API Key」里新建，完整的 Key 只显示一次，请立即保存；之后列表里只显示开头几位，用来辨认。数量上限：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，并选择时区；保存后在工作流详情页打开「启用」开关。免费版可同时启用 1 个定时工作流，Pro 版 10 个。