Sync agent state from PC at 2026-05-19 12:06:32
This commit is contained in:
wangzhendong
392
docs/G2_RUNBOOK.md
Normal file
392
docs/G2_RUNBOOK.md
Normal file
@@ -0,0 +1,392 @@
|
||||
# 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:
|
||||
|
||||
```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 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:
|
||||
|
||||
```powershell
|
||||
$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:
|
||||
|
||||
```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.
|
||||
|
||||
### 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 -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:
|
||||
|
||||
```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.
|
||||
- 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.
|
||||
Reference in New Issue
Block a user