From 73f31c75bed48fca9527adb539d7ef06953149ca Mon Sep 17 00:00:00 2001 From: user Date: Sat, 28 Feb 2026 03:24:32 -0800 Subject: [PATCH] docs: add webhook vs poller notification delivery approaches Add a new 'Notification Delivery: Webhooks vs Polling' section to OPENCLAW_TRICKS.md explaining the two approaches for receiving Gitea notifications: 1. Direct webhooks for VPS/public server deployments (realtime, push-based) 2. Notification poller for local machines behind NAT (simple, no firewall config) Includes a comparison table to help users choose. Update SETUP_CHECKLIST.md Phase 10 to present both options (A and B) with separate sub-checklists, replacing the previous poller-only instructions. --- OPENCLAW_TRICKS.md | 48 +++++++++++++++++++++++++++++++++++++++++++--- SETUP_CHECKLIST.md | 28 +++++++++++++++++++++++++-- 2 files changed, 71 insertions(+), 5 deletions(-) diff --git a/OPENCLAW_TRICKS.md b/OPENCLAW_TRICKS.md index 6c155e9..ffd1e5e 100644 --- a/OPENCLAW_TRICKS.md +++ b/OPENCLAW_TRICKS.md @@ -1482,9 +1482,51 @@ Never send internal thinking or status narration to user's DM. Output should be: ## Gitea Integration & Notification Polling -For self-hosted Gitea instances, you can set up a notification poller that -injects Gitea events (issue assignments, PR reviews, @-mentions) into the -agent's session. +For self-hosted Gitea instances, you need a way to deliver notifications (issue +assignments, PR reviews, @-mentions) to your agent. There are two approaches, +depending on your network setup. + +### Notification Delivery: Webhooks vs Polling + +#### 1. Direct webhooks (VPS / public server) + +If your OpenClaw instance runs on a VPS or other publicly reachable server, you +can run Traefik (or any reverse proxy) on the same server and configure Gitea +webhooks to POST directly to OpenClaw's webhook endpoint. This is push-based and +realtime — notifications arrive instantly. + +Set up a Gitea webhook (per-repo or org-wide) pointing at your OpenClaw +instance's `/hooks/wake` endpoint. Gitea sends a POST on every event, and the +agent wakes immediately to process it. + +#### 2. Notification poller (local machine behind NAT) + +If your OpenClaw instance runs on a dedicated local machine behind NAT (like a +home Mac or Linux box), Gitea can't reach it directly. In this case, use a +lightweight polling script that checks the Gitea notifications API every few +seconds and signals the agent when new notifications arrive. + +This is the approach we use — OpenClaw runs on a dedicated Mac Studio on a home +LAN, so we poll Gitea's notification API and wake the agent via the local +`/hooks/wake` endpoint when new notifications appear. The poller script is +included below in the [Notification poller](#notification-poller) section. + +The poller approach trades ~30 seconds of latency (polling interval) for +simplicity and no NAT/firewall configuration. For most workflows this is +perfectly fine — code review and issue triage don't need sub-second response +times. If no new notifications arrive between heartbeats, the effective latency +is bounded by the heartbeat interval (~30 minutes), but in practice the poller +catches most events within seconds. + +#### Which should you choose? + +| Factor | Webhooks | Poller | +| ------------------- | ------------------- | ------------------------- | +| Network requirement | Public IP / domain | None (outbound-only) | +| Latency | Instant | ~2-30s (polling interval) | +| Setup complexity | Reverse proxy + TLS | Single background script | +| Dependencies | Traefik/nginx/Caddy | Python stdlib only | +| Best for | VPS / cloud deploys | Home LAN / NAT setups | ### Workflow rules (HEARTBEAT.md / AGENTS.md): diff --git a/SETUP_CHECKLIST.md b/SETUP_CHECKLIST.md index a2aca97..0e8c208 100644 --- a/SETUP_CHECKLIST.md +++ b/SETUP_CHECKLIST.md @@ -495,7 +495,27 @@ code review. - [ ] Grant write access to repos the agent should be able to push to directly - [ ] For other repos: the agent forks and creates PRs -### 10.2 Set up the notification poller +### 10.2 Choose your notification delivery approach + +There are two ways to get Gitea notifications to your agent. Choose based on +your network setup: + +**Option A: Direct webhooks (VPS / public server)** + +If OpenClaw runs on a publicly reachable server (VPS, cloud VM), configure Gitea +webhooks to POST directly to OpenClaw's `/hooks/wake` endpoint. This is +push-based and realtime. + +- [ ] Configure your reverse proxy (Traefik, nginx, Caddy) to expose OpenClaw's + webhook endpoint +- [ ] Add a Gitea webhook (per-repo or org-wide) pointing at your endpoint +- [ ] Verify: create a test issue, confirm the agent wakes instantly + +**Option B: Notification poller (local machine behind NAT)** + +If OpenClaw runs on a local machine behind NAT (home Mac, Linux box), Gitea +can't reach it. Use the polling script instead — it checks the Gitea +notifications API every few seconds and wakes the agent locally. - [ ] Deploy the Gitea notification poller script (source in [OPENCLAW_TRICKS.md](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)) @@ -503,7 +523,11 @@ code review. - [ ] Run as a system service (launchd on macOS, systemd on Linux) - [ ] Verify: create a test issue, confirm the agent wakes and processes it -### 10.3 Set up webhook feed +See +[OPENCLAW_TRICKS.md § Notification Delivery](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md#notification-delivery-webhooks-vs-polling) +for a detailed comparison of both approaches. + +### 10.3 Set up webhook feed (activity channel) - [ ] Add a Gitea webhook to each repo (or use a global/org webhook) - [ ] Point webhooks at your Mattermost/Slack/Discord incoming webhook URL