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

@@ -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):
 

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