Temporal gives you durable execution, yet activities that call OpenClaw still need the same operational spine as any other HTTP client: a gateway tool whitelist, honest heartbeat boundaries, and compact failure summaries that workflows can merge without importing full agent transcripts. This runbook targets a dedicated remote Mac where the worker, gateway, and models may or may not share a loopback interface.

Continue from Agno gateway whitelist, sessions_spawn failure relay, and Task Brain identity splits so orchestration and audit lines stay aligned.

On this page: Pain points · Loopback versus tunnel · Worker identity · Retry policy · Secrets injection · Gateway modes · Runbook steps

Three failure modes teams repeat

First, a valid Bearer still yields empty tool catalogs when HTTP or Session tools stay on default deny lists. Second, long OpenClaw calls without heartbeats let Temporal cancel while the gateway keeps working, duplicating side effects on retry. Third, tokens in workflow input replay into history and leak in exports. The sections below name each knob.

Decision matrix: loopback versus SSH tunnel to the gateway

Pick a row before you wire environment variables into the worker. The goal is a stable base URL the activity code can trust across restarts.

Mode When it fits Main risk Mitigation
Loopback Gateway listener and worker share one macOS host; you can target 127.0.0.1 with minimal hops. Port collisions with other dev services on the same tenant. Pin ports in launchd plist, document the pair beside the Temporal task queue name.
SSH local forward Gateway listens on another network namespace or remote interface; the worker should still see localhost. Tunnel drops silently; activities retry into duplicate tool calls. Health-check the tunnel from a tiny probe workflow and tie idempotency keys to workflow id plus activity attempt.
Mixed Temporal cluster is remote while OpenClaw stays on the Mac worker host. Clock skew and split-brain logs between cloud and Mac. Carry the same correlation id in Temporal search attributes and OpenClaw request headers.

Worker identity

Register the Python worker with a stable task queue per environment, a worker identity string, and a build id when you version workers. Echo the same labels in OpenClaw logs so history joins gateway lines. Split interactive queues from production so blast radius and autoscale rules stay clear.

Retry policy

Keep workflow code deterministic—no OpenClaw there. Run HTTP and tools in activities with a retry policy, tight schedule-to-start for queue pressure, and schedule-to-close above worst-case latency plus gateway wait. Mark validation and client faults non-retryable. Use capped exponential backoff so recovery does not stampede the gateway.

Secrets injection

Pass OpenClaw tokens, model URLs, and tenant ids via worker environment, sealed boot files, or a secret store the activity reads on entry—not workflow input, child payloads, or search attributes, which land in history. Rotate by restarting workers and draining in-flight activities instead of mutating secrets from replayed code.

Gateway loopback and tunnel behavior in production

Loopback suits one Mac where the worker hits the gateway on the same host. Tunnel mode uses SSH -L: the worker posts to localhost while sshd forwards to the real listener. Document the choice in the service readme—wrong-mode DNS wastes hours. Pair either path with the Agno tool whitelist so only needed invoke routes appear in the catalog.

Minimal reproducible steps

Execute in order on the remote Mac before you attach production schedules.

  1. Install Node 22 LTS, matching OpenClaw CLI, run openclaw doctor; archive stdout with the Temporal namespace.
  2. Start or tunnel the gateway; write OPENCLAW_BASE_URL to whichever loopback or forwarded port you standardized.
  3. Mint a short-lived Bearer; align Session and HTTP tool allowlists with the activities that will call tools/invoke or related paths.
  4. Wrap OpenClaw in activities with timeouts, heartbeats on long streams, and typed results workflows can branch on.
  5. Register the worker with the task queue, identity, and build id policy you documented; connect to Temporal Cloud or self-hosted endpoints over TLS.
  6. Chaos test: drop the tunnel or block the gateway port; confirm Temporal shows attempts and the activity returns a small JSON failure envelope with ids and error class, not raw HTML.
  • Citable gate: heartbeat interval should stay strictly below Temporal’s heartbeat timeout for your namespace defaults.
  • Citable gate: failure JSON should stay under a few kilobytes so workflow history remains cheap.
  • Citable gate: every OpenClaw request should log the same correlation id you emit in Temporal activity completion notes.

FAQ

Import full transcripts into workflows? No—merge summaries per the sessions_spawn note; park traces in object storage by correlation id.

Does Temporal replace gateway policy? No—Temporal handles retries and timeouts; OpenClaw still enforces tool visibility and token scope.

Skim the Tech Blog for related OpenClaw notes, open the homepage for product context, then use pricing and purchase when you need a dedicated Mac hour pool for soak tests.

Summary: Pin identity and build ids, run OpenClaw in activities with heartbeats and capped retries, inject secrets outside history, pick loopback or tunnel on purpose, align allowlists with Bearer scope, return small failure JSON for cheap durable replay.