From 9063dce0dfc291ca82747f563c08b7f540eb04f9 Mon Sep 17 00:00:00 2001 From: wangzhendong Date: Fri, 15 May 2026 10:34:23 +0800 Subject: [PATCH] Bootstrap OpenClaw agent control plane Co-authored-by: Cursor --- .cursor/rules/agent-orchestration.mdc | 17 +++++++ AGENT_BOARD.md | 71 +++++++++++++++++++++++++++ README.md | 24 +++++++++ evidence/README.md | 9 ++++ handoff/CORRECTION.md | 30 +++++++++++ handoff/ORCHESTRATOR.md | 40 +++++++++++++++ handoff/PC_EXECUTOR.md | 41 ++++++++++++++++ handoff/PC_VERIFIER.md | 26 ++++++++++ handoff/VPS_EXECUTOR.md | 41 ++++++++++++++++ handoff/VPS_VERIFIER.md | 27 ++++++++++ rollback/README.md | 9 ++++ 11 files changed, 335 insertions(+) create mode 100644 .cursor/rules/agent-orchestration.mdc create mode 100644 AGENT_BOARD.md create mode 100644 README.md create mode 100644 evidence/README.md create mode 100644 handoff/CORRECTION.md create mode 100644 handoff/ORCHESTRATOR.md create mode 100644 handoff/PC_EXECUTOR.md create mode 100644 handoff/PC_VERIFIER.md create mode 100644 handoff/VPS_EXECUTOR.md create mode 100644 handoff/VPS_VERIFIER.md create mode 100644 rollback/README.md diff --git a/.cursor/rules/agent-orchestration.mdc b/.cursor/rules/agent-orchestration.mdc new file mode 100644 index 0000000..27acf43 --- /dev/null +++ b/.cursor/rules/agent-orchestration.mdc @@ -0,0 +1,17 @@ +--- +description: Multi-agent orchestration rules for OpenClaw PC/VPS work +alwaysApply: true +--- + +# OpenClaw Multi-Agent Rules + +- Read `AGENT_BOARD.md` before making plans, running commands, or editing files. +- Stay within the active role scope assigned by the user or orchestrator. +- Do not write secrets, passwords, tokens, API keys, or `OPENCLAW_GATEWAY_TOKEN` into files, logs, evidence, commits, or chat. +- Treat the VPS `smartmotor.cloud` website as frozen during filing review. Do not change homepage content, linked page content reachable from the homepage, static assets, container images, bind mounts, routes, Nginx rules, or `/opt/services/docker-composite.yml` entries that could alter public website content. +- Execution agents may write only their own handoff, evidence, and rollback files unless explicitly assigned otherwise. +- Execution agents do not mark their own work as accepted; a verifier or orchestrator must validate evidence. +- Before system-level changes, service restarts, network exposure changes, or config edits, create a rollback note. +- Prefer read-only discovery before mutation. Capture important command results in `evidence/`. +- If task scope, device target, or acceptance criteria are unclear, stop and ask instead of guessing. +- When ending a session or nearing context limits, update the relevant file under `handoff/`. diff --git a/AGENT_BOARD.md b/AGENT_BOARD.md new file mode 100644 index 0000000..54e52e1 --- /dev/null +++ b/AGENT_BOARD.md @@ -0,0 +1,71 @@ +# OpenClaw Agent Control Board + +> Source of truth for multi-agent work across the Windows PC workspace and the VPS `/opt/service` workspace. + +## Mission + +Bring the Windows 11 always-on PC, Tencent Cloud VPS OpenClaw Gateway, phone Control UI, optional Tailscale path, and later channels such as QQ into a controlled multi-device OpenClaw workflow. + +## Current Decision + +- Shared mechanism: use the VPS Gitea repository as the durable sync point. +- Repository mode: standalone Gitea repository `openclaw-control-plane`. +- Repository URL: `https://git.smartmotor.cloud/wangzhendong/openclaw-control-plane.git`. +- Authentication mode: HTTPS access from both the Windows PC and VPS. +- Default branch: `main`. +- PC control-plane path: `D:\openclaw-control-plane`. +- VPS control-plane path: `/opt/openclaw-control-plane`. +- Secrets policy: no password, token, API key, or `OPENCLAW_GATEWAY_TOKEN` may be written into repo files, handoffs, evidence, or chat. +- Frozen website policy: strict freeze during ICP/public-security filing review. Agents must not change the `smartmotor.cloud` homepage, content reachable from homepage links, static assets, Nginx routing, bind mounts, container images, or `/opt/services/docker-composite.yml` entries that could alter public website output. + +## Agent Roles + +| Role | Scope | May Write | +|---|---|---| +| ORCHESTRATOR | Requirements alignment, task split, dependency tracking, final acceptance | `AGENT_BOARD.md`, `handoff/ORCHESTRATOR.md` | +| PC_EXECUTOR | Windows PC, Tailscale, OpenClaw CLI/node, local service install | `handoff/PC_EXECUTOR.md`, `evidence/pc-*`, `rollback/pc-*` | +| VPS_EXECUTOR | VPS `/opt/service`, Gateway, Docker stack, Nginx, Gitea, approvals | `handoff/VPS_EXECUTOR.md`, `evidence/vps-*`, `rollback/vps-*` | +| PC_VERIFIER | Independent read-only validation of PC executor results | `handoff/PC_VERIFIER.md`, `evidence/verify-pc-*` | +| VPS_VERIFIER | Independent read-only validation of VPS executor results | `handoff/VPS_VERIFIER.md`, `evidence/verify-vps-*` | +| CORRECTION | Detect drift, conflicts, unsafe changes, missing evidence, and rollback needs | `handoff/CORRECTION.md` | + +## Quality Gates + +| Gate | Required Evidence | Owner | Status | +|---|---|---|---| +| G0 Requirements aligned | User-approved mission, roles, and acceptance criteria | ORCHESTRATOR | Pending | +| G1 Baseline discovered | PC and VPS read-only status snapshots | PC_EXECUTOR, VPS_EXECUTOR, verifiers | Pending | +| G2 Gateway/node pairing ready | PC `node run` evidence and VPS approval evidence | PC_EXECUTOR, VPS_EXECUTOR | Pending | +| G3 Execution smoke test | Harmless command result proves execution came from the PC node | PC_VERIFIER | Pending | +| G4 Persistent service verified | `node install/start/status` and reboot survival evidence | PC_VERIFIER, CORRECTION | Pending | +| G5 Security posture reviewed | Secrets absent, public exposure avoided, least-privilege notes captured | VPS_VERIFIER, CORRECTION | Pending | + +## Active Tasks + +| ID | Task | Owner | Depends On | Status | +|---|---|---|---|---| +| T0 | Create local control-plane scaffold | ORCHESTRATOR | None | Done | +| T1 | Create standalone Gitea repo for this control plane | User + ORCHESTRATOR | T0 | Done | +| T2 | Sync this scaffold to Gitea and clone/pull on VPS | ORCHESTRATOR + VPS_EXECUTOR | T1 | In Progress | +| T3 | Run read-only PC baseline discovery | PC_EXECUTOR | T2 | Pending | +| T4 | Run read-only VPS baseline discovery | VPS_EXECUTOR | T2 | Pending | +| T5 | Verify both baselines before any config change | PC_VERIFIER + VPS_VERIFIER | T3, T4 | Pending | + +## Acceptance Criteria Draft + +- The PC can act as an OpenClaw execution node connected to the existing Gateway. +- The Gateway continues to coexist with Nginx, Gitea, Confluence, and Postgres on the VPS. +- The existing `smartmotor.cloud` website content remains unchanged during filing review, including homepage content and linked content reachable from the homepage. +- No PC service port is exposed directly to the public internet. +- Tailscale is optional for the OpenClaw public Gateway path, but available for safer device-to-device operations. +- Phone can be used as a control client after the execution path is stable. +- Later QQ or other channels are added only after the Gateway/node path is verified. + +## Operating Rules + +- Agents must read this file before doing work. +- Executors must not accept work outside their named scope. +- Executors must not validate their own work as complete. +- VPS-related agents must treat the `smartmotor.cloud` website defined by `/opt/services/docker-composite.yml` as frozen: no edits to homepage content, linked page content, routing, static assets, bind mounts, container images, or Nginx rules that could alter what public visitors see. +- Any system-level change requires a rollback note before execution. +- Any blocking issue must be recorded in the relevant handoff file and surfaced to ORCHESTRATOR. diff --git a/README.md b/README.md new file mode 100644 index 0000000..5da0cf6 --- /dev/null +++ b/README.md @@ -0,0 +1,24 @@ +# OpenClaw Control Plane + +Shared control-plane repository for coordinating Cursor agents across: + +- Windows PC workspace: `D:\openclaw` +- Control-plane workspace on PC: `D:\openclaw-control-plane` +- VPS service workspace: `/opt/service` +- Control-plane workspace on VPS: `/opt/openclaw-control-plane` + +## Start Here + +Every agent must read: + +1. `AGENT_BOARD.md` +2. Its assigned file under `handoff/` +3. `.cursor/rules/agent-orchestration.mdc` + +## Hard Safety Rule + +During ICP/public-security filing review, the existing `smartmotor.cloud` website is frozen. Do not change homepage content, linked page content reachable from the homepage, static assets, Nginx routing, Docker bind mounts, container images, or `/opt/services/docker-composite.yml` entries that could alter public website output. + +## Secrets + +Do not store secrets in this repository. diff --git a/evidence/README.md b/evidence/README.md new file mode 100644 index 0000000..2fa650e --- /dev/null +++ b/evidence/README.md @@ -0,0 +1,9 @@ +# Evidence Directory + +Agents store non-secret evidence here. + +Rules: + +- Do not store passwords, tokens, API keys, cookies, private keys, or `OPENCLAW_GATEWAY_TOKEN`. +- Prefer short command summaries over full logs when logs may contain secrets. +- Use names such as `pc-YYYYMMDD-topic.md`, `vps-YYYYMMDD-topic.md`, `verify-pc-YYYYMMDD-topic.md`, or `verify-vps-YYYYMMDD-topic.md`. diff --git a/handoff/CORRECTION.md b/handoff/CORRECTION.md new file mode 100644 index 0000000..f16b303 --- /dev/null +++ b/handoff/CORRECTION.md @@ -0,0 +1,30 @@ +# CORRECTION Handoff + +## Role + +Detect drift, unsafe assumptions, missing evidence, conflicting edits, and tasks that no longer align with the mission. + +## Watchlist + +- Agents editing outside their role scope. +- Executors marking their own work as accepted. +- Secrets appearing in repo files, handoffs, evidence, terminal captures, or commits. +- Any attempt to alter the frozen `smartmotor.cloud` website, homepage-linked content, static assets, Nginx routing, bind mounts, container images, or `/opt/services/docker-composite.yml` entries that affect public website output. +- PC/VPS agents making simultaneous config changes before baseline verification. +- Gitea sync conflicts in `AGENT_BOARD.md` or handoff files. +- Changes to Nginx, Docker, or Windows services without rollback notes. + +## Current State + +- Control-plane scaffold is being prepared locally in `D:\openclaw-control-plane`. +- Remote Gitea repository has been created and cloned locally. + +## Next Actions + +1. After Gitea sync is configured, verify all role files exist on both PC and VPS. +2. Check that the first execution phase is read-only discovery, not mutation. +3. Flag any missing rollback note before service-level changes. + +## Last Update + +Template created during control-plane bootstrap. diff --git a/handoff/ORCHESTRATOR.md b/handoff/ORCHESTRATOR.md new file mode 100644 index 0000000..74f96b7 --- /dev/null +++ b/handoff/ORCHESTRATOR.md @@ -0,0 +1,40 @@ +# ORCHESTRATOR Handoff + +## Role + +Own requirements alignment, task decomposition, dependency tracking, and final acceptance. + +## Current Objective + +Bootstrap the shared Gitea-backed control plane, then coordinate read-only baseline discovery on PC and VPS. + +## Must Read + +- `AGENT_BOARD.md` +- `OPENCLAW_EXEC_NODE_PLAN.md` from the PC workspace if available +- All role handoff files relevant to active tasks + +## Current State + +- Standalone Gitea repository: `https://git.smartmotor.cloud/wangzhendong/openclaw-control-plane.git`. +- PC local path: `D:\openclaw-control-plane`. +- VPS target path: `/opt/openclaw-control-plane`. +- Access mode: HTTPS. +- Default branch: `main`. +- Strict `smartmotor.cloud` website freeze is a hard requirement during filing review. + +## Next Actions + +1. Commit and push the control-plane scaffold to Gitea after user approval. +2. Clone or pull the repository on the VPS at `/opt/openclaw-control-plane`. +3. Run G0 requirements and acceptance review with the user. +4. Assign PC and VPS read-only baseline tasks only after sync is available on both machines. + +## Open Questions + +- Has the VPS cloned the control-plane repository at `/opt/openclaw-control-plane`? +- Should Gitea Issues be used immediately for task tracking, or should `AGENT_BOARD.md` remain the first source of truth for the initial run? + +## Last Update + +Control-plane repository scaffold prepared locally. diff --git a/handoff/PC_EXECUTOR.md b/handoff/PC_EXECUTOR.md new file mode 100644 index 0000000..b5b793d --- /dev/null +++ b/handoff/PC_EXECUTOR.md @@ -0,0 +1,41 @@ +# PC_EXECUTOR Handoff + +## Role + +Operate only on the Windows 11 PC side: `D:\openclaw`, Tailscale, local OpenClaw CLI/node, and Windows service or scheduled task setup. + +## Allowed Work + +- Read local PC state. +- Run harmless diagnostic commands. +- Capture evidence under `evidence/pc-*`. +- Prepare rollback notes under `rollback/pc-*` before local system changes. + +## Not Allowed + +- Do not access VPS secrets. +- Do not approve Gateway pairings. +- Do not expose local PC ports publicly. +- Do not mark PC work as accepted without verifier review. + +## Current State + +From `OPENCLAW_EXEC_NODE_PLAN.md`: + +- OpenClaw CLI was previously detected as `OpenClaw 2026.5.7 (eeef486)`. +- Gateway 443 connectivity was previously successful. +- Tailscale service exists and was later logged in with PC Tailnet IP `100.125.185.1`. +- Next planned OpenClaw work is C1 token injection, C2 `node run`, then C3 VPS approval. + +## Next Read-Only Task + +After the Gitea control plane is synchronized, collect current PC baseline evidence: + +- `openclaw --version` +- `openclaw node --help` +- Tailscale CLI path and login status +- `Test-NetConnection openclaw.smartmotor.cloud -Port 443` + +## Last Update + +Template created during control-plane bootstrap. diff --git a/handoff/PC_VERIFIER.md b/handoff/PC_VERIFIER.md new file mode 100644 index 0000000..2a22d6f --- /dev/null +++ b/handoff/PC_VERIFIER.md @@ -0,0 +1,26 @@ +# PC_VERIFIER Handoff + +## Role + +Independently validate PC-side execution results. Prefer read-only checks and evidence review. + +## Validation Scope + +- Confirm PC baseline commands match `OPENCLAW_EXEC_NODE_PLAN.md`. +- Confirm any OpenClaw node execution evidence truly originates from the Windows PC. +- Confirm no local PC port is exposed publicly as part of the node setup. +- Confirm service persistence only after `node install/start/status` and reboot evidence exist. + +## Current State + +- Waiting for PC_EXECUTOR baseline evidence. + +## Next Actions + +1. Review `evidence/pc-*` after PC_EXECUTOR completes baseline discovery. +2. Record pass/fail findings in this file and, if needed, `evidence/verify-pc-*`. +3. Do not mutate PC configuration unless explicitly reassigned as an executor. + +## Last Update + +Template created during control-plane bootstrap. diff --git a/handoff/VPS_EXECUTOR.md b/handoff/VPS_EXECUTOR.md new file mode 100644 index 0000000..16f154b --- /dev/null +++ b/handoff/VPS_EXECUTOR.md @@ -0,0 +1,41 @@ +# VPS_EXECUTOR Handoff + +## Role + +Operate only on the VPS side: `/opt/service`, OpenClaw Gateway, Docker stack, Nginx, Gitea, Confluence, Postgres, and Gateway-side approval workflows. + +## Allowed Work + +- Read VPS service state. +- Run harmless diagnostic commands. +- Capture evidence under `evidence/vps-*`. +- Prepare rollback notes under `rollback/vps-*` before service or config changes. + +## Not Allowed + +- Do not request or store plaintext VPS passwords. +- Do not rotate or print secrets unless explicitly authorized by the user. +- Do not change the `smartmotor.cloud` website during filing review: homepage content, linked content reachable from the homepage, static assets, routes, bind mounts, container images, Nginx rules, or `/opt/services/docker-composite.yml` entries that affect public website output are frozen. +- Do not restart production-facing services without an approved rollback note. +- Do not mark VPS work as accepted without verifier review. + +## Current State + +- VPS public IP: `114.132.222.127`. +- OpenClaw Gateway is already deployed and coexists with the existing Docker stack. +- The VPS service workspace path is `/opt/service`. +- The VPS control-plane path is `/opt/openclaw-control-plane`. +- Gitea control-plane repository: `https://git.smartmotor.cloud/wangzhendong/openclaw-control-plane.git`. + +## Next Read-Only Task + +After the Gitea control plane is synchronized, collect current VPS baseline evidence: + +- Git/Gitea repository availability for the control plane. +- OpenClaw Gateway process or container status. +- Nginx route for `openclaw.smartmotor.cloud`. +- Whether `openclaw devices approve`, `openclaw nodes pending`, and `openclaw nodes approve` are available. + +## Last Update + +Template created during control-plane bootstrap. diff --git a/handoff/VPS_VERIFIER.md b/handoff/VPS_VERIFIER.md new file mode 100644 index 0000000..acf2230 --- /dev/null +++ b/handoff/VPS_VERIFIER.md @@ -0,0 +1,27 @@ +# VPS_VERIFIER Handoff + +## Role + +Independently validate VPS-side execution results. Prefer read-only checks and evidence review. + +## Validation Scope + +- Confirm Gateway remains healthy. +- Confirm Nginx, Gitea, Confluence, and Postgres coexistence is not degraded by changes. +- Confirm the frozen `smartmotor.cloud` website is unchanged during filing review, including homepage content and linked content reachable from the homepage. +- Confirm approval commands and node status evidence are sufficient. +- Confirm no secrets are written into tracked files or evidence. + +## Current State + +- Waiting for VPS_EXECUTOR baseline evidence. + +## Next Actions + +1. Review `evidence/vps-*` after VPS_EXECUTOR completes baseline discovery. +2. Record pass/fail findings in this file and, if needed, `evidence/verify-vps-*`. +3. Do not mutate VPS configuration unless explicitly reassigned as an executor. + +## Last Update + +Template created during control-plane bootstrap. diff --git a/rollback/README.md b/rollback/README.md new file mode 100644 index 0000000..bd727c2 --- /dev/null +++ b/rollback/README.md @@ -0,0 +1,9 @@ +# Rollback Directory + +Agents store rollback notes here before system-level changes. + +Rules: + +- A rollback note is required before service restarts, config edits, routing changes, or persistent node installation. +- Do not modify the frozen `smartmotor.cloud` website during filing review. +- Include the intended change, current state snapshot, rollback command or manual steps, and owner.