2026_OPENCLAW
INSTALL_SH_
CHANNEL_PROBE_
SECURITY_REMOTE.

I. Why “it runs on my laptop” still fails the first production sign-off

Community snippets optimize for dopamine: you paste a command, see a banner, and assume the hard part is finished. Production failures rarely announce themselves as compile errors. They arrive as silence: the gateway process is alive, metrics look flat, yet no first customer-visible message ever lands in the channel you promised. The usual root cause is ordering, not model quality. Teams wire channels before openclaw doctor proves that provider credentials, listen addresses, and reverse-proxy paths line up. The channel layer swallows mismatches instead of throwing a crisp stack trace. A second failure mode is narrative drift between what openclaw init created and what launchd actually executes: WorkingDirectory, log locations, and upgrade scripts each tell a different story until a single reboot turns troubleshooting into archaeology. A third failure mode is security as folklore: without openclaw security audit, bind surfaces, token file modes, and ClawHub skill provenance live inside one engineer’s chat history. When that engineer goes on holiday, the system regresses from “works” to “nobody dares touch it.” This article keeps only a handful of large sections on purpose. Each section is long enough to paste into an internal wiki as a single narrative block rather than exploding into a dozen micro-posts nobody finishes reading.

Translate those symptoms into governance language and you get missing sign-off criteria: reviewers cannot tell what “green” means, and on-call engineers cannot tell which layer to roll back first. The thread through the rest of this piece is the official chain install.sh → init → doctor → channels probe → security audit, with remote Mac OPENCLAW_* parity treated as part of the same evidence bundle. The goal is to answer auditors with attachments, not screenshots assembled the night before a review.

II. Picking an install path without turning it into a tribal religion

The decision is not which stack looks modern on a slide deck but which stack your future self can reproduce twelve months from now with the same digest pins and the same attachments. Official install.sh encodes ordering and guardrails directly in the script, which reduces the chance that a newcomer wires channels before a workspace exists. Global npm or pnpm installs are fine for teams that already treat Node majors as infrastructure contracts, but you must co-locate PATH rules, permission boundaries, and rollback notes on the same runbook page; otherwise muscle memory quietly becomes production configuration. Docker Compose often wins on auditability and isolation, yet it forces you to design acceptance tests for volumes, bridge networks, and host-channel bridging before the team even understands gateway behavior; layering containers on top of confusion multiplies triage time rather than shrinking it.

Whichever path you pick, freeze the Node major, the package manager, and a ban on undocumented curl flags inside README. Cross-read the npm/Docker/pnpm matrix article on this site and capture a single team resolution about the canonical delivery path instead of letting three laptops invent three religions.

Once the path is chosen, spend an hour writing the failure modes you refuse to rediscover: what happens when a provider rotates TLS roots, when a teammate upgrades Node without updating CI, when a reverse proxy adds a default idle timeout that kills long-lived websocket upgrades, when disk pressure on a remote Mac slows log rotation enough to hide errors until customers notice first. Those paragraphs belong beside the matrix table because they are how senior engineers quietly de-risk launches. They also become the seed content for your first tabletop exercise: revoke a test token on purpose, rerun probes, confirm paging fires, restore credentials, capture timestamps, and attach the transcript next to the production runbook so auditors see humans practicing the path instead of only reading it.

III. Five steps from an empty directory to a defensible first message

Treat the following list as a ticket attachment checklist, not a motivational poster. If a step cannot emit a savable log or text artifact, the step is not done. That discipline pays rent the first time you promote an environment from a personal laptop to a shared remote Mac or hand the pager to someone who was not in your private chat thread when the cluster was born.

1. Freeze Node and directory boundaries: dedicate a directory for the gateway, document which PATH segments belong to OpenClaw, and prevent accidental overlap with other CLI toolchains in the home directory.
2. Run official install.sh and record its digest: write download URL, verification command, and expected hash into the runbook; reject verbal “just add this flag” shortcuts because they cannot be re-verified by the next engineer.
3. openclaw init: confirm workspace, configuration, and memory directories materialize together; redact secrets before committing templates and record both “minimal runnable” and “production delta” columns.
4. openclaw doctor as a hard gate: forbid production channels until doctor passes; store the raw doctor output as a CI artifact or acceptance attachment instead of cropping screenshots.
5. channels probe plus a canned first message: probe before inviting humans; use fixture text so debug noise is not mistaken for success.

After the five steps you should be able to answer three blunt questions: which version is installed, which directory is authoritative, and whether channel handshakes were validated independently of your optimism. If you cannot answer them, you executed motion without evidence; pause feature work and repair the chain first.

IV. Layered triage when channels go quiet

Silence tempts people to tweak models or crank concurrency. A calmer sequence is provider health, then gateway routing and bind addresses, then channel adapters and callback URLs. channels probe logs should state whether credentials expired, whether webhooks are reachable, whether socket mode still needs a tunnel you forgot to renew, and whether the gateway binds the interface you believe it binds. Read the 429 and logging article alongside this section so you can separate rate limits from “dead air” handshakes: throttles usually emit explicit HTTP codes or provider errors, whereas DNS skew, clock skew, or reverse-proxy idle timeouts masquerade as flaky silence.

When HTTP orchestration tools such as n8n sit in front of OpenClaw, orchestrator idempotency and signatures do not replace gateway probes. Keep layered attachments in the ticket instead of merging unrelated logs into one file; otherwise the next postmortem wastes hours proving whether retries flooded an internal queue or the gateway dropped events on its own.

Load and cost controls belong in the same story: burst tests should use isolated provider projects and synthetic channels, recording CPU, memory, and open file descriptors while ramping traffic. Poisoning production channels with synthetic floods earns the pager storm you deserve. On Apple Silicon hosts that also run other AI services, compare results with the concurrency article’s discussion of unified memory pressure so you do not misread thermal throttling as a logic bug. Set token ceilings and requests-per-minute limits on dashboards next to probe failure rates, and tune alerts so they fire when both cost and error signals breach thresholds—alert fatigue from noisy probes is how real regressions hide in plain sight.

V. security audit, workspace permissions, and the provider vacuum

openclaw security audit should cover listen addresses, token file modes, ClawHub skill provenance with pinning and diffs, and whether reverse proxies, Tailscale, or SSH tunnels match the written architecture. Cross-read the gateway attack-surface article and map every finding to an owner and due date instead of treating audit output as a weekend cleanup list. On remote Macs, include screen sharing and file sharing in the same operational story as the gateway port; attackers and auditors alike care about adjacent exposure. Workspaces created by init often contain secret placeholders and memory files: document Unix permissions and group policy, which service accounts may read them, whether CI uses read-only images, and whether developer laptops may write production paths. Treat multi-user-readable secrets as release blockers, not warnings. On multi-tenant remotes, prefer separate OS users per gateway instance instead of shared sudo habits.

Between doctor and probe sits an easy-to-ignore provider vacuum: billing state, organization policy, IP allow-lists, egress IP registration, and key rotation dates. Remote egress IPs differ from developer laptops; pre-register them in provider consoles or you will chase intermittent greens that fail only under production traffic. Put egress IP changes in the same change-management class as plist edits so operations and application engineers review both sides of the boundary together.

Rotation deserves its own paragraph in the runbook, not a sticky note: create a secondary token, deploy side-by-side, flip the provider console, probe twice with fixtures, revoke the old token, rerun audit, and store the rotation ticket beside the plist merge request. Teams that rotate by editing live plist files without a second copy have already written the outage postmortem in advance. Legal and retention hooks matter even for small teams—document which jurisdictions data may traverse per channel and how long logs persist, then reference those policies inside audit summaries so compliance reviews are not invented after a regulator asks. When marketing wants a “beta” badge, define GA as seven consecutive days of green probes on fixtures, a clean audit or signed waivers, a trained secondary owner, and a successful restore drill; anything less is just a louder form of technical debt.

VI. Remote launchd, thresholds, observability, and how MACGPU fits the story

On a shared remote Mac, spell out whether OPENCLAW_* and model secrets arrive from plist EnvironmentVariables, EnvironmentFiles, or a secrets manager. After upgrades, diff plists before suspecting application code. Split administrative SSH from public webhook ingress per the SSH/VNC selection guide so firewall rules are not “mostly right” in verbal form. Upgrade windows should follow a fixed order: snapshot plist and a redacted workspace manifest, run doctor, then touch channel configuration. Stuffing provider routing changes into the same change ticket as a gateway upgrade multiplies variables and makes rollback ambiguous.

Observability should standardize five attachments: doctor output, raw probe logs, audit summary, redacted launchd plist, and provider event identifiers or masked console screenshots. External demos or customer bridges need at least the first three or “it worked once” is not reproducible. Quarterly cold-start drills that rely only on the public runbook plus internal mirrors expose stale links and missing credentials faster than any linter; feed those gaps into the backlog ahead of net-new features.

Add a nightly automation job that boots a disposable directory, installs from the pinned digest, runs doctor, and uploads logs as build artifacts. When CI doctor diverges from production doctor, you want automation—not a customer—to discover the drift at three in the morning. Keep CI Node majors aligned with production majors; silent jumps recreate “works on my machine” even when both sides are arm64. Track non-vanity metrics such as probe success fraction, median time-to-first-token after an inbound event, and audit finding counts over time; avoid dashboards that only show uptime without defining the signal that counts as up. Pair gateway metrics with provider quota metrics so throttles are distinguishable from silence.

Laptops are great for validation and exploration but poor as the sole front door for customer-facing demos because sleep, PATH noise, and browser proxies distort behavior. Remote Macs offer dedicated launchd, pinned versions, and shared attachments. If you need always-on Apple Silicon capacity for gateways and regression instead of turning a personal machine into a closet server, MACGPU publishes plans and help entry points without forcing a login wall. Final self-check before any external demo: doctor, probe, and audit artifacts are all present; skipping one is how silent regressions return on stage.