openclaw-control-plane/docs/G2_RUNBOOK.md

G2 Runbook - Gateway/Node Pairing Pre-Execution Plan

Status

Pre-execution plan confirmed. G2 execution is not authorized and must not start from this document alone.

This runbook is a planning and authorization checklist. It may be used only after the user explicitly authorizes G2 execution in a later instruction. It does not authorize token injection, openclaw node run, VPS approval, service changes, Nginx changes, Docker changes, or any mutation by itself.

Non-Execution Confirmation

This planning pass must update only documentation and task files.

Forbidden in this planning pass:

• Do not execute any PC command.
• Do not execute any VPS command.
• Do not start a PC node.
• Do not approve a node or device.
• Do not read, print, store, or rotate secrets.
• Do not change Gateway, Docker, Nginx, service, firewall, route, bind mount, image, or public website state.

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
• tasks/T9-G2-PC-node-run.md
• tasks/T10-G2-VPS-pairing-approve.md
• Role handoffs for PC_EXECUTOR, VPS_EXECUTOR, PC_VERIFIER, VPS_VERIFIER, and CORRECTION

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.
• Sync-health has been confirmed healthy by the user and T7 sync-health blocked state is cleared.
• 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.
• Before actual G2 execution, CORRECTION must still do a final freshness check: both heartbeat files must exist, both must be under 5 minutes old, and no sync-state/error-*.md may exist.

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 Gateway-side pairing commands against live state, including openclaw devices approve, openclaw nodes pending, or openclaw nodes approve.
• 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.

Authorization must be explicit at these points:

• A0: User authorizes G2 execution to begin.
• A1: User authorizes local PC session token use.
• A2: User authorizes foreground PC node run.
• A3: User authorizes VPS-side approval for a specific non-secret request or node ID.
• A4: Verifiers authorize marking G2 evidence accepted. Executors must not self-accept.

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.
• If a command requires a token/password flag, do not place the value in the command line. Prefer local session environment or interactive user entry that is not captured in evidence.

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 only after G2 execution is authorized.
• 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

Command drafts, not for this planning pass:

$env:OPENCLAW_GATEWAY_TOKEN = "<user-pastes-token-locally>"
openclaw node run --host openclaw.smartmotor.cloud --port 443 --tls --display-name "desktop-vuor0gs"

PC_EXECUTOR authorization points:

• A0 before any G2 work.
• A1 before token use.
• A2 before openclaw node run.

PC_EXECUTOR stop conditions:

• User authorization is absent or ambiguous.
• Token would be printed, stored, logged, committed, or pasted into chat.
• Command asks to install, start, restart, stop, or persist a service.
• Command attempts firewall, network, scheduled task, environment persistence, or public port changes.
• Gateway host, display name, or command shape differs from the runbook without ORCHESTRATOR review.

VPS_EXECUTOR

Scope: VPS Gateway approval only.

Planned G2 task:

• Confirm Gateway-side CLI command shape using --help if needed, only after G2 execution is authorized.
• 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

Command drafts, not for this planning pass:

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

VPS_EXECUTOR authorization points:

• A0 before any G2 work.
• A3 before approving a specific request or node ID.

VPS_EXECUTOR stop conditions:

• Request identity is ambiguous or multiple indistinguishable pending requests exist.
• Approval would require token/password entry, token rotation, Gateway config mutation, restart, reload, Nginx edit, Docker edit, bind mount change, image change, or public website change.
• Approval target cannot be tied to PC evidence and display name.

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

Verification draft:

Review PC evidence only. Do not run PC commands unless a later user instruction explicitly authorizes verifier-side read-only checks.

PC_VERIFIER stop conditions:

• PC evidence is missing, incomplete, or not synchronized.
• Evidence contains a secret.
• Evidence suggests service persistence, firewall/network change, public port exposure, or a command outside the runbook.

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

Verification draft:

Review VPS evidence only. Do not run VPS commands unless a later user instruction explicitly authorizes verifier-side read-only checks.

VPS_VERIFIER stop conditions:

• VPS evidence is missing, incomplete, or not synchronized.
• Evidence contains a secret.
• Approval cannot be tied to the intended PC node.
• Evidence suggests restart, reload, token rotation, Gateway config mutation, Nginx edit, Docker edit, bind mount change, image change, or frozen website output change.

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

Monitoring draft:

Review sync-state files and task/evidence visibility only. Do not execute PC/VPS operational commands in this planning pass.

CORRECTION stop conditions:

• Either heartbeat is missing or older than 5 minutes.
• Any sync-state/error-*.md file exists.
• Either side has a persistent Git state that prevents evidence visibility.
• Any role attempts to execute G2 without explicit authorization.
• Any evidence or handoff contains a secret.
• Any task attempts to bypass the filing freeze.

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 openclaw-gateway node openclaw.mjs nodes pending
docker exec openclaw-gateway node openclaw.mjs devices approve <requestId>
docker exec 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.

Planning-Pass Completion

This runbook update is documentation-only. It confirms G2 is ready for an authorization decision, but G2 remains unexecuted until a later explicit user instruction opens execution.