OpenClaw production runbook template: what to record before Gateway handover

Published May 24, 2026 · OpenClawBlog Team

An incoming operator should not have to reconstruct a Gateway from shell history. “The Gateway is running” is a status update, not a handover. It does not say which host is serving requests, how clients authenticate, which agent they can reach, what that agent can change, or what happens after the next restart.

The official Gateway exposure runbook already names most of the inventory needed before changing network or channel policy: the host, state directory, bind mode, authentication source, channels, reachable agents, tools, sandbox settings, credentials, and backup location. This guide turns that inventory into a handover record with evidence and stop conditions.

The command sequence below is documentation-derived. No local OpenClaw Gateway test is claimed. Proposed checks are labelled as such, and the source links describe documented behavior rather than proving that a particular installation is healthy.

The handover gate

A useful runbook lets the next operator answer five questions without asking the departing operator to remember anything:

Question	Record	Evidence of readiness
Which Gateway is this?	Host, OS user, profile, version, config path, state directory, workspace, port, and service owner.	A status result that identifies the intended instance.
How can it be reached?	URL, bind mode, network path, authentication mode, secret reference, firewall or proxy boundary.	One authorized probe and one rejected or unauthorized probe.
What can it touch?	Channels, routes, agents, tools, plugins, workspaces, browser or node access, credentials, and approvals.	An authority matrix with exceptions explained.
Is it healthy?	Timestamped Gateway, channel, model, audit, and log checks.	Observed output, expected output, warnings, and accepted residual risk.
How do we change or recover it?	Restart owner, backup artifact, rollback target, escalation contact, and stop conditions.	A documented recovery path that does not depend on the departing operator.

This is a proposed operating gate based on the documentation. A secret should never be copied into the runbook. Record the name of the secret, where it is stored, who can rotate it, and when it was last checked.

Collect the evidence before writing the summary

Use the account and profile that own the Gateway. If the Gateway is remote, run the service and state checks on the host that actually runs it. The configuration reference describes the normal config file as JSON5 and points to openclaw config schema for the live schema, including bundled and plugin metadata.

A proposed read-only evidence pass is:

openclaw --version
openclaw config schema
openclaw gateway status --deep --json
openclaw status --deep
openclaw health --json
openclaw channels status --probe
openclaw doctor
openclaw security audit --deep

Save the outputs in a dated evidence bundle with secrets removed. Keep the command, timestamp, selected profile, and exit result together. The distinction between similar commands matters. The Gateway runbook says gateway status --deep performs extra service discovery. It is not a deeper RPC health probe. openclaw status --deep asks the running Gateway for a live probe and can include per-account channel probes.

Do not treat an empty or redacted field as proof that a capability is absent. Record “not observed,” “not configured,” or “not tested” when that is what the evidence shows.

1. Identify the exact Gateway and its owner

Start the runbook with an identity block:

Instance and profile name.
Host name, operating system, and OS account.
OpenClaw version or source revision.
Active config path, state directory, and workspace paths.
Gateway bind mode, port, and operator URL.
Service manager and lifecycle owner.
Last verified timestamp and the operator who performed the check.

The default Gateway port is 18789, and the normal state location is ~/.openclaw, but neither should be assumed during a handover. A profile, environment override, custom state directory, or external supervisor can change the target.

Record the service manager explicitly. The documented options include a macOS LaunchAgent, a Linux systemd user service, or a native Windows Scheduled Task. A container platform or another supervisor may own the lifecycle instead. The important question is not which command looks familiar; it is who is allowed to stop, start, restart, and replace the running service.

If more than one Gateway is intentional, record a separate port, config path, state directory, and workspace for each instance. The Gateway runbook recommends gateway probe when several reachable identities may be present. A handover should say which identity is expected and what the operator should do if another one answers.

2. Map access and the trust boundary

Record the full route from operator to Gateway. That may be loopback with an SSH tunnel, Tailscale, a private LAN or tailnet bind, or a trusted reverse proxy. The exposure guidance recommends the narrowest pattern that satisfies the workflow and warns against direct public port forwarding.

Include the URL a new operator should use, the bind mode, the firewall or proxy rule, the authentication mode, and a reference to the token or password source. Do not write the token itself. SSH is a transport path, not an authentication bypass. The Gateway documentation says clients still need to satisfy Gateway authentication through an SSH tunnel.

Remote checks need their own note. The remote access reference says a CLI --url does not automatically reuse implicit config or environment credentials. If a probe uses an explicit URL, show the approved credential source in the runbook and keep the actual value outside it. A safe validation shape is:

openclaw gateway probe --url ws://127.0.0.1:18789 --token $OPENCLAW_GATEWAY_TOKEN

Also record every enabled channel account and its admission rules. Include whether it accepts direct messages, groups, or webhooks; its pairing or allowlist policy; mention requirements; and the agent selected by each route.

OpenClaw documents one trust boundary per Gateway. It is intended for one operator or a mutually trusting team, not for mutually adversarial users sharing one agent or Gateway. If the people using the system do not share trust in the same credentials, files, sessions, and tools, the runbook should record the separate Gateway, OS user, or host boundary instead of presenting labels or session names as isolation.

3. Record authority, not feature names

“The support agent has access to Slack” is too vague to operate. For each reachable agent, create a small authority row containing:

Field	What to write down
Identity	Agent id, purpose, inbound channels, and route or binding.
State	Workspace, agent directory, session scope, model route, and provider profile.
Execution	Sandbox mode, scope, backend, workspace access, tool profile, allow and deny rules, and approval policy.
Reach	Host filesystem, browser profiles, paired nodes, MCP servers, external services, and outbound messaging.
Ownership	Credential owner, extension owner, update path, and the person who approves exceptions.

The sandbox and tool-policy reference separates three controls that are often collapsed into one word. Sandboxing decides where tools run. Tool policy decides which tools are available. Elevated mode is an exec-specific escape hatch and does not grant a denied tool.

For each agent, record the effective result rather than only the configured defaults. The documented inspector can show this with openclaw sandbox explain --json. Include the mode, scope, workspace access, effective allow and deny rules, and elevated gates. If the policy allows exec, do not call the agent read-only merely because write tools are denied; shell commands can still produce side effects.

List enabled plugins, skills, and MCP servers with their source, version or revision, declared purpose, update owner, and removal path. Add disabled but installed components when they can be reactivated by configuration. This inventory is a proposed handover practice. It gives the next operator enough context to interpret the results from doctor and the deep security audit.

4. Attach a health snapshot with its limits

Health evidence should include both the command and the scope of what it proves:

openclaw status --deep is a live Gateway probe and may include channel-account probes.
openclaw health --json is a machine-readable Gateway health snapshot over WebSocket.
openclaw channels status --probe checks channel readiness when the Gateway is reachable.
openclaw doctor checks Gateway, channel, plugin, skill, model-routing, state, and configuration issues.
openclaw security audit --deep adds deeper security checks, including plugin and skill code-safety checks documented by the audit reference.

The health documentation gives two cautions worth putting directly into the runbook. Stored session rows are not socket liveness. A provider can reconnect and appear healthy before a new session row exists. Also, the top-level health session summary represents the default agent, or the first configured agent when there is no default. It is not a fleet-wide total.

Channel connectivity and inbound admission are separate failure domains. A channel may still send replies while its durable ingress queue is unavailable. Record whether the evidence covers outbound transport, inbound admission, or both. If the handover requires message delivery, include an approved synthetic inbound test and its expected route. That is a proposed test, not a claim made by the health command alone.

Record the active log path and how to follow it. The logging reference documents openclaw logs --follow, default file logs under /tmp/openclaw, macOS LaunchAgent logs under ~/Library/Logs/openclaw, Linux user-service logs through journalctl, and Windows Scheduled Task inspection. The runbook should name the actual path for the selected profile and state that log output may still contain sensitive information.

5. Document normal changes and recovery

For a managed service, the normal restart instruction should be openclaw gateway restart. The Gateway runbook specifically advises against replacing restart with a chained stop and start. Record the expected health result, the maximum wait, and the service owner who can intervene if the restart fails.

A scheduled restart request is not proof that the successor is healthy. The service reference distinguishes accepted restart requests from a completed health check. If the result is restart-health-failed, the next operator should stop and inspect the service, logs, configuration, and target identity before attempting another activation.

For remote mode, document that a failed health check does not install or restart a local service. Recovery belongs on the remote host. If an external supervisor owns the Gateway, write down the supervisor's command path and escalation contact. Do not let two lifecycle owners repair the same profile and port.

Before a significant update or configuration change, record the backup artifact and its verification result. The backup guide documents a verified full archive with:

openclaw backup create --output ~/Backups/openclaw --verify

The archive can include state, configuration, credentials, configured agent directories, and workspaces. Custom agent roots outside the default state directory still matter. Backups are sensitive records, so the runbook should record their protected location, retention rule, encryption or access control, and the person responsible for rotation without exposing their contents.

Do not describe a package copy as a complete recovery point. The rollback documentation says a package downgrade does not reverse configuration or database migrations. A complete recovery point must match the package or source revision and include the relevant configuration, global and per-agent databases, workspaces, credentials, and retained originals. The backup archive does not contain the package itself.

Failure paths the handover must make explicit

The service says running, but replies do not arrive

Start with the health sweep, not a blind restart: openclaw status, openclaw models status, openclaw channels status, and openclaw logs --follow. Check the model credential state, channel admission policy, remote tunnel, and WebSocket path. Record which layer failed. “Gateway up” only answers one part of the problem.

The channel looks connected, but inbound work is missing

Check channel status with a live probe and inspect the logs for ingress or dead-letter information. Do not conclude that the provider socket proves message admission. If the channel sends but does not receive, the runbook should direct the operator to the channel's queue and account state before relinking credentials.

A remote operator receives unauthorized

Confirm the URL, profile, auth mode, and credential source. An explicit remote URL may not reuse the local config credential, and an SSH tunnel still requires Gateway authentication. The operator should be able to rotate or reload the credential through its approved secret path without editing the runbook.

A restart reaches the wrong process

Run openclaw gateway status --deep and openclaw gateway probe. Compare the returned identity with the recorded host, port, config path, state directory, and profile. If multiple Gateways are intentional, each needs its own paths and lifecycle owner. If they are not intentional, stop and resolve the duplicate before changing configuration.

The Gateway may be overexposed

Use the rollback sequence from the exposure runbook: stop public forwarding, return to loopback where possible, disable risky channel admission, remove unexpected wildcard entries, rotate Gateway and affected integration credentials, review audit logs and tool calls, and rerun the deep audit. The handover must name who can authorize re-enabling access.

A copyable handover template

OpenClaw Gateway handover
Recorded at:
Instance and profile:
Host and OS user:
OpenClaw version or source revision:
Config path:
State directory:
Workspace and agent directories:
Service manager and lifecycle owner:
Bind, port, operator URL:
Auth mode and secret reference:
Secret rotation owner:
Channels, accounts, and admission rules:
Agent routes and session scopes:
Tools, sandbox, elevated policy, and approvals:
Plugins, skills, and MCP inventory:
Health evidence paths and timestamps:
Accepted warnings and owners:
Last verified backup and recovery test:
Normal restart command:
Rollback target and stop conditions:
Escalation contact:
Handover accepted by:

Keep this template next to the evidence, not instead of it. A link to a log file without a timestamp is weak evidence. A backup path without a verification result is an intention. A tool label without its effective policy is not an authority map.

When not to hand over yet

Pause the handover when the target process cannot be identified, the service owner is unclear, the authentication path is ambiguous, or a second Gateway answers unexpectedly. Pause when critical audit findings are unexplained, when the only backup is an unverified live database copy, or when no one has a tested path for a migration-related rollback.

Also pause when the Gateway serves people with materially different trust levels but the runbook presents separate sessions as tenant isolation. Split the deployment or narrow the audience first. The same applies when the runbook contains raw tokens, channel credentials, private transcripts, or copied log lines that expose sensitive data.

The useful test is simple: can the next operator identify the intended Gateway, see its real authority, reproduce the health check, restart it through the correct owner, and recover it without guessing? If not, the Gateway may be running, but the handover is incomplete.

Sources

Official documentation pages were accessed on 2026-09-13. Publication dates were not stated on the opened documentation pages.