Compare commits

..

1 Commits

Author SHA1 Message Date
user
73f31c75be docs: add webhook vs poller notification delivery approaches
All checks were successful
check / check (push) Successful in 11s
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.
2026-02-28 03:24:32 -08:00
2 changed files with 531 additions and 829 deletions

View File

@ -173,84 +173,46 @@ The landing checklist (triggered automatically after every flight) updates
location, timezone, nearest airport, and lodging in the daily context file. It
also checks if any cron jobs have hardcoded timezones that need updating.
### Gitea Notification Delivery
### The Gitea Notification Poller
There are two approaches for getting Gitea notifications to your agent,
depending on your network setup.
#### Option A: Direct Webhooks (VPS / Public Server)
If your OpenClaw instance runs on a VPS or other publicly reachable server, the
simplest approach is direct webhooks. Run Traefik (or any reverse proxy with
automatic TLS) 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.
Setup: add a webhook on each Gitea repo (or use an organization-level webhook)
pointing to `https://your-openclaw-host/hooks/gitea`. OpenClaw handles the rest.
#### Option B: Notification Poller + Dispatcher (Local Machine Behind NAT)
If your OpenClaw runs on a dedicated local machine behind NAT (like a home Mac
or Linux workstation), Gitea can't reach it directly. This is our setup —
OpenClaw runs on a Mac Studio on a home LAN.
The solution: a Python script that both polls and dispatches. It polls the Gitea
notifications API every 15 seconds, triages each notification (checking
assignment and @-mentions), marks them as read, and spawns one isolated agent
session per actionable item via `openclaw cron add --session isolated`.
The poller also runs a secondary **assignment scan** every 2 minutes, checking
all watched repos for open issues/PRs assigned to the bot that were recently
updated and still need a response. This catches cases where notifications aren't
generated (e.g. self-assignment, API-created issues).
OpenClaw has heartbeats, but those are periodic (every ~30min). For Gitea issues
and PRs, we wanted near-realtime response. The solution: a tiny Python script
that polls the Gitea notifications API every 2 seconds and wakes the agent via
OpenClaw's `/hooks/wake` endpoint when new notifications arrive.
Key design decisions:
- **The poller IS the dispatcher.** No flag files, no heartbeat dependency. The
poller triages notifications and spawns agents directly.
- **Marks notifications as read immediately.** Each notification is marked read
as it's processed, preventing re-dispatch on the next poll.
- **One agent per issue.** Each spawned agent gets a `SCOPE` instruction
limiting it to one specific issue/PR. Agents post results as Gitea comments,
not DMs.
- **Dedup tracking.** An in-memory `dispatched_issues` set prevents spawning
multiple agents for the same issue within one poller lifetime.
- **`--no-deliver` instead of `--announce`.** Agents report via Gitea API
directly. The `--announce` flag on isolated sessions had delivery failures.
- **Assignment scan filters by recency.** Only issues updated in the last 5
minutes are considered, preventing re-dispatch for stale assigned issues.
- **Zero dependencies.** Just Python stdlib. Runs anywhere.
- **The poller never marks notifications as read.** That's the agent's job after
it processes them. This prevents the poller and agent from racing.
- **It tracks notification IDs, not counts.** This way it only fires on
genuinely new notifications, not re-reads of existing ones.
- **The wake message tells the agent to route output to Gitea/Mattermost, not to
DM.** This prevents chatty notification processing from disturbing the human.
- **Zero dependencies.** Just Python stdlib (`urllib`, `json`, `time`). Runs
anywhere.
Response time: ~1560s from notification to agent comment (vs ~30 min with the
old heartbeat approach).
Here's the full source:
```python
#!/usr/bin/env python3
"""
Gitea notification poller + dispatcher.
Two polling loops:
1. Notification-based: detects new notifications (mentions, assignments by
other users) and dispatches agents for actionable ones.
2. Assignment-based: periodically checks for open issues/PRs assigned to
the bot that have no recent bot comment. Catches cases where
notifications aren't generated (e.g. self-assignment, API-created issues).
Gitea notification poller.
Polls for unread notifications and wakes OpenClaw when the count
changes. The AGENT marks notifications as read after processing —
the poller never marks anything as read.
Required env vars:
GITEA_URL - Gitea instance URL
GITEA_TOKEN - Gitea API token
HOOK_TOKEN - OpenClaw hooks auth token
Optional env vars:
POLL_DELAY - Delay between polls in seconds (default: 15)
COOLDOWN - Minimum seconds between dispatches (default: 30)
ASSIGNMENT_INTERVAL - Seconds between assignment scans (default: 120)
OPENCLAW_BIN - Path to openclaw binary
GATEWAY_URL - OpenClaw gateway URL (default: http://127.0.0.1:18789)
POLL_DELAY - Delay between polls in seconds (default: 2)
"""
import json
import os
import subprocess
import sys
import time
import urllib.request
@ -258,158 +220,109 @@ import urllib.error
GITEA_URL = os.environ.get("GITEA_URL", "").rstrip("/")
GITEA_TOKEN = os.environ.get("GITEA_TOKEN", "")
POLL_DELAY = int(os.environ.get("POLL_DELAY", "15"))
COOLDOWN = int(os.environ.get("COOLDOWN", "30"))
ASSIGNMENT_INTERVAL = int(os.environ.get("ASSIGNMENT_INTERVAL", "120"))
OPENCLAW_BIN = os.environ.get("OPENCLAW_BIN", "/opt/homebrew/bin/openclaw")
BOT_USER = "clawbot" # Change to your bot's Gitea username
# Repos to scan for assigned issues
WATCHED_REPOS = [
# "org/repo1",
# "org/repo2",
]
# Track dispatched issues to prevent duplicates
dispatched_issues = set()
GATEWAY_URL = os.environ.get("GATEWAY_URL", "http://127.0.0.1:18789").rstrip(
"/"
)
HOOK_TOKEN = os.environ.get("HOOK_TOKEN", "")
POLL_DELAY = int(os.environ.get("POLL_DELAY", "2"))
def gitea_api(method, path, data=None):
url = f"{GITEA_URL}/api/v1{path}"
body = json.dumps(data).encode() if data else None
headers = {"Authorization": f"token {GITEA_TOKEN}"}
if body:
headers["Content-Type"] = "application/json"
req = urllib.request.Request(url, headers=headers, method=method, data=body)
def check_config():
missing = []
if not GITEA_URL:
missing.append("GITEA_URL")
if not GITEA_TOKEN:
missing.append("GITEA_TOKEN")
if not HOOK_TOKEN:
missing.append("HOOK_TOKEN")
if missing:
print(
f"ERROR: Missing required env vars: {', '.join(missing)}",
file=sys.stderr,
)
sys.exit(1)
def gitea_unread_ids():
"""Return set of unread notification IDs."""
req = urllib.request.Request(
f"{GITEA_URL}/api/v1/notifications?status-types=unread",
headers={"Authorization": f"token {GITEA_TOKEN}"},
)
try:
with urllib.request.urlopen(req, timeout=15) as resp:
raw = resp.read()
return json.loads(raw) if raw else None
with urllib.request.urlopen(req, timeout=10) as resp:
notifs = json.loads(resp.read())
return {n["id"] for n in notifs}
except Exception as e:
print(f"WARN: {method} {path}: {e}", file=sys.stderr, flush=True)
return None
print(
f"WARN: Gitea API failed: {e}", file=sys.stderr, flush=True
)
return set()
def needs_bot_response(repo_full, issue_number):
"""True if the bot is NOT the author of the most recent comment."""
comments = gitea_api("GET", f"/repos/{repo_full}/issues/{issue_number}/comments")
if comments and len(comments) > 0:
if comments[-1].get("user", {}).get("login") == BOT_USER:
return False
def wake_openclaw(count):
text = (
f"[Gitea Notification] {count} new notification(s). "
"Check your Gitea notification inbox via API, process them, "
"and mark as read when done. "
"Route all output to Gitea comments or Mattermost #git/#claw. "
"Do NOT reply to this session — respond with NO_REPLY."
)
payload = json.dumps({"text": text, "mode": "now"}).encode()
req = urllib.request.Request(
f"{GATEWAY_URL}/hooks/wake",
data=payload,
headers={
"Authorization": f"Bearer {HOOK_TOKEN}",
"Content-Type": "application/json",
},
method="POST",
)
try:
with urllib.request.urlopen(req, timeout=5) as resp:
status = resp.status
print(f" Wake responded: {status}", flush=True)
return True
def is_actionable(notif):
"""Returns (actionable, reason, issue_number)."""
subject = notif.get("subject", {})
repo = notif.get("repository", {})
repo_full = repo.get("full_name", "")
url = subject.get("url", "")
number = url.rstrip("/").split("/")[-1] if url else ""
if not number or not number.isdigit():
return False, "no issue number", None
issue = gitea_api("GET", f"/repos/{repo_full}/issues/{number}")
if not issue:
return False, "couldn't fetch issue", number
assignees = [a.get("login") for a in (issue.get("assignees") or [])]
if BOT_USER in assignees:
if needs_bot_response(repo_full, number):
return True, f"assigned to {BOT_USER}", number
return False, "assigned but already responded", number
issue_body = issue.get("body", "") or ""
if f"@{BOT_USER}" in issue_body and issue.get("user", {}).get("login") != BOT_USER:
if needs_bot_response(repo_full, number):
return True, f"@-mentioned in body", number
comments = gitea_api("GET", f"/repos/{repo_full}/issues/{number}/comments")
if comments:
last = comments[-1]
if last.get("user", {}).get("login") == BOT_USER:
return False, "own comment is latest", number
if f"@{BOT_USER}" in (last.get("body") or ""):
return True, f"@-mentioned in comment", number
return False, "not mentioned or assigned", number
def spawn_agent(repo_full, issue_number, title, subject_type, reason):
dispatch_key = f"{repo_full}#{issue_number}"
if dispatch_key in dispatched_issues:
return
dispatched_issues.add(dispatch_key)
repo_short = repo_full.split("/")[-1]
job_name = f"gitea-{repo_short}-{issue_number}-{int(time.time())}"
msg = (
f"Gitea: {reason} on {subject_type} #{issue_number} "
f"'{title}' in {repo_full}.\n"
f"API: {GITEA_URL}/api/v1 | Token: {GITEA_TOKEN}\n"
f"SCOPE: Only {subject_type} #{issue_number} in {repo_full}.\n"
f"Read all comments, do the work, post results as Gitea comments."
)
try:
subprocess.run(
[OPENCLAW_BIN, "cron", "add",
"--name", job_name, "--at", "1s",
"--message", msg, "--delete-after-run",
"--session", "isolated", "--no-deliver",
"--thinking", "low", "--timeout-seconds", "300"],
capture_output=True, text=True, timeout=15,
)
except Exception as e:
print(f"Spawn error: {e}", file=sys.stderr, flush=True)
dispatched_issues.discard(dispatch_key)
print(
f"WARN: Failed to wake OpenClaw: {e}",
file=sys.stderr,
flush=True,
)
return False
def main():
print(f"Poller started (poll={POLL_DELAY}s, cooldown={COOLDOWN}s)", flush=True)
seen_ids = set(n["id"] for n in (gitea_api("GET", "/notifications?status-types=unread") or []))
last_dispatch = 0
last_assign_scan = 0
check_config()
print(
f"Gitea notification poller started (delay={POLL_DELAY}s)",
flush=True,
)
last_seen_ids = gitea_unread_ids()
print(
f"Initial unread: {len(last_seen_ids)} notification(s)", flush=True
)
while True:
time.sleep(POLL_DELAY)
now = time.time()
# Notification polling
notifs = gitea_api("GET", "/notifications?status-types=unread") or []
current_ids = {n["id"] for n in notifs}
new_ids = current_ids - seen_ids
if new_ids and now - last_dispatch >= COOLDOWN:
for n in [n for n in notifs if n["id"] in new_ids]:
nid = n.get("id")
if nid:
gitea_api("PATCH", f"/notifications/threads/{nid}")
is_act, reason, num = is_actionable(n)
if is_act:
repo = n["repository"]["full_name"]
title = n["subject"]["title"][:60]
stype = n["subject"].get("type", "").lower()
spawn_agent(repo, num, title, stype, reason)
last_dispatch = now
seen_ids = current_ids
current_ids = gitea_unread_ids()
new_ids = current_ids - last_seen_ids
# Assignment scan (less frequent)
if now - last_assign_scan >= ASSIGNMENT_INTERVAL:
for repo in WATCHED_REPOS:
for itype in ["issues", "pulls"]:
items = gitea_api("GET",
f"/repos/{repo}/issues?state=open&type={itype}"
f"&assignee={BOT_USER}&sort=updated&limit=10") or []
for item in items:
num = str(item["number"])
if f"{repo}#{num}" in dispatched_issues:
if not new_ids:
last_seen_ids = current_ids
continue
# Only recently updated items (5 min)
# ... add is_recently_updated() check here
if needs_bot_response(repo, num):
spawn_agent(repo, num, item["title"][:60],
"pull" if itype == "pulls" else "issue",
f"assigned to {BOT_USER}")
last_assign_scan = now
ts = time.strftime("%H:%M:%S")
print(
f"[{ts}] {len(new_ids)} new notification(s) "
f"({len(current_ids)} total unread), waking agent",
flush=True,
)
wake_openclaw(len(new_ids))
last_seen_ids = current_ids
if __name__ == "__main__":
@ -455,15 +368,13 @@ This applies to everything: project rules ("no mocks in tests"), workflow
preferences ("fewer PRs, don't over-split"), corrections, new policies.
Immediate write to the daily file, and to MEMORY.md if it's a standing rule.
### Sensitive Output Routing
### PII-Aware Output Routing
A lesson learned the hard way: **the audience determines what you can say, not
who asked.** If the human asks for a medication status report in a group
channel, the agent can't just dump it there — other people can read it. The
rule: if the output would contain sensitive information (PII, secrets,
credentials, API keys, operational details like flight numbers, locations,
travel plans, medical info, etc.) and the channel isn't private, redirect to DM
and reply in-channel with "sent privately."
rule: if the output would contain PII and the channel isn't private, redirect to
DM and reply in-channel with "sent privately."
This is enforced at multiple levels:
@ -494,7 +405,7 @@ The heartbeat handles:
- Periodic memory maintenance
State tracking in `memory/heartbeat-state.json` prevents redundant checks (e.g.,
don't re-check notifications if you checked 10 minutes ago).
don't re-check email if you checked 10 minutes ago).
The key output rule: heartbeats should either be `HEARTBEAT_OK` (nothing to do)
or a direct alert. Work narration goes to a designated status channel, never to
@ -1506,8 +1417,7 @@ stay quiet.
## Inbox Check (PRIORITY)
(check whatever notification sources apply to your setup — e.g. Gitea
notifications, emails, issue trackers)
(check notifications, issues, emails — whatever applies)
## Flight Prep Blocks (daily)
@ -1541,9 +1451,10 @@ Never send internal thinking or status narration to user's DM. Output should be:
```json
{
"lastChecks": {
"gitea": 1703280000,
"email": 1703275200,
"calendar": 1703260800,
"weather": null
"weather": null,
"gitea": 1703280000
},
"lastWeeklyDocsReview": "2026-02-24"
}
@ -1571,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):
@ -1712,24 +1665,21 @@ Never lose a rule or preference your human states:
---
## Sensitive Output Routing — Audience-Aware Responses
## PII Output Routing — Audience-Aware Responses
A critical security pattern: **the audience determines what you can say, not who
asked.** If your human asks for a sitrep (or any sensitive info) in a group
asked.** If your human asks for a sitrep (or any PII-containing info) in a group
channel, you can't just dump it there — other people can read it.
### AGENTS.md / checklist prompt:
```markdown
## Sensitive Output Routing (CRITICAL)
## PII Output Routing (CRITICAL)
- NEVER output sensitive information in any non-private channel, even if your
human asks for it
- This includes: PII, secrets, credentials, API keys, and sensitive operational
information (flight numbers/times/dates, locations, travel plans, medical
info, financial details, etc.)
- If a request would produce any of the above in a shared channel: send the
response via DM instead, and reply in-channel with "sent privately"
- NEVER output PII in any non-private channel, even if your human asks for it
- If a request would produce PII (medication status, travel details, financial
info, etc.) in a shared channel: send the response via DM instead, and reply
in-channel with "sent privately"
- The rule is: the audience determines what you can say, not who asked
- This applies to: group chats, public issue trackers, shared Mattermost
channels, Discord servers — anywhere that isn't a 1:1 DM
@ -1738,10 +1688,10 @@ channel, you can't just dump it there — other people can read it.
### Why this matters:
This is a real failure mode. If someone asks "sitrep" in a group channel and you
respond with medication names, partner details, travel dates, hotel names, or
API credentials — you just leaked all of that to everyone in the channel. The
human asking is authorized to see it; the channel audience is not. Always check
WHERE you're responding, not just WHO asked.
respond with medication names, partner details, travel dates, and hotel names —
you just leaked all of that to everyone in the channel. The human asking is
authorized to see it; the channel audience is not. Always check WHERE you're
responding, not just WHO asked.
---

File diff suppressed because it is too large Load Diff