헤르메스 웹훅 가이드 — 바깥세상이 회사를 부른다
지금까지 우리 회사는 우리가 시켜야 움직였습니다. 이번 시간에는 방향을 바꿉니다. 바깥세상에서 사건이 생기면, 그 신호가 우리 회사를 깨우도록 만듭니다. 그리고 한 가지 중요한 판단을 배웁니다. 들어온 신호에 에이전트를 깨워 일을 시킬지, 아니면 직원 없이 알림만 즉시 전달할지입니다.
💡 사전 요구사항: 헤르메스 MCP 가이드에서 도구를 붙이는 방향(우리가 거는 전화)을, 헤르메스 cron 가이드에서 시간으로 깨우는 자동화를 익히셨다면 준비가 된 것입니다. 웹훅은 그 반대, 바깥에서 들어오는 사건입니다.

웹훅이 무엇이고, 언제 쓰나요
웹훅은 외부 서비스에서 사건이 생겼을 때, 그 서비스가 우리가 정한 주소로 데이터를 보내 알려주는 방식입니다. 우리가 물어보러 가는 것이 아니라, 사건이 생긴 쪽이 먼저 알려줍니다.
- MCP는 우리 에이전트가 외부 도구를 쓰러 나가는 방향입니다.
- cron은 정해진 시간에 우리가 작업을 돌리는 방식입니다.
- 웹훅은 반대로, 외부에서 사건이 우리 쪽으로 들어옵니다.
고객 문의 제출, 결제 완료, 새 글 발행처럼 외부 사건에 즉시 반응해야 할 때 씁니다.
1단계. 웹훅 입구 켜기
웹훅은 게이트웨이의 한 플랫폼입니다. 8644 포트에 접수창구를 여는 것인데, 켜는 방법이 두 가지입니다.
방법 A. 웹 대시보드에서 (가장 쉬움)
왼쪽 사이드패널에서 WEBHOOKS 메뉴를 클릭하면 웹훅 관리 페이지가 열립니다. 처음에는 "Webhook receiver disabled" 상태입니다. 오른쪽 위의 ENABLE WEBHOOKS 버튼을 누르면 활성화됩니다.

방법 B. 설정 파일에서
# ~/.hermes/profiles/본인프로필/config.yaml
platforms:
webhook:
enabled: true
extra:
host: "0.0.0.0"
port: 8644
⚠️ 환경변수(.env)로만 켜면 게이트웨이는 듣고 있는데 구독 명령이 비활성으로 나옵니다. 대시보드나 설정 파일로 켜 주세요.
💡 포트 충돌 우회: 여러 프로필의 게이트웨이를 함께 돌리면 8644 포트가 겹칠 수 있습니다. 다른 프로필 게이트웨이가 이미 8644를 쓰고 있으면 이 프로필의 웹훅 서버가 뜨지 못해 요청이 404가 납니다. 이럴 땐 위
port를 8645처럼 비어 있는 번호로 바꾸고 게이트웨이를 재시작하세요. 그러면 헬스 확인과 웹훅 주소도 바뀐 포트로 씁니다(예:http://localhost:8645/webhooks/magma-inquiry).
웹훅을 켜지 않은 채로 터미널에서 바로 구독을 시도하면, 헤르메스가 켜는 법 세 가지를 친절히 안내해 줍니다. 먼저 켜고 진행하세요.

게이트웨이를 띄우고 입구가 살아 있는지 확인합니다.
hermes gateway run
curl http://localhost:8644/health
{"status": "ok", "platform": "webhook"} 가 보이면 성공입니다.
핵심 판단 — 깨울까, 그냥 전달할까
신호가 들어왔을 때 두 갈래 길이 있습니다. 이 단원의 가장 중요한 설계 판단입니다.

- 에이전트 모드: 직원이 깨어나 내용을 읽고, 판단하고, 행동까지 합니다. 분류하고, 답변 초안을 쓰고, 카드를 만들고, 담당자에게 보냅니다.
- 전달 전용 모드: 직원을 깨우지 않고 메시지만 즉시 전달합니다. 판단이 필요 없는 단순 알림용이고, 토큰 비용이 들지 않습니다.
💡 대시보드 구독 폼의 DELIVER ONLY 체크박스가 이 스위치입니다. 체크하면 에이전트를 건너뛰고 바로 전달, 체크하지 않으면 에이전트가 깨어납니다.
2단계. 먼저 준비할 것 — 회사 지식
에이전트가 진짜 도움이 되려면 우리 회사 사정을 알아야 합니다. 그래서 고객지원 지식을 미리 스킬로 준비합니다. 이 스킬은 한 프로필에만 두지 않고 공용 폴더 ~/.agents/skills에 설치합니다. 그러면 어느 프로필이든 그 폴더를 불러와 함께 쓸 수 있습니다. skills.sh CLI로 한 줄입니다.
skills add dandacompany/dante-skills@magma-support -g -y --copy -a cline
💡
hermes skills install은 지금 프로필에만 설치되지만, 위skills명령은 공용 폴더~/.agents/skills에 복사해 둡니다.-a는 설치 폴더를 고르는 옵션인데,cline을 비롯한 몇몇 타깃이 바로~/.agents/skills에 씁니다. 이름은 신경 쓰지 말고, 폴더가~/.agents/skills면 됩니다.💡 프로필이 이 공용 폴더를 불러오게 하려면 프로필 설정에 한 줄이 있어야 합니다. 헤르메스 설정 파일(
config.yaml)의skills.external_dirs에~/.agents/skills가 들어 있으면 됩니다(대개 기본으로 켜져 있습니다). 설치 후hermes -p sophie skills list에magma-support가 보이면 준비된 것입니다. 직접 받아 두고 싶으면 이 가이드의 프로젝트 파일 탭.agents/skills/magma-support/에서도 받을 수 있습니다.
magma-support/
SKILL.md 응대 지침과 가드레일
references/
products.md 대표 제품과 가격대
sizing.md 사이즈표와 핏 가이드
policies.md 재입고·교환환불·배송·주문 정책
faq.md 자주 묻는 질문
💡 핵심은 데이터의 양이 아니라 경계입니다. SKILL.md에 "정책에 있는 것만 정확히 답하고, 실시간 재고나 정확한 입고일처럼 확실하지 않은 것은 추측하지 말고 담당자 확인 필요로 표시하라"는 지침을 넣어 둡니다.
3단계. 에이전트 모드 — 행동하는 비서
문의를 받을 전화번호를 만듭니다. 대시보드 폼에 다음 값을 입력합니다.
| 폼 필드 | 입력값 |
|---|---|
| NAME | magma-inquiry |
| DESCRIPTION | MAGMA 고객 문의 접수·분류·답변 초안 |
| EVENTS | (비움 = 전체) |
| DELIVER TO | Slack (담당 채널) |
| DELIVER ONLY | 체크하지 않음 (에이전트 모드) |
| PROMPT | 아래 지침 |
PROMPT 칸에는 에이전트가 할 일을 적습니다.
고객 문의입니다. 고객지원 정책을 참고해 (1) 문의 유형을 한 단어로 분류하고
(2) 정중한 1차 답변 초안을 작성한 뒤 (3) 터미널로
hermes kanban create "[문의/유형] {inquiry.message}" --assignee default
카드를 만들고 카드 id를 보고하세요. 정책으로 확실하지 않은 내용은 추측하지 말고
담당자 확인 필요로 표시하세요. 문의: {inquiry.message}
실제로 폼을 채우면 이런 모습입니다.

같은 구독을 터미널로 만들 수도 있습니다.
hermes webhook subscribe magma-inquiry \
--description "MAGMA 고객 문의 접수·분류·답변 초안" \
--prompt "위 PROMPT 내용을 그대로" \
--skills magma-support \
--deliver slack --deliver-chat-id "담당채널"
💡 secret은 따로 적지 않습니다. 적지 않으면 시스템이 강한 값을 자동으로 만들어 줍니다. 대시보드에서 만들면 생성 직후 화면에 한 번 표시되니 그때 복사해서 외부 서비스에 붙여 넣으세요. 특정 값으로 고정하고 싶으면 명령에
--secret 본인이정한값을 한 줄 더하면 됩니다.
구독을 만들면 웹훅 URL과 secret이 한 번만 표시됩니다. secret은 이 화면에서만 보이니 바로 복사해 두세요.

만들고 나면 웹훅 목록(Subscriptions)에 이렇게 등록됩니다. 구독 변경은 수신기가 켜져 있으면 바로 반영(hot-reload)됩니다.

외부 폼을 붙이기 전에, 우리 손으로 가짜 문의를 한 발 쏴서 확인합니다.
hermes webhook test magma-inquiry \
--payload '{"inquiry":{"message":"마그마 자켓 L 재입고 언제 되나요? 색상 교환도 되나요?"}}'
처음 발사하면 답변 초안은 담당 채널에 잘 도착하는데, 카드 생성에서 "터미널 실행 도구가 제공되지 않아 실행할 수 없습니다"가 나옵니다. 슬랙에는 이렇게 도착합니다.

왜냐하면 웹훅 플랫폼은 도구가 기본 최소이기 때문입니다. 외부에서 들어오는 입구라 검색·보기 정도(web·vision)만 켜져 있고, 터미널·파일·코드 실행은 꺼져 있습니다.
⚠️ 헷갈리기 쉬운 점:
hermes tools list는 기본이 cli 플랫폼이라 터미널이 켜져 보입니다. 하지만 웹훅으로 들어온 요청은 webhook 플랫폼 권한을 따릅니다. 웹훅 도구 상태는 꼭 플랫폼을 지정해 확인하세요.
hermes tools list --platform webhook
행동(카드 생성 등 터미널 사용)이 필요하면 webhook 플랫폼에 명시적으로 켜고, 게이트웨이를 재시작합니다.
hermes tools enable --platform webhook terminal
hermes gateway restart
💡 파일·코드 실행까지 함께 켜려면
hermes tools enable --platform webhook terminal file code_execution처럼 한 줄에 나열합니다.⚠️ 보안: 웹훅에 터미널을 켜면 외부 POST 요청이 에이전트에게 쉘 명령 실행을 유도할 수 있습니다. HMAC secret을 반드시 유지하고, 신뢰된 자동화 경로에서만 켜세요.
다시 발사하면 에이전트가 행동합니다.

- 정책을 반영한 1차 답변 초안을 만듭니다. 확실하지 않은 정보는 담당자 확인 필요로 표시합니다.
- 칸반 카드를 만들어 팀 보드에 기록합니다.
- 담당 채널로 문의와 추천 답변, 카드 id를 보냅니다.
💡 단순히 답만 쓴 것이 아니라 분류·기록·전달까지 행동했습니다. 외부 신호 하나에 직원이 알아서 일을 처리한 것입니다. 전달 설정에 문의 유형 같은 값을 끼우면 유형별로 다른 채널에 보내는 동적 라우팅도 됩니다.
진짜 외부 폼 연결 — Tally
여기까지는 우리 손으로 가짜 문의를 쏴 본 것입니다. 이제 진짜 고객이 채우는 폼을 붙여 봅니다. 설문 폼 중 Tally는 웹훅을 기본으로 보내 주고 커스텀 헤더도 넣을 수 있어 헤르메스에 바로 붙습니다. (참고로 Google Forms는 웹훅을 직접 보내지 못해 별도 스크립트가 필요합니다.)
⚠️ 외부 서비스(Tally)의 서버가 우리 웹훅에 닿아야 하므로, 이때부터는
localhost가 아니라 공개 주소가 필요합니다. 공개 주소 준비는 사전 요구사항입니다.
공개 주소 만들기 — Tailscale Funnel
앞 섹션에서 설치한 Tailscale로 바로 공개 주소를 만들 수 있습니다. 내 컴퓨터의 localhost:8645를 인터넷에서 닿는 HTTPS 주소로 열어 줍니다.
tailscale funnel --yes --bg 8645
- 로컬 8645를 공개 HTTPS(443)로 노출하고 백그라운드로 등록합니다.
--yes는 설정 변경을 확인 없이 승인,--bg는 백그라운드 실행입니다. - 처음 켤 때 Funnel 활성화가 필요하면 안내 링크가 나옵니다. 관리 콘솔에서 허용(HTTPS 인증서·Funnel)하세요.
- 공개 주소는
https://기기이름.테일넷이름.ts.net형태로 나옵니다. 끄려면tailscale funnel off.
⚠️
listener already exists for port 443가 뜨면, 이미 다른 Funnel/Serve가 443을 쓰고 있는 경우입니다(Funnel은 외부 HTTPS를 443에서 받습니다). 그냥tailscale funnel 8645로 실행하면 충돌하니, 위처럼--yes --bg로 기존 설정을 갱신하며 추가하세요. 다른 Funnel이 있으면 새 주소가 다른 호스트명(예:기기이름-1.테일넷이름.ts.net)으로 나올 수 있으니, 출력에 찍힌 실제 주소를 확인해 Tally Endpoint에 넣습니다.
받은 공개 주소 뒤에 /webhooks/magma-inquiry를 붙인 것이 Tally에 넣을 Endpoint URL입니다.
https://기기이름.테일넷이름.ts.net/webhooks/magma-inquiry
💡 Tailscale Funnel은 임시 터널과 달리 주소가 고정이고 자동 HTTPS라, Tally Endpoint를 한 번만 넣어 두면 됩니다. (아주 빠른 일회성 테스트만 필요하면
cloudflared tunnel --url http://localhost:8645같은 임시 터널도 있지만, 우리는 이미 깐 Tailscale로 갑니다.)⚠️ 주소가 공개됐다는 건 누구나 두드릴 수 있다는 뜻입니다. 인증 헤더(
X-Gitlab-Token)와 secret을 반드시 유지하세요.
문의 폼 만들기 — 두 가지 방법
폼은 두 가지로 만들 수 있습니다. 헤르메스 에이전트에게 시켜 API로 만들거나(A), Tally 화면에서 직접 만들거나(B). 둘 다 결과는 같은 폼입니다.
방법 A. 헤르메스 에이전트가 API로 생성 — 강사와 똑같은 폼이 나오도록 정의를 고정해 두었습니다.
먼저 Tally API 키를 발급합니다. 오른쪽 위 계정 이름을 누르고 Settings로 들어가, API keys 탭에서 Create API key를 누릅니다.

키 이름을 적고(예: basic) Create를 누르면 키가 발급됩니다.

발급된 키를 Sophie 프로필의 환경 파일에 저장합니다. 아래 명령으로 환경 파일 경로를 확인하고, 그 파일을 편집기로 열어 TALLY_API_KEY=발급받은키 한 줄을 추가합니다(키는 화면에 출력하지 말고 편집기로 직접 붙여 넣으세요).
hermes -p sophie config env-path
다음으로 에이전트가 Tally를 다룰 수 있도록 tally-api 스킬을 설치합니다. 이 스킬은 Tally REST API(폼 생성·제출 조회·웹훅 생성)와 호출용 헬퍼를 담고 있어, 에이전트가 API를 직접 다룰 때 길잡이가 됩니다. 이건 Sophie만 쓰는 스킬이라 Sophie 프로필에 설치합니다(헤르메스 스킬 설치).
hermes -p sophie skills install dandacompany/dante-skills/tally-api
💡 앞의 magma-support는 여러 프로필이 함께 쓸 고객지원 지식이라 공용 폴더(
~/.agents/skills)에 깔았지만, tally-api는 Sophie의 접수 업무 전용이라 Sophie 프로필에만 설치합니다. 같은 스킬이라도 공유 범위에 따라 설치 위치를 고릅니다.
이제 Sophie에게 평소처럼 자연스럽게 요청하면 됩니다. 폼에 받을 내용과 웹훅 설정을 말로 적어 주면, 에이전트가 tally-api 스킬을 써서 폼을 만들고 웹훅 연결까지 해 줍니다. 토큰(secret) 값만 보안을 위해 직접 넣습니다. (터미널 도구와 tally-api 스킬이 준비돼 있어야 합니다.)
form 제목은 MAGMA 문의하기
1. 답변받을 이메일 주소
2. 무엇을 도와드릴까요?
통합은 웹훅 방식을 사용하고, 아래처럼 설정해 줘.
url : https://본인공개주소/webhooks/magma-inquiry
http header : X-Gitlab-Token (내 secret)
토큰 값은 내가 직접 Tally 웹페이지에서 입력할게.
💡 폼 정의를 JSON으로 일일이 적지 않아도, 이렇게 말로 주면 tally-api 스킬이 Tally 블록 구조(제목·이메일 입력칸·서술형 입력칸)에 맞춰 알아서 만들어 줍니다. 이메일 필드를 꼭 넣어 두세요. 답변 초안을 그 주소로 보내야 하니까요.
url은 본인 공개 주소(앞서 만든 Tailscale Funnel 주소)로 바꿉니다.
에이전트가 폼을 만들고 웹훅까지 연결한 뒤 공개 주소를 알려 줍니다. 이제 남은 건 토큰 값을 직접 넣는 것 하나입니다(아래 "토큰 값 넣기").
방법 B. Tally 화면에서 직접 만들기 — API 대신 직접 만들고 싶으면, Tally 홈에서 New form을 누릅니다.

폼은 아래와 같이 구성합니다. 블록 추가 메뉴에서 이메일은 Email, 문의 내용은 Long answer(여러 줄 입력)를 고르면 됩니다.
| 순서 | 블록(Tally) | 화면 텍스트 | 설정 |
|---|---|---|---|
| 제목 | Form title | MAGMA 문의하기 | 제출 버튼 "제출하기" |
| 질문 1 | 답변받을 이메일 주소 | 필수 | |
| 질문 2 | Long answer | 무엇을 도와드릴까요? | 필수 |
이메일을 받아 둬야 답변 초안을 그 주소로 보낼 수 있습니다. 문의 유형 같은 분류는 폼에서 받지 않아도 됩니다. 들어온 글을 보고 에이전트가 답변 단계에서 알아서 분류하니까요. 다 만들었으면 오른쪽 위 Publish를 눌러 발행합니다.

웹훅 연결과 토큰 값 넣기
- 방법 A로 만들었다면 — 에이전트가 웹훅 url과
X-Gitlab-Token헤더까지 이미 걸어 두었습니다. 남은 건 토큰 값 하나입니다. Tally의 Integrations → Webhooks에서 그 웹훅을 열어,X-Gitlab-Token값에 구독 생성 때 받은 secret을 넣고 저장하면 됩니다(아래 화면의 헤더 값 칸). - 방법 B로 만들었다면 — 웹훅을 처음부터 직접 겁니다. 아래 순서를 따라가세요.
폼이 헤르메스로 전달되려면 secret(토큰)이 양쪽에서 일치해야 합니다. secret 값은 화면에서 직접 다룹니다.
먼저 Share 탭에서 폼 주소를 확인할 수 있습니다(외부에 공유할 주소입니다).

이제 Integrations 탭으로 가서 Webhooks의 Connect를 누릅니다.

웹훅 설정 창이 열리면 두 가지를 채웁니다.
- Endpoint URL = 앞서 만든 공개 주소 뒤에
/webhooks/magma-inquiry를 붙인 값.
https://본인공개주소/webhooks/magma-inquiry
- Add HTTP headers를 눌러 인증 헤더를 추가합니다. 이름은
X-Gitlab-Token, 값은 구독 생성 때 받은 우리 secret입니다. 헤르메스는 이 헤더로 "우리가 허락한 요청"인지 확인합니다.
X-Gitlab-Token : (구독 생성 때 받은 secret)
- Connect를 눌러 저장합니다.

Tally는 응답을 data.fields 배열에 담아 보냅니다. 그래서 구독 프롬프트에서는 특정 자리 대신 전체 페이로드를 넘겨 에이전트가 직접 읽게 합니다. {__raw__}가 전체 제출 내용입니다.
구독 프롬프트는 에이전트가 할 일을 명시적으로 적습니다. 문의가 오면 magma-support 스킬을 열어 정책을 확인하고, 고객 이메일과 문의를 찾아, 답변을 Gmail 초안으로 저장하고, 담당 채널에 알리게 합니다.
hermes webhook subscribe magma-inquiry \
--skills magma-support \
--deliver slack --deliver-chat-id "담당채널" \
--prompt "고객이 문의 폼을 제출했습니다. 먼저 magma-support 스킬을 열어 제품·정책과 이메일 초안 작성·저장 방법을 확인한 뒤 처리하세요. 제출 데이터에서 고객 이메일 주소와 문의 내용을 찾아 (1) 문의 유형을 한 단어로 분류 (2) 정책에 근거한 1차 답변 이메일 초안 작성, 확실하지 않은 건 담당자 확인 필요로 표시 (3) 그 답변을 고객 이메일 앞 Gmail 초안으로 저장하되 발송은 하지 말 것 (4) 칸반 카드 생성 (5) 담당 채널에 문의·추천 답변·초안 저장 결과·카드 id 전달. 제출 데이터: {__raw__}"
💡 사전 준비: 이메일 초안 저장은 Google Workspace CLI(
gws)를 씁니다. 에이전트가 도는 헤르메스 서버에 gws가 설치·인증돼 있어야 합니다(앞 섹션의 gws 설정). 초안 저장 명령 형식은 magma-support 스킬에 담겨 있으니 에이전트가 스킬을 열어 참고합니다. 초안은 저장만 하고 발송하지 않으므로, 담당자가 Gmail에서 검토한 뒤 보냅니다.
이제 누군가 Tally 폼을 제출하면, Tally가 우리 웹훅으로 직접 POST하고, Sophie가 정책을 확인해 분류·답변 이메일 초안 저장(고객 주소 앞)·칸반 카드·담당자 전달까지 처리합니다. 담당자는 슬랙 알림을 보고 Gmail 초안을 검토해 보내기만 하면 됩니다. 우리가 시키지 않아도 바깥 고객이 우리 팀을 깨우는 것입니다.
실제로 만들어지는 Gmail 초안은 이런 모습입니다. 고객 주소가 수신자로 들어가 있고, 제목과 본문이 정책에 맞춰 완성돼 있으며, 확실하지 않은 부분은 담당자 확인이 필요하다고 정직하게 적혀 있습니다. 보내기는 사람이 마지막에 누릅니다.

팀 보드에도 카드가 자동으로 박힙니다. 슬랙에서 /kanban list를 실행하면, 방금 들어온 문의가 새 카드로 올라온 것을 볼 수 있습니다. 아래 맨 아래 줄이 이번 문의로 생성된 카드입니다(담당 sophie, 진행 중).

💡 다른 폼 서비스도 비슷합니다. Typeform·Jotform도 웹훅을 보냅니다. 핵심은 그 서비스가 우리가 알아볼 수 있는 인증 방식(토큰 헤더 또는 서명)으로 보내 줄 수 있느냐입니다. Tally는 커스텀 헤더를 지원해 토큰 방식으로 가장 쉽게 붙습니다.
4단계. 전달 전용 모드 — 0원 즉시 알림
판단이 필요 없는 신호도 있습니다. 결제 완료 알림 같은 것이죠. 이럴 때는 직원을 깨우지 않고 메시지만 바로 보냅니다.
| 폼 필드 | 입력값 |
|---|---|
| NAME | magma-order-alert |
| DELIVER TO | Slack (주문 채널) |
| DELIVER ONLY | 체크 (에이전트 안 깨움) |
| PROMPT | 새 주문 들어왔습니다. 주문번호 {order.id} / {order.amount}원 / {order.customer} |
터미널로는 이렇게 만듭니다.
hermes webhook subscribe magma-order-alert \
--deliver slack --deliver-chat-id "주문채널" --deliver-only \
--prompt "새 주문 들어왔습니다. 주문번호 {order.id} / {order.amount}원 / {order.customer}"

들어온 데이터를 메시지 틀에 끼워서 직원 없이 바로 보냅니다. 토큰 0원, 1초 안에 전달입니다. 판단이 필요한 일은 에이전트 모드, 단순 알림은 전달 전용. 이 두 갈래를 구분하는 것이 웹훅 설계의 핵심입니다.
⚠️ 전달 전용은 진짜 전달 대상이 있어야 합니다.
--deliver log와는 함께 쓸 수 없습니다.
인증 — secret은 자동발급
입구가 인터넷에 열려 있으니, 우리가 허락한 요청만 받도록 인증을 겁니다. 인증 없는 요청은 401로 거부됩니다.
- 대시보드든 CLI든 secret을 따로 적지 않으면 강한 값이 자동발급됩니다. 대시보드는 생성 직후 한 번 보여주니 그때 복사하세요.
- 그 값을 외부 서비스(폼·결제·깃허브 등)의 웹훅 설정에 붙여 넣으면 양쪽이 같은 secret을 공유하게 됩니다.
- 특정 값으로 고정하려면 CLI에
--secret 본인이정한값을 한 줄 더하면 됩니다.
안전하게 쓰기
⚠️ 외부로 나가는 답변은 자동으로 바로 발송하지 마세요. 담당자에게 추천 답변으로 전달하고, 사람이 검토한 뒤 보내는 것을 기본으로 합니다.
외부 입구로 들어온 일은 기본 권한이 최소입니다. 터미널처럼 행동에 필요한 도구는 명시적으로 열어 줘야 합니다. 딱 필요한 만큼만 여는 설계입니다.
자주 만나는 문제
- 구독 명령이 비활성이라고 나와요. 환경변수로만 켰을 가능성이 큽니다. 대시보드나 설정 파일로 켜세요.
- 요청을 보냈는데 401이 떠요. secret이 빠졌거나 틀린 경우입니다. 자동발급된 secret을 외부 서비스에 정확히 넣었는지 확인하세요.
- 에이전트가 카드를 못 만들어요. 웹훅 플랫폼에 터미널이 꺼져 있습니다(웹훅 도구 기본 최소).
hermes tools enable --platform webhook terminal후hermes gateway restart하세요. 상태는hermes tools list --platform webhook로 확인(hermes tools list만 치면 cli 기준이라 켜져 보입니다). - 구독은 만들었는데 요청이 404가 떠요. 포트 충돌일 수 있습니다. 다른 프로필 게이트웨이가 이미 8644를 점유하면 이 프로필 웹훅 서버가 못 떠서 404가 납니다. config.yaml의
port를 8645처럼 빈 번호로 바꾸고 게이트웨이를 재시작한 뒤, 그 포트로 헬스·요청을 보내세요.
마무리
오늘 우리 회사에 바깥 신호를 받는 입구가 생겼습니다. 판단이 필요한 일은 에이전트가 분류하고 답변 초안을 만들고 카드까지 박고, 단순 알림은 0원으로 즉시 전달합니다. 다음 시간에는 보안 담당을 채용해서, 문을 연 우리 회사를 위에서 아래까지 점검해 보겠습니다.
