웹훅

Gateway는 외부 트리거를 위한 소규모 HTTP 웹훅 엔드포인트를 노출할 수 있습니다.

활성화

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    // 선택 사항: 명시적 `agentId` 라우팅을 이 허용 목록으로 제한합니다.
    // 생략하거나 "*"를 포함하면 모든 에이전트를 허용합니다.
    // []로 설정하면 모든 명시적 `agentId` 라우팅을 거부합니다.
    allowedAgentIds: ["hooks", "main"],
  },
}

참고:

hooks.enabled=true일 때 hooks.token은 필수입니다.
hooks.path의 기본값은 /hooks입니다.

인증

모든 요청에 훅 토큰이 포함되어야 합니다. 헤더를 권장합니다:

Authorization: Bearer <token> (권장)
x-openclaw-token: <token>
쿼리 문자열 토큰은 거부됩니다 (?token=...은 400을 반환).

엔드포인트

`POST /hooks/wake`

페이로드:

{ "text": "System line", "mode": "now" }

text 필수 (문자열): 이벤트에 대한 설명 (예: “New email received”).
mode 선택 사항 (now | next-heartbeat): 즉시 하트비트를 트리거할지 (기본값 now) 또는 다음 주기적 체크까지 대기할지.

효과:

메인 세션에 시스템 이벤트를 대기열에 추가합니다
mode=now이면 즉시 하트비트를 트리거합니다

`POST /hooks/agent`

페이로드:

{
  "message": "Run this",
  "name": "Email",
  "agentId": "hooks",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}

message 필수 (문자열): 에이전트가 처리할 프롬프트 또는 메시지.
name 선택 사항 (문자열): 훅의 사람이 읽을 수 있는 이름 (예: “GitHub”), 세션 요약의 접두사로 사용됩니다.
agentId 선택 사항 (문자열): 이 훅을 특정 에이전트로 라우팅합니다. 알 수 없는 ID는 기본 에이전트로 대체됩니다. 설정되면, 훅은 해석된 에이전트의 워크스페이스와 설정을 사용하여 실행됩니다.
sessionKey 선택 사항 (문자열): 에이전트의 세션을 식별하는 데 사용되는 키입니다. 기본적으로 hooks.allowRequestSessionKey=true가 아닌 한 이 필드는 거부됩니다.
wakeMode 선택 사항 (now | next-heartbeat): 즉시 하트비트를 트리거할지 (기본값 now) 또는 다음 주기적 체크까지 대기할지.
deliver 선택 사항 (불리언): true이면 에이전트의 응답이 메시징 채널로 전송됩니다. 기본값은 true입니다. 하트비트 확인만 포함된 응답은 자동으로 건너뛰어집니다.
channel 선택 사항 (문자열): 전달용 메시징 채널. last, whatsapp, telegram, discord, slack, mattermost (플러그인), signal, imessage, msteams 중 하나. 기본값은 last.
to 선택 사항 (문자열): 채널의 수신자 식별자 (예: WhatsApp/Signal의 전화번호, Telegram의 채팅 ID, Discord/Slack/Mattermost(플러그인)의 채널 ID, MS Teams의 대화 ID). 기본값은 메인 세션의 마지막 수신자.
model 선택 사항 (문자열): 모델 오버라이드 (예: anthropic/claude-3-5-sonnet 또는 별칭). 제한된 경우 허용된 모델 목록에 있어야 합니다.
thinking 선택 사항 (문자열): 사고 레벨 오버라이드 (예: low, medium, high).
timeoutSeconds 선택 사항 (숫자): 에이전트 실행의 최대 지속 시간(초).

효과:

격리 에이전트 턴을 실행합니다 (자체 세션 키)
항상 메인 세션에 요약을 게시합니다
wakeMode=now이면 즉시 하트비트를 트리거합니다

세션 키 정책 (호환성을 깨는 변경)

/hooks/agent 페이로드의 sessionKey 오버라이드는 기본적으로 비활성화되어 있습니다.

권장: 고정된 hooks.defaultSessionKey를 설정하고 요청 오버라이드는 비활성화 상태로 유지합니다.
선택 사항: 필요한 경우에만 요청 오버라이드를 허용하고, 접두사를 제한합니다.

권장 설정:

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
  },
}

호환성 설정 (레거시 동작):

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:"], // 강력 권장
  },
}

`POST /hooks/<name>` (매핑)

커스텀 훅 이름은 hooks.mappings를 통해 해석됩니다 (설정 참고). 매핑은 임의의 페이로드를 wake 또는 agent 액션으로 변환할 수 있으며, 선택적 템플릿이나 코드 변환을 포함합니다.

매핑 옵션 (요약):

hooks.presets: ["gmail"]은 내장 Gmail 매핑을 활성화합니다.
hooks.mappings로 설정에서 match, action, 템플릿을 정의합니다.
hooks.transformsDir + transform.module은 커스텀 로직용 JS/TS 모듈을 로드합니다.
- hooks.transformsDir (설정된 경우)는 OpenClaw 설정 디렉토리 아래의 변환 루트 내에 있어야 합니다 (일반적으로 ~/.openclaw/hooks/transforms).
- transform.module은 유효한 변환 디렉토리 내에서 해석되어야 합니다 (탐색/이스케이프 경로는 거부됨).
match.source를 사용하여 일반 수집 엔드포인트를 유지합니다 (페이로드 기반 라우팅).
TS 변환은 TS 로더(예: bun 또는 tsx)가 필요하거나, 런타임에 사전 컴파일된 .js가 필요합니다.
매핑에 deliver: true + channel/to를 설정하면 응답을 채팅 인터페이스로 라우팅합니다 (channel은 기본적으로 last이며 WhatsApp으로 대체됩니다).
agentId는 훅을 특정 에이전트로 라우팅합니다. 알 수 없는 ID는 기본 에이전트로 대체됩니다.
hooks.allowedAgentIds는 명시적 agentId 라우팅을 제한합니다. 생략하거나 *를 포함하면 모든 에이전트를 허용합니다. []로 설정하면 명시적 agentId 라우팅을 거부합니다.
hooks.defaultSessionKey는 명시적 키가 제공되지 않을 때 훅 에이전트 실행의 기본 세션을 설정합니다.
hooks.allowRequestSessionKey는 /hooks/agent 페이로드에서 sessionKey를 설정할 수 있는지 제어합니다 (기본값: false).
hooks.allowedSessionKeyPrefixes는 요청 페이로드 및 매핑의 명시적 sessionKey 값을 선택적으로 제한합니다.
allowUnsafeExternalContent: true는 해당 훅의 외부 콘텐츠 안전 래퍼를 비활성화합니다 (위험; 신뢰할 수 있는 내부 소스에만 사용).
openclaw webhooks gmail setup은 openclaw webhooks gmail run용 hooks.gmail 설정을 작성합니다. 전체 Gmail watch 흐름은 Gmail Pub/Sub를 참고하세요.

응답

200: /hooks/wake
200: /hooks/agent (비동기 실행 수락)
401: 인증 실패
429: 동일 클라이언트에서 반복 인증 실패 후 (Retry-After 확인)
400: 유효하지 않은 페이로드
413: 과대 페이로드

예시

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

다른 모델 사용

에이전트 페이로드(또는 매핑)에 model을 추가하여 해당 실행의 모델을 오버라이드합니다:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'

agents.defaults.models를 강제하는 경우, 오버라이드 모델이 해당 목록에 포함되어 있는지 확인하세요.

curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'

보안

훅 엔드포인트를 루프백, 테일넷, 또는 신뢰할 수 있는 리버스 프록시 뒤에 유지하세요.
전용 훅 토큰을 사용하세요. 게이트웨이 인증 토큰을 재사용하지 마세요.
반복적인 인증 실패는 클라이언트 주소별로 속도 제한이 적용되어 무차별 대입 시도를 늦춥니다.
멀티 에이전트 라우팅을 사용하는 경우, hooks.allowedAgentIds를 설정하여 명시적 agentId 선택을 제한하세요.
호출자 선택 세션이 필요하지 않다면 hooks.allowRequestSessionKey=false를 유지하세요.
요청 sessionKey를 활성화하는 경우, hooks.allowedSessionKeyPrefixes를 제한하세요 (예: ["hook:"]).
웹훅 로그에 민감한 원시 페이로드를 포함하지 마세요.
훅 페이로드는 신뢰할 수 없는 것으로 취급되며 기본적으로 안전 경계로 래핑됩니다. 특정 훅에 대해 이를 비활성화해야 하는 경우, 해당 훅의 매핑에서 allowUnsafeExternalContent: true를 설정하세요 (위험).

웹훅

활성화

인증

엔드포인트

POST /hooks/wake

POST /hooks/agent

세션 키 정책 (호환성을 깨는 변경)

POST /hooks/<name> (매핑)

응답

예시

다른 모델 사용

보안

`POST /hooks/wake`

`POST /hooks/agent`

`POST /hooks/<name>` (매핑)