문서 · Opengency

빠른 시작

웹 앱에 가입하고 로그인하세요.
새 워크플로를 만드세요. 캔버스에는 시작점인 "Trigger" 노드가 이미 있습니다.
"Action" 노드를 끌어 놓고 커넥터(예: Email)를 선택한 뒤 설정을 입력하세요.
트리거 노드와 작업 노드를 연결하고 저장하세요.
Run을 클릭하고 테스트 데이터를 입력한 다음 실행 로그에서 각 노드의 결과를 확인하세요.

워크플로 편집 가이드

워크플로는 세 종류의 노드로 구성됩니다:

트리거: 시작점입니다. 모든 워크플로에는 정확히 하나가 있으며, 실행 중 들어온 데이터가 출력이 됩니다.
조건: Yes와 No 출력으로 하나의 결정을 내립니다. 일치하는 분기만 실행됩니다.
작업: 커넥터를 호출합니다. 예를 들어 이메일을 보내거나 API를 호출하거나 데이터베이스에 기록합니다.

저장할 때 트리거 노드가 정확히 하나인지, 모든 연결의 양쪽 끝이 연결되었는지, 순환이 없는지, 조건 출력에 Yes/No 라벨이 있는지, 각 작업의 필수 항목이 입력되었는지 확인합니다. 문제는 하나씩 표시됩니다.

실행 시 트리거 노드부터 연결을 따라 진행합니다. 어느 노드라도 실패하면 전체 실행이 즉시 중단되고 실패로 표시됩니다.

조건

조건에는 왼쪽 값, 연산자, 오른쪽 값이 있습니다. 각 값은 고정값이거나 참조값일 수 있습니다(다음 절 참조).

연산자	의미	예시
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는 No가 되고, 다른 모든 연산자도 No가 됩니다.

노드 간 값 전달

조건이나 작업 설정에서 $.로 시작하는 값은 실행 중 데이터로 대체됩니다:

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

필드 전체 값이 하나의 참조와 정확히 같으면 원래 형식(숫자, 목록, 객체)이 유지됩니다. 텍스트 중간에 데이터를 넣으려면 {{$.path}}를 사용하세요:

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

문자열은 그대로 삽입되고, 숫자·목록·객체는 JSON으로 변환되며, 빈 값은 빈 문자열로 삽입됩니다.
경로가 없으면 아무 내용도 삽입되지 않습니다. 전체 값 참조도 비어 있게 되지만 노드가 실패하지는 않고 실행 로그의 해당 단계에 표시됩니다.
$.로 시작하는 값만 참조로 처리됩니다. 예를 들어 "$100 off"는 일반 텍스트입니다.
이메일 제목과 본문은 {{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가 비어 있으면 앞 단계 노드의 출력이 전송됩니다.
timeout의 기본값은 30초이며 최대 60초까지 설정할 수 있습니다.

DingTalk

설정 단계

DingTalk 그룹 → 그룹 설정 → 그룹 어시스턴트 → 로봇 추가 → 사용자 지정(Webhook 사용)을 여세요.
보안을 위해 서명(Sign) 또는 사용자 지정 키워드(Custom keywords)를 선택하세요(둘 다 사용 가능). 서명을 사용하면 SEC로 시작하는 비밀 키를 secret에 복사하세요. 키워드를 사용하면 메시지에 항상 들어갈 단어를 등록하고 Opengency도 키워드로 추가하세요. "Test connection"은 "Opengency 连接测试"라는 문구를 전송합니다.
생성된 웹훅 URL을 webhook_url에 복사하세요.

공식 문서 ↗

필수 항목: webhook_url
선택 사항: secret(서명용 비밀 키), msg_type(text / markdown / link / card), message, at_mobiles, at_all

DingTalk 그룹 설정 → 그룹 어시스턴트 → 봇 추가에서 webhook_url을 얻으세요. "Test connection"은 실제로 그룹에 테스트 메시지를 보냅니다. 메시지 내용은 "Opengency 连接测试"로 고정되어 있습니다. 봇이 사용자 지정 키워드를 사용한다면 "Opengency"를 반드시 포함해야 합니다. 그렇지 않으면 키워드 불일치로 테스트가 거부됩니다(서명만 사용하는 경우에는 해당하지 않음).

자주 발생하는 오류

서명 불일치(sign not match): 봇이 서명을 사용하지만 secret이 비어 있거나 잘못되었습니다. 웹훅 URL의 access_token이 아니라 SEC로 시작하는 서명용 비밀 키를 입력하세요.
키워드 불일치: 메시지에 봇의 키워드가 하나도 없습니다. 메시지에 키워드를 넣거나, 메시지에 포함될 단어를 봇의 키워드로 추가하세요.
타임스탬프가 유효하지 않음: Opengency 서버와 DingTalk의 시각이 한 시간 넘게 차이 납니다. 서버 시각을 수정하세요.
"Test connection"은 전송 없이 확인만 하는 기능이 아닙니다. 실제로 그룹에 "Opengency 连接测试"를 게시합니다.

WeCom

설정 단계

WeCom 그룹 → 오른쪽 위 "…" → 그룹 로봇 → 로봇 추가를 여세요.
로봇을 만들면 웹훅 URL이 바로 표시됩니다.
해당 URL을 webhook_url에 복사하세요.

공식 문서 ↗

필수 항목: webhook_url
선택 사항: msg_type(text / markdown / card), message, at_mobiles, at_all, url 및 title(card용)

WeCom 그룹 → 그룹 봇에서 webhook_url을 얻으세요. URL에 포함된 key가 자격 증명입니다. @ 멘션은 text에서만 작동합니다. "Test connection"은 실제로 그룹에 테스트 메시지를 보냅니다.

자주 발생하는 오류

웹훅 URL의 key는 자격 증명입니다. URL을 아는 사람은 누구나 그룹에 게시할 수 있습니다. 유출되었다면 그룹에서 로봇을 삭제하고 새로 추가하세요.
@ 멘션은 text 유형에서만 작동합니다. card 유형에는 카드가 연결될 주소인 url도 필요하며, 없으면 저장할 수 없습니다.
WeCom은 너무 자주 게시하는 로봇을 속도 제한하므로 메시지가 전달되지 않을 수 있습니다. 실행 간격을 너무 짧게 설정하지 마세요.
"Test connection"은 실제로 그룹에 테스트 메시지를 게시합니다.

Feishu

설정 단계

Feishu 그룹 → 설정 → 그룹 봇 → 봇 추가 → 사용자 지정 봇을 여세요.
보안을 위해 서명 검증을 켜고 해당 페이지에 표시된 비밀 키를 secret에 입력할 수 있습니다. 사용자 지정 키워드도 사용할 수 있으며, 이 경우 Opengency도 키워드로 추가하세요.
생성된 웹훅 URL을 webhook_url에 복사하세요.

공식 문서 ↗

필수 항목: webhook_url
선택 사항: secret(봇에서 서명 검증을 사용한 경우), msg_type(text / post / markdown / card), message, title, at_open_ids, at_all

Feishu 그룹 설정 → 그룹 봇 → 사용자 지정 봇에서 webhook_url을 얻으세요. "Test connection"은 실제로 그룹에 테스트 메시지를 보냅니다.

자주 발생하는 오류

서명 검증이 켜져 있는데 secret이 비어 있거나 잘못된 경우 Feishu가 메시지를 거부합니다(signature check failed). 비밀 키는 봇 설정에서 다시 확인할 수 있습니다.
사용자 지정 키워드를 설정했지만 메시지에 해당 키워드가 없으면 메시지가 거부됩니다.
at_open_ids에는 전화번호나 이름이 아니라 ou_로 시작하는 open_id를 입력해야 합니다.
"Test connection"은 실제로 그룹에 테스트 메시지를 게시합니다.

Slack

설정 단계

https://api.slack.com/apps를 열어 앱을 만들거나 기존 앱을 선택한 다음, Features에서 Incoming Webhooks를 켜세요.
Add New Webhook to Workspace를 클릭하고 메시지를 게시할 채널을 선택한 뒤 승인하세요.
생성된 웹훅 URL(https://hooks.slack.com/services/로 시작)을 webhook_url에 복사하세요.

공식 문서 ↗

필수 항목: webhook_url
선택 사항: message, username, icon_emoji, channel

webhook_url 자체가 자격 증명이며 URL을 아는 사람은 누구나 해당 채널에 게시할 수 있습니다. Opengency는 이를 암호화해 저장하고 UI와 로그에서 가립니다. 현재 Slack 앱의 웹훅은 생성할 때 선택한 채널에만 게시하므로 username, icon_emoji, channel 설정은 무시됩니다. 다른 채널에 게시하려면 새 웹훅을 만드세요. "Test connection"은 실제로 채널에 테스트 메시지를 게시합니다.

자주 발생하는 오류

no_service: 웹훅이 삭제되거나 비활성화되었거나 주소가 잘못되었습니다. 앱의 Incoming Webhooks 페이지를 확인하고, 필요하면 웹훅을 다시 만들어 연결 정보를 갱신하세요.
channel_not_found: 채널이 없거나 이 웹훅에서 접근할 수 없습니다. 채널 이름을 확인하거나 올바른 채널용 웹훅을 다시 만드세요.
channel_is_archived: 채널이 보관 처리되었습니다. 보관을 해제하거나 다른 채널의 웹훅을 사용하세요.
action_prohibited: 워크스페이스 관리자가 이 웹훅의 작업을 제한했습니다. Slack 관리자에게 문의하세요.
invalid_payload 또는 no_text: 메시지가 비어 있거나 형식이 잘못되었습니다. message가 비어 있지 않은지 확인하세요.
HTTP 429: 게시 빈도가 높아 Slack에서 속도를 제한했습니다. 나중에 다시 시도하고 실행 간격을 너무 짧게 설정하지 마세요.
"Test connection"은 전송 없이 확인만 하는 기능이 아닙니다. 실제로 채널에 "Opengency connection test"를 게시합니다.

Teams

설정 단계

Teams에서 메시지를 게시할 채널을 열고 채널 이름 옆의 "…" → Workflows를 선택하세요.
"Send webhook alerts to a channel" 템플릿을 선택하고 안내에 따라 팀과 채널을 지정한 뒤 저장하세요.
생성 후 흐름 세부 정보 페이지에서 웹훅 URL을 복사해 webhook_url에 입력하세요.

공식 문서 ↗

필수 항목: webhook_url
선택 사항: message, title

webhook_url 자체가 자격 증명이며 URL의 sig는 흐름의 서명입니다. Opengency는 이를 암호화해 저장하고 UI와 로그에서 가립니다. Workflows(Power Automate) 웹훅만 지원합니다. Microsoft가 단계적으로 종료 중인 기존 Office 365 커넥터 웹훅(outlook.office.com/webhook/…)은 지원하지 않습니다. 메시지는 Adaptive Card로 전송됩니다. title은 카드 상단의 굵은 제목이고 message는 본문이며 기본 Markdown을 사용할 수 있습니다. 메시지가 28 KB를 넘으면 긴 본문은 잘립니다. "Test connection"은 실제로 채널에 테스트 메시지를 게시합니다.

자주 발생하는 오류

HTTP 401 / 403(주소가 유효하지 않거나 취소됨): 웹훅 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는 웹훅 요청을 초당 약 4건으로 제한하며, 너무 자주 게시하면 거부합니다. 나중에 다시 시도하고 실행 간격을 너무 짧게 설정하지 마세요.
"Test connection"은 전송 없이 확인만 하는 기능이 아닙니다. 실제로 채널에 "Opengency connection test"를 게시합니다.

Email

설정 단계

메일 서비스 제공업체 설정에서 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번 포트는 implicit 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 권한만 있는 계정을 사용하세요. 한 번에 SQL 문 하나만 실행할 수 있으며 공개 주소에만 연결할 수 있습니다.

자주 발생하는 오류

"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 요청을 받는 공개 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)가 포함되며, 수신 측에서 이를 사용해 요청을 검증할 수 있습니다.

자주 발생하는 오류

"Test connection"은 실제로 수신 측에 event_type이 ping인 이벤트를 보냅니다.
4xx 또는 500 응답이나 시간 초과는 재시도하지 않습니다(수신 측에서 이미 처리했을 수 있음). 429, 502, 503, 504 응답과 연결이 아예 수립되지 않은 경우에만 재시도합니다.
"not a public address": 수신 URL이 내부 또는 로컬 주소입니다.
event_types가 비어 있으면 모든 데이터를 전달합니다. 항목을 추가하면 목록에 없는 event_type의 데이터는 건너뜁니다.

보안 제한: HTTP, DingTalk, WeCom, Feishu, Slack, Teams, Email, MySQL 및 Webhook은 공개 주소에만 연결할 수 있습니다(127.0.0.1, 10.x, 192.168.x 같은 내부 주소는 차단됩니다). SQLite는 사용자 자신의 데이터 디렉터리에만 접근할 수 있습니다.

API 키

스크립트나 다른 시스템에서 API를 호출할 때 사용합니다(예: 예약 스크립트로 워크플로 실행). 앱의 Account → API Keys에서 키를 만드세요. 전체 키는 한 번만 표시되므로 즉시 저장해야 하며, 이후 목록에는 식별용 앞부분만 표시됩니다. 한도: 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"로 표시되며 키의 앞부분 몇 글자도 함께 표시됩니다.
API 키 관리, 비밀번호 변경, 계정 삭제에는 모두 계정 비밀번호로 로그인해야 합니다. API 키로는 이러한 작업을 할 수 없습니다.
키를 취소하면 즉시 적용되어 401을 반환합니다. 비밀번호를 변경해도 기존 키는 무효화되지 않으므로 유출이 의심되면 각 키를 개별적으로 취소하세요.
키는 서버 측에만 보관하세요. 프런트엔드 웹 코드에 넣거나 채팅에서 공유하지 마세요.

자주 묻는 질문

HTTP 노드에 "not a public address"가 표시되는 이유는 무엇인가요?: 대상이 내부 또는 로컬 주소여서 보안상 차단되었습니다. 공개적으로 접근할 수 있는 주소를 사용하세요.
워크플로 실행이 실패하면 알림을 받을 수 있나요?: 네, 모든 요금제에서 가능합니다. 계정 → 실패 알림에서 계정 이메일이나 저장된 DingTalk, WeCom, Feishu 또는 이메일 연결로 보내도록 설정하세요. 약 10분 안에 여러 번 실패하면 하나의 메시지로 합쳐 각 워크플로의 실패 횟수, 오류가 난 노드, 세부 정보 링크를 보여 줍니다. 수동으로 취소한 실행은 알림을 보내지 않습니다.
워크플로에서 반복 실행할 수 있나요?: 아직 지원하지 않습니다. 워크플로는 순환 연결을 만들 수 없으며, 시도하면 저장 시 문제가 표시됩니다.
워크플로를 예약 실행할 수 있나요?: 네. 편집기에서 트리거를 「예약 실행」으로 변경하고 실행 주기(매 N분, 매시간, 매일, 매주)를 선택하거나 cron 표현식을 입력한 뒤 시간대를 지정하세요. 워크플로를 저장한 다음 상세 페이지에서 「활성화」 스위치를 켜세요. 동시에 활성화할 수 있는 예약 워크플로는 Free에서 1개, Pro에서 10개입니다.