OpenClaw Webhooks and Ollama on a Cloud Mac in 2026: Tokens, Routes, and Troubleshooting

Hooking external systems into OpenClaw is where automation graduates from “CLI demo” to “always-on teammate.” In 2026 the supported pattern is an HTTP gateway that exposes /hooks/* endpoints protected by shared secrets, while Ollama on Apple Silicon gives you a local model path that keeps HTML/CSS refactors inside the LAN—if the wiring is correct. This article walks through enabling webhooks, choosing wake versus agent routes, validating Ollama from the same Mac that runs the gateway, and fixing the errors that still show up in GitHub issues after upgrades.

Enable hooks and secrets safely

Upstream docs describe enabling webhooks with hooks.enabled: true plus a token the gateway checks on every POST. Prefer Authorization: Bearer <token>; alternative headers such as x-openclaw-token exist for legacy clients. Do not place the secret in query parameters—those show up in access logs and browser histories.

After editing configuration, restart the gateway daemon and confirm the listener binds to 127.0.0.1 until a reverse proxy terminates TLS in front. Pair this section with the production hardening guide before you expose anything past your laptop.

/hooks/wake vs /hooks/agent

Think of POST /hooks/wake as “poke the system” events—CI finished, calendar reminder fired, or a CMS webhook wants the agent to poll a folder. POST /hooks/agent targets an isolated run with tighter blast radius, useful when untrusted JSON arrives from a partner integration.

Route	Typical payload	When to use
/hooks/wake	Lightweight signal + metadata	Scheduled jobs, repo push hooks
/hooks/agent	Task body + tool hints	Per-ticket automation from Jira/Linear

Copy-paste curl examples

From any host that can reach the gateway (often via SSH tunnel), run:

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"}'

Swap the URL for your loopback tunnel (https://127.0.0.1:8443/hooks/wake) during local testing. Expect HTTP 204 or 200 with a JSON body; immediate 401 means the bearer token mismatched, while 404 usually means the gateway binary is too old or the path is misspelled—double-check trailing slashes because some proxies normalize them differently.

Agent-scoped tests look nearly identical—only the path changes:

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"}'

Pipe responses through jq to assert .status == "accepted" in CI. If your load balancer terminates HTTP/2, watch for duplicate POST retries: idempotent handlers should detect the same build id within a 5-minute window and short-circuit to avoid double-running expensive Ollama prompts.

Ollama on M-series: ports, models, fallbacks

Ollama listens on 127.0.0.1:11434 by default. From the same Mac running OpenClaw, verify the daemon sees your model catalog:

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

Pin models using raw IDs like qwen2.5:7b inside openclaw.json; vague aliases make the scheduler fall back to cloud APIs. If you recently followed the npm versus Docker deployment guide, ensure the container or global install shares the same network namespace as Ollama—Docker users may need host.docker.internal:11434 instead of localhost.

Throughput tip: Apple Silicon Mac mini nodes often sustain 35–50 tok/s on 7B-class models with unified memory; budget 8 GB RAM minimum for the model weights plus the Node gateway footprint.

Distinguish the native Ollama API from the OpenAI-compatible surface on /v1: tool-calling fidelity differs, and OpenClaw’s planner may choose one transport based on your provider string. When in doubt, test both with a five-line JSON tool schema and watch whether the model returns structured arguments or plain prose. Document the winning combination beside your webhook runbook so the next on-call engineer does not rediscover the mismatch at 2 a.m.

Known 2026 failure modes

1. HTTP 404 after a “successful” Ollama completion. Track upstream issues: the agent run finishes but the callback route returns not found. Mitigation: upgrade to the latest patch release and confirm your reverse proxy forwards /hooks/* verbatim.
2. Custom headers stripped on Ollama streams. Protected endpoints that require X-OLLAMA-KEY may 403 if an older build drops headers during internal streaming. Update or inject headers at the proxy until your version includes the forwarding fix.
3. Anthropic traffic despite Ollama config. Run curl from the gateway environment, not only your shell, to catch firewall gaps. Set agents.defaults.model.primary to an explicit ollama/model:tag string and watch logs for fallback warnings.
4. Tool schema rejections on tiny models. Some Gemma-scale checkpoints return HTTP 400 when tools are attached; OpenClaw may auto-retry without tools—plan simpler tasks for small local models.

Capture gateway + Ollama logs side by side for thirty seconds when reproducing any of the above; correlating timestamps across processes usually reveals whether the failure is network, auth, or model-side in under one iteration.

Why stage on a rented Mac mini

Webhooks plus local inference generate always-on processes: gateway, Ollama, and occasionally a browser skill. A cloud Mac mini keeps that load off your laptop battery, preserves macOS file paths OpenClaw plugins expect, and lets you snapshot a known-good openclaw.json before risky upgrades. When an experiment blows up, reprovision faster than reclaiming a shared office machine.

Combine SSH for log tailing with occasional VNC if you must click through macOS privacy prompts for screen-recording skills—same node, two access modes, zero extra hardware purchase.

Operational metrics worth logging: webhook acceptance rate (target 99.5% weekly), p95 latency from POST to first agent log line (often 300–800 ms on LAN), and Ollama queue depth. Alert when 429 responses from cloud providers spike—that usually means your hook fan-out triggered too many parallel agent runs; throttle with a simple semaphore in CI or stagger cron entries by 30–60 seconds.

For HTML/CSS repositories, point skills at the same working tree your static build uses so webhook-triggered diffs stay reviewable in one pull request. A common layout keeps the repo under /Users/build/workspace/site on the cloud Mac, with .openclawignore excluding node_modules and dist to keep context windows lean—similar to the optimization patterns described in earlier OpenClaw cost posts on this blog.

When you bridge Slack or Microsoft Teams, rotate the signing secret quarterly and store it in the macOS Keychain via security add-generic-password rather than plaintext shell exports. That single habit prevents accidental leaks during screen shares when someone runs env | grep OPENCLAW for debugging.

FAQ

Why do I see HTTP 404 after a successful Ollama run?

Some gateway builds mishandle post-run callbacks when Ollama is the provider. Update OpenClaw, confirm the webhook URL path matches the documented /hooks/* routes, and capture gateway logs around the response phase.

Are query-string tokens allowed?

Current guidance rejects secrets in query strings; use Authorization: Bearer or the x-openclaw-token header instead.

Why would OpenClaw call Anthropic when Ollama is configured?

Model discovery can fall back if the primary string is not a valid ollama/ reference or the daemon is unreachable from the gateway process. Verify connectivity with curl and pin agents.defaults.model.primary explicitly.

Renting Apple Silicon capacity from MacHTML means you can keep webhook endpoints and Ollama models warm 24/7 without thermal throttling your personal MacBook. That stability translates into fewer missed CI hooks and predictable token latency when agents rewrite HTML or CSS across large repos. Treat the rented node as production-like staging: freeze dependency versions for a week after each successful hook drill, then schedule upgrades deliberately.