2026 클라우드 Mac의 OpenClaw Webhook과 Ollama: 토큰, 라우트, 문제 해결

외부 시스템을 OpenClaw에 붙이면 자동화가 «CLI 데모»에서 «항상 켜진 팀원»으로 성숙합니다. 2026년 권장 패턴은 공유 시크릿으로 보호된 /hooks/* 엔드포인트를 노출하는 HTTP 게이트웨이와 Apple Silicon의 Ollama로, HTML/CSS 리팩터를 가능한 한 LAN 추론 경로에 두는 것입니다—배선이 맞을 때요. 이 글은 Webhook 활성화, wake 대 agent 라우트 선택, 게이트웨이와 같은 Mac에서 Ollama 검증, 업그레이드 후에도 GitHub 이슈에 남는 오류 대응을 다룹니다.

훅과 시크릿을 안전하게 켜기

상위 문서는 hooks.enabled: true와 모든 POST를 검증하는 토큰을 요구합니다. 우선 Authorization: Bearer <token>을 쓰세요. 레거시 클라이언트용 x-openclaw-token도 있습니다. 쿼리 매개변수에 비밀을 넣지 마세요—접근 로그와 브라우저 기록에 남습니다.

설정을 바꾼 뒤 게이트웨이를 재시작하고, 리버스 프록시가 TLS를 종료하기 전까지 리스너가 127.0.0.1에만 바인딩되는지 확인하세요. 노트북 밖으로 무엇이든 노출하기 전에 프로덕션 게이트웨이 강화 가이드를 읽고 루프백·인증서·터널 정책을 맞추세요.

운영 측면에선 분기마다 토큰을 회전하고 staging에서 24시간 검증 후 프로덕션에 롤링하며, 롤백용으로 이전 토큰을 짧게만 남깁니다. 다중 환경이면 환경별로 다른 시크릿을 써 테스트 훅이 프로덕션 에이전트를 건드리지 않게 합니다.

로그에는 요청 ID와 훅 유형을 넣어 게이트웨이 줄과 Ollama 줄을 상관시킵니다. 규제 산업에서는 전체 JSON 본문 debug 로그를 피하거나 민감 필드를 마스킹합니다. 서드파티 SaaS webhook이면 문서의 IP 대역과 서명 알고리즘을 재확인해 가짜 POST를 합법 이벤트와 섞지 마세요.

/hooks/wake vs /hooks/agent

POST /hooks/wake는 «시스템을 가볍게 찌르는» 이벤트—CI 완료, 캘린더 알림, CMS가 폴더 폴링을 유도하는 신호입니다.POST /hooks/agent는 격리 실행용으로 파트너 연동처럼 신뢰할 수 없는 JSON에 더 작은 폭발 반경을 줍니다.

라우트	전형 페이로드	언제
/hooks/wake	가벼운 신호+메타	스케줄 잡, 저장소 푸시 훅
/hooks/agent	작업 본문+툴 힌트	Jira/Linear 티켓 자동화

같은 비즈니스 흐름에 깨움과 툴 매개변수가 모두 필요하면 게이트웨이 앞에 큐로 피크를 깎고 워커가 내부 API로 분기하면 Ollama를 직격하기 어렵습니다. 순서가 엄격한 파이프라인은 페이로드에 단조 증가 시퀀스를 넣고 핸들러에서 중복을 제거합니다.

복사해 쓰는 curl 예

게이트웨이에 닿을 수 있는 호스트(대개 SSH 터널)에서 실행합니다.

curl -sS -X POST "https://gateway.example/hooks/wake" \
  -H "Authorization: Bearer $OPENCLAW_HOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"source":"ci","build":"12345"}'

로컬 테스트는 URL을 루프백 터널(예 https://127.0.0.1:8443/hooks/wake)로 바꿉니다. HTTP 200 또는 204와 JSON 본문을 기대합니다. 즉시 401은 Bearer 불일치, 404는 게이트웨이가 오래됐거나 경로 오타—끝 슬래시는 프록시가 정규화해 차이가 납니다.

curl -sS -X POST "https://127.0.0.1:8443/hooks/agent" \
  -H "Authorization: Bearer $OPENCLAW_HOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"task":"Summarize dist/index.html headings","repo":"/Users/build/workspace/site"}'

CI에서는 jq로 .status == "accepted"를 검증합니다. 로드밸런서가 HTTP/2를 종료하면 중복 POST 재시도를 주의하세요. 멱등 핸들러는 약 5분 안의 동일 build ID를 감지해 단락해 비싼 Ollama 프롬프트 이중 실행을 막습니다.

다지역 팀은 노트북과 클라우드 Mac 모두에서 같은 curl을 돌려 DNS·체인·시스템 프록시 차이를 없앱니다. 기업 SSL 검사가 있으면 루트 CA를 클라우드 Mac 키체인에 넣지 않으면 curl만 성공하고 Node 프로세스만 실패해 «게이트웨이만 깨짐» 착시가 납니다.

M 시리즈 Ollama: 포트, 모델, 폴백

Ollama는 기본 127.0.0.1:11434를 수신합니다. OpenClaw를 돌리는 같은 Mac에서 카탈로그를 확인합니다.

curl -sS http://127.0.0.1:11434/api/tags | jq '.models[].name'

openclaw.json에서는 qwen2.5:7b 같은 명시 ID로 모델을 고정하세요. 모호한 별칭은 스케줄러를 클라우드 API로 폴백시킵니다. 최근에 npm 대 Docker 배포 비교를 읽었다면 컨테이너나 글로벌 설치가 Ollama와 같은 네트워크 네임스페이스를 공유하는지 확인하세요. Docker에선 host.docker.internal:11434가 필요한 경우가 많습니다.

처리량 힌트: Apple Silicon Mac mini에서 7B급은 35~50 tok/s 전후. 가중치와 Node 게이트웨이에 최소 8GB RAM을 예산하세요. 네이티브 Ollama API와 /v1 OpenAI 호환면은 툴 호출 행동이 달라 OpenClaw 플래너가 제공자 문자열로 전송 계층을 고릅니다. 짧은 JSON 툴 스키마로 둘 다 시험해 구조화 인수인지 산문인지 보고 webhook 운영 매뉴얼에 승리 조합을 적습니다.

대형 저장소는 스킬 설정으로 인덱스 경로를 제한하고 .openclawignore로 node_modules와 빌드 산출물을 빼 컨텍스트를 슬림하게 합니다. 모델이 diff를 중간에 자르면 «파일 나열»과 «파일별 패치」 두 단계로 작업을 쪼개고 훅 페이로드에 파일 경계를 명시하면 에이전트의 범위 밖 수정이 줄어듭니다.

2026년 알려진 실패 모드

1. Ollama 성공 후 HTTP 404. 상위 이슈 추적: 실행은 끝나는데 콜백이 없음. 완화: 최신 패치로 올리고 리버스 프록시가 /hooks/*를 그대로 전달하는지 확인.
2. Ollama 스트림에서 커스텀 헤더 삭제. X-OLLAMA-KEY가 필요한 보호 엔드포인트는 구버전이 내부 스트림에서 헤더를 떨구면 403. 프록시에 주입하거나 수정 릴리스까지 업데이트.
3. Ollama 설정인데 Anthropic 호출. 게이트웨이 프로세스 환경에서도 curl해 방화벽 틈을 잡으세요.agents.defaults.model.primary를 ollama/model:tag로 명시하고 폴백 경고 로그를 봅니다.
4. 소형 모델이 툴 스키마 거부. Gemma급 체크포인트는 툴 부착 시 HTTP 400을 줄 수 있고 OpenClaw가 툴 없이 재시도—소형 로컬 모델엔 단순 작업을 배정하세요.

어느 것이든 재현할 때 게이트웨이와 Ollama 로그를 나란히 약 30초 모아 타임스탬프를 맞추면 네트워크·인증·모델 중 어디가 깨졌는지 한 번의 반복으로 가름하기 쉽습니다.

외부 벡터 DB나 검색 플러그인을 쓰면 webhook이 같은 초에 대량 인덱스 리프레시를 일으켜 SSD I/O와 모델 큐를 동시에 포화시키지 않도록 핸들러에 동시 실행 상한과 데드레터 큐를 둡니다.

임대 Mac mini에서 스테이징하는 이유

Webhook과 로컬 추론은 상주 프로세스를 뜻합니다: 게이트웨이, Ollama, 때로 브라우저 스킬. 클라우드 Mac mini는 부하를 노트 배터리에서 멀리하고 OpenClaw 플러그인이 기대하는 macOS 경로를 유지하며, 위험한 업그레이드 전 알려진 좋은 openclaw.json을 스냅샷할 수 있습니다. 실험이 터지면 공유 사무실 머신을 되찾는 것보다 재프로비저닝이 빠릅니다.

SSH로 로그를 tail하고 macOS 개인정보 확인이 필요하면 가끔 VNC—같은 노드, 두 접근, 추가 하드웨어 없음. 기록할 지표: webhook 주간 수락률 목표 99.5%, POST부터 첫 에이전트 로그 줄까지 p95(LAN에선 종종 300~800ms), Ollama 큐 깊이. 클라우드 429가 치솟으면 훅 부채가 병렬 에이전트를 과다 기동한 경우가 많습니다—CI에 세마포를 넣거나 cron을 30~60초 어긋냅니다.

HTML/CSS 저장소는 스킬을 정적 빌드와 같은 작업 트리로 향하게 해 webhook이 만지는 diff를 한 PR에 담습니다. 전형은 클라우드 Mac의 /Users/build/workspace/site이고 .openclawignore로 node_modules와 dist를 제외. Slack/Teams를 잇는 경우 분기마다 서명 시크릿을 돌리고 security add-generic-password로 키체인에 넣어 디버깅 중 env | grep OPENCLAW 유출을 막습니다.

MacHTML 임대 노드에선 고객별로 사용자와 LaunchAgent를 나눠 임시 파일 교차 읽기를 방지합니다. 컴플라이언스가 빡세면 게이트웨이 액세스 로그를 append-only 스토리지로보내고 보존 기간을 명시합니다. 다국적 팀은 주요 사용자와 같은 리전 데이터센터를 골라 TLS 왕복이 webhook 꼬리 지연에 미치는 영향을 줄입니다.

«성공 드릴»을 빈 머신에서 첫 2xx webhook까지의 시간·명령 시퀀스·롤백 절차가 갖춰진 형태로 정의하고 메이저 업그레이드마다 재실행하면 주말 온콜 인지 부하가 줄어듭니다.

FAQ

Ollama는 성공했는데 HTTP 404가 왜 뜨나요?

일부 게이트웨이 빌드는 Ollama를 제공자로 둘 때 실행 후 콜백을 잘못 처리합니다. OpenClaw를 업데이트하고 Webhook URL 경로가 문서의 /hooks/*와 일치하는지 확인하고, 응답 단계에서 게이트웨이 로그를 확보하세요.

쿼리스트링 토큰은 허용되나요?

현재 권장은 쿼리스트링 비밀을 거부하는 것입니다. Authorization: Bearer 또는 x-openclaw-token 헤더를 쓰세요.

Ollama를 설정했는데 OpenClaw가 Anthropic을 호출하는 이유는?

기본 모델 문자열이 유효한 ollama/ 참조가 아니거나 게이트웨이 프로세스가 데몬에 닿지 못하면 모델 탐색이 폴백합니다. curl로 연결을 검증하고 agents.defaults.model.primary를 명시적으로 고정하세요.

MacHTML에서 Apple Silicon 용량을 빌리면 webhook 엔드포인트와 Ollama 모델을 24/7 따뜻하게 유지하면서 개인 MacBook을 과열시키지 않을 수 있습니다. 그 안정성은 놓친 CI 훅 감소와 대형 저장소 HTML/CSS 재작성에서 예측 가능한 토큰 지연으로 이어집니다. 임대 노드를 프로덕션에 가까운 스테이징으로 취급하고 성공 드릴 후 일주일 의존성을 동결한 뒤 계획적으로 업그레이드하세요.