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:

- Have the user start the Windows PC node in a dedicated local PowerShell terminal 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.

## T9 Token Execution Model

`OPENCLAW_GATEWAY_TOKEN` must not be sent to chat, files, evidence, commits, or an Agent-managed shell. Because a token set in a separate user PowerShell session does not automatically enter the Agent shell, T9 uses this model:

- The user opens a dedicated local PC PowerShell terminal.
- The user sets `OPENCLAW_GATEWAY_TOKEN` only in that local terminal session.
- The user runs the foreground `openclaw node run` command in that same terminal.
- PC_EXECUTOR does not run `openclaw node run` in the Agent shell and does not request, read, print, or record the token value.
- PC_EXECUTOR provides the command template, reminds the user not to disclose the token, then records only non-secret status and any non-secret pairing request ID or pending node ID reported by the user.

## 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 historical `/opt/service` references versus the actual `/opt/services` path, obsolete `docker-composite.yml` references versus the actual `/opt/services/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-compose.openclaw.yml` or any equivalent compose/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 or refresh the PC rollback note before the user-run foreground node flow.
- Give the user the local PowerShell command template and require that the token is never sent to chat or files.
- Ask the user to set the Gateway token and run the foreground node in the same dedicated local PowerShell terminal.
- Do not run `openclaw node run` from the Agent shell.
- Capture only non-secret evidence reported by the user, including connection status and pairing request ID or pending node 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 template for the user to run in a dedicated local PC PowerShell terminal; PC_EXECUTOR must not execute this in the Agent shell:

```powershell
$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 instructing the user to set the token in the local terminal.
- A2 before instructing the user to run foreground `openclaw node run`.

PC_EXECUTOR stop conditions:

- User authorization is absent or ambiguous.
- Token would be printed, stored, logged, committed, pasted into chat, or entered into an Agent-managed shell.
- 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:

```bash
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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 local token use.
- The user is at a dedicated local PC PowerShell terminal, not an Agent shell.
- Token is typed or pasted locally by the user, not pasted into repo/chat/files.
- The local terminal is not being copied into evidence.

User-run command template; do not execute in Agent shell and do not record the token value:

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

Expected output:

- No command output containing the token.
- Evidence records only: "User set Gateway token in a dedicated local PC PowerShell terminal; 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.

User-run command template in the same dedicated local PC PowerShell terminal; do not execute in Agent shell:

```powershell
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.
- User cannot report non-secret status without exposing terminal content that includes a token.

### 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:

```text
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:

```bash
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:

```text
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.
- User was given the local PowerShell command template and warned not to send the token to chat/files.
- User reported token was set in a dedicated local PC PowerShell terminal without value disclosure.
- Exact node command template used, without secrets.
- Non-secret connection/pairing status summary reported by the user.
- 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.