openclaw-control-plane/docs/G2_RUNBOOK.md

G2 Runbook - Gateway/Node Pairing Preparation

Status

Draft for user authorization. G2 execution is not open yet.

This runbook is an execution-before-action checklist. It may be used only after the user explicitly authorizes G2. It does not authorize token injection, openclaw node run, VPS approval, service changes, Nginx changes, Docker changes, or any mutation by itself.

Sources Reviewed

• USER_STATUS.md
• AGENT_BOARD.md
• handoff/ORCHESTRATOR.md
• D:\openclaw\OPENCLAW_EXEC_NODE_PLAN.md
• evidence/pc-baseline-20260515.md
• evidence/vps-baseline-20260515.md
• evidence/verify-vps-baseline-20260515.md
• sync-state/heartbeat-pc.json
• sync-state/heartbeat-vps.json
• sync-state/README.md

G2 Goal

G2 prepares the OpenClaw execution path immediately before smoke testing:

• Start the Windows PC node in foreground mode and connect it to the VPS Gateway.
• Approve the pairing on the VPS/Gateway side.
• Confirm the execution plane is ready for G3 smoke testing, without running the G3 smoke test yet unless separately authorized.

G2 does not install a persistent service. G4 covers persistence later.

Current Baseline

• G0A, G0B, and G1 are complete in AGENT_BOARD.md.
• PC baseline shows OpenClaw CLI OpenClaw 2026.5.7 (eeef486), openclaw node --help availability, Tailscale availability, outbound TCP 443 success to openclaw.smartmotor.cloud, and no PC OpenClaw public port exposure.
• VPS baseline shows openclaw-gateway running healthy in Docker on services_appnet, with Gateway CLI available inside the openclaw-gateway container.
• VPS verifier accepted G1 with follow-up observations about /opt/service versus /opt/services, docker-composite.yml versus docker-compose.openclaw.yml, and the Nginx route/config anomaly.
• Sync-state files exist for PC and VPS. PC heartbeat currently reports dirty; this is expected while control-plane documents are being edited, but CORRECTION must re-check sync health before any G2 execution.

Actions Requiring Explicit User Authorization

These actions must not be performed unless the user explicitly authorizes G2 execution:

• Injecting or setting OPENCLAW_GATEWAY_TOKEN on the Windows PC.
• Running openclaw node run.
• Reading or using any real token, password, API key, private key, cookie, or secret value.
• Approving a device pairing request on the VPS.
• Running openclaw nodes pending or openclaw nodes approve if it changes approval state.
• Starting G3 smoke test from QQ or phone Control UI.
• Installing, starting, restarting, stopping, or persisting any PC/VPS service.
• Changing firewall, network, Nginx, Docker compose, bind mounts, container images, environment variables, or service state.

Secret Handling Rules

• Never write token/password/API key/private key/cookie values into files, evidence, logs, commits, or chat.
• Do not paste OPENCLAW_GATEWAY_TOKEN into chat.
• Do not echo or print the token.
• Evidence may say that a token was set locally, but must not include its value.
• Pairing request IDs may be recorded only if they are not secrets.
• If a command prints a secret or prompts to display one, stop and record a blocker without copying the value.

smartmotor.cloud Freeze Rules

G2 must not affect the public smartmotor.cloud website during filing review.

Forbidden during G2:

• Changing homepage content.
• Changing content reachable from homepage links.
• Changing static assets.
• Changing Nginx routing or route files.
• Changing Docker bind mounts or container images.
• Changing /opt/services/docker-composite.yml or equivalent service entries that could alter public website output.
• Restarting or reloading public website services unless a later approved rollback plan explicitly authorizes it.

Role Task Split

PC_EXECUTOR

Scope: Windows PC only.

Planned G2 task:

• Confirm no stale OpenClaw node process is running.
• After explicit user authorization, set the Gateway token only in the local shell/session.
• Run the node in foreground mode.
• Capture non-secret evidence of connection and pairing request ID if shown.
• Stop immediately on any secret exposure, fatal connection error, or request for unapproved mutation.

May write:

• evidence/pc-g2-node-run-YYYYMMDD.md
• handoff/PC_EXECUTOR.md
• rollback/pc-g2-node-run-YYYYMMDD.md

VPS_EXECUTOR

Scope: VPS Gateway approval only.

Planned G2 task:

• Confirm Gateway-side CLI command shape using --help if needed.
• After explicit user authorization and after PC evidence provides a pairing request ID or pending node ID, approve the correct request.
• Capture non-secret approval evidence.
• Do not restart/reload services or change Gateway/Nginx/Docker configuration.

May write:

• evidence/vps-g2-approve-YYYYMMDD.md
• handoff/VPS_EXECUTOR.md
• rollback/vps-g2-approve-YYYYMMDD.md

PC_VERIFIER

Scope: Independent validation of PC-side G2 evidence.

Planned G2 verification:

• Confirm PC foreground node evidence shows connection to the expected Gateway.
• Confirm token value is absent from evidence.
• Confirm no service install/start/status command was executed.
• Confirm no PC firewall, network, environment persistence, scheduled task, or public port exposure change occurred.

May write:

• evidence/verify-pc-g2-YYYYMMDD.md
• handoff/PC_VERIFIER.md

VPS_VERIFIER

Scope: Independent validation of VPS-side G2 evidence and freeze compliance.

Planned G2 verification:

• Confirm only the intended pairing approval occurred.
• Confirm no restart, reload, token rotation, Nginx edit, Docker compose edit, bind mount change, image change, or public website content change occurred.
• Confirm the frozen website policy remains intact.
• Track existing path/route anomalies as follow-up observations, not automatic blockers unless they affect G2.

May write:

• evidence/verify-vps-g2-YYYYMMDD.md
• handoff/VPS_VERIFIER.md

CORRECTION

Scope: Guardrails and drift detection.

Planned G2 monitoring:

• Confirm sync health before G2 execution starts.
• Block G2 if heartbeat is stale, sync error files exist, evidence is not visible on both sides, or repo state prevents coordination.
• Block G2 if any task tries to bypass user authorization or freeze rules.
• Block G2 if any secret appears in evidence, handoffs, logs, commits, or chat.

May write:

• handoff/CORRECTION.md
• tasks/T7-correction-monitor.md

Step Plan

Step 0 - ORCHESTRATOR Authorization Check

Prerequisites:

• User explicitly says to authorize G2 execution.
• G0A, G0B, and G1 remain complete.
• CORRECTION reports sync health not blocked.
• No sync-state/error-pc.md or sync-state/error-vps.md exists.
• PC and VPS agents can see the same latest control-plane state.

Command draft:

No PC/VPS command. ORCHESTRATOR records authorization and opens G2 tasks.

Expected output:

• USER_STATUS.md and AGENT_BOARD.md show G2 authorized/in progress.
• G2 executor tasks move from draft to ready.

Stop conditions:

• User authorization is ambiguous.
• Sync health is blocked.
• Any evidence or handoff contains a secret.
• Website freeze risk is unresolved.

Step 1 - PC Rollback Note Before Token/Node Run

Prerequisites:

• Step 0 complete.
• PC_EXECUTOR is assigned and has read the runbook.

Command draft:

No operational command. Write rollback note before action.

Expected output:

• rollback/pc-g2-node-run-YYYYMMDD.md exists.
• Rollback note says foreground node can be stopped with Ctrl+C, shell token can be cleared by closing the shell or removing the session environment variable, and no persistent service is installed in G2.

Stop conditions:

• Rollback note would require recording a secret.
• PC_EXECUTOR cannot confirm this is foreground-only.

Step 2 - PC Token Injection

Prerequisites:

• User explicitly authorizes token use.
• Token is provided out-of-band or typed locally by the user, not pasted into repo/chat.
• PC shell is local and not being logged into evidence.

Command draft:

$env:OPENCLAW_GATEWAY_TOKEN = "<user-pastes-token-locally>"

Expected output:

• No command output containing the token.
• Evidence records only: "Gateway token was set in local shell session; value not displayed or recorded."

Stop conditions:

• Token appears in terminal output, file, evidence, chat, or logs.
• Executor is asked to store token persistently.
• Token source or target Gateway is unclear.

Step 3 - PC Foreground Node Run

Prerequisites:

• Step 2 complete.
• No stale foreground node process conflicts are reported.
• No service install/start command is planned.

Command draft:

openclaw node run --host openclaw.smartmotor.cloud --port 443 --tls --display-name "desktop-vuor0gs"

Expected output:

• Foreground process keeps running.
• Logs show connection attempt to Gateway.
• If pairing is required, logs show a non-secret request ID or pending node ID.
• No PC public port is exposed.

Stop conditions:

• Command prints a secret.
• Fatal connection error repeats.
• Command asks to install or persist a service.
• Command attempts to bind a public PC port.
• Gateway host differs from openclaw.smartmotor.cloud without ORCHESTRATOR review.

Step 4 - VPS Rollback Note Before Approval

Prerequisites:

• PC evidence includes a non-secret pairing request ID or pending node ID, or Gateway shows a matching pending node.
• User explicitly authorizes VPS-side approval.

Command draft:

No approval command yet. Write rollback note before action.

Expected output:

• rollback/vps-g2-approve-YYYYMMDD.md exists.
• Rollback note explains how to stop the PC foreground node and how to escalate if the wrong request is approved. It must not invent destructive revoke commands.

Stop conditions:

• Request identity is ambiguous.
• Approval would require changing Gateway config, restarting services, or reading secrets.

Step 5 - VPS Pairing Approval

Prerequisites:

• Step 4 complete.
• VPS_EXECUTOR can target the openclaw-gateway container CLI without changing Docker/Nginx configuration.
• Request ID or node ID matches PC evidence and display name.

Command drafts:

docker exec -it openclaw-gateway node openclaw.mjs devices approve <requestId>
docker exec -it openclaw-gateway node openclaw.mjs nodes pending
docker exec -it openclaw-gateway node openclaw.mjs nodes approve <nodeId>

Expected output:

• The intended PC device/node is approved.
• Gateway shows the PC node online or approved.
• Evidence contains request IDs or node IDs only if non-secret.

Stop conditions:

• Multiple indistinguishable pending requests exist.
• Command would print or require a token/password.
• Command requires restart/reload/config mutation.
• Any action risks changing frozen website output.

Step 6 - G2 Verification

Prerequisites:

• PC_EXECUTOR and VPS_EXECUTOR evidence exists.
• No secret-bearing evidence exists.

Command draft:

Verifier review only. No new PC/VPS mutation.

Expected output:

• PC_VERIFIER accepts or returns PC G2 evidence.
• VPS_VERIFIER accepts or returns VPS G2 evidence.
• CORRECTION confirms no sync, secret, or freeze blocker.
• ORCHESTRATOR may mark G2 complete only after verifier acceptance.

Stop conditions:

• Missing evidence.
• Any evidence contains a secret.
• Approval cannot be tied to the intended PC node.
• Website freeze compliance is uncertain.

Rollback and Recovery Strategy

G2 uses foreground execution to keep recovery simple:

• Before PC action: write a PC rollback note.
• If foreground node misbehaves: stop it with Ctrl+C.
• If token was set in the shell: close the shell or clear the session environment variable. Do not write the token value.
• If pairing request is wrong or ambiguous: do not approve; block and ask ORCHESTRATOR/CORRECTION.
• If wrong approval appears to have happened: stop the PC foreground node, preserve non-secret evidence, and ask VPS_EXECUTOR to identify an official revoke/remove flow using --help or documentation before any corrective command.
• If sync becomes unhealthy: pause cross-device work until both sides can see the same evidence through Git.
• If freeze risk appears: stop all VPS-side action and route to CORRECTION.

Evidence Checklist

PC_EXECUTOR evidence should include:

• Authorization was received.
• Rollback note path.
• Token was set locally without value disclosure.
• Exact node command used.
• Connection/pairing status summary.
• Pairing request ID if non-secret.
• Confirmation no install/start/service/firewall/network/public-port change occurred.

VPS_EXECUTOR evidence should include:

• Authorization was received.
• Rollback note path.
• Pending request or node identity used for approval.
• Exact approval command shape, without secrets.
• Approval result summary.
• Confirmation no restart/reload/token rotation/Nginx/Docker/public website change occurred.

Verifier evidence should include:

• PC and VPS evidence reviewed.
• No secrets found.
• Intended PC node identity confirmed.
• Frozen website rule not violated.
• G2 accepted or returned with findings.

Decision: Should ORCHESTRATOR Request G2 Authorization?

Yes, but only as a request for explicit user authorization, not as execution.

The baseline evidence is sufficient to ask the user whether to open G2. The next user-facing question should be: "Authorize G2 execution now?" If the user says yes, ORCHESTRATOR must first open the draft tasks, require rollback notes, and keep each token/run/approval action behind the explicit authorization boundaries in this runbook.