openclaw-control-plane/AGENT_BOARD.md

OpenClaw Agent Control Board

Source of truth for multi-agent work across the Windows PC workspace and the VPS /opt/services 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: /home/ubuntu/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, /opt/services/docker-compose.openclaw.yml, or any equivalent compose/service entries that could alter public website output.
• Communication MVP: use Git-backed polling sync scripts under sync/ plus task files under tasks/. This reduces manual pull/push but is not the final async-notification design.
• Sync-health monitoring: CORRECTION monitors tracked heartbeat and error files under sync-state/; no separate sync monitor agent is used at this stage.
• User-facing status entry: USER_STATUS.md. Users should not need to read internal task, handoff, evidence, or sync-state files for routine status.
• COACH role: the main user-facing chat acts as COACH by default, guiding workflow usability, session freeze, and knowledge capture without replacing ORCHESTRATOR.
• Confirmed OpenClaw target: QQ and phone Control UI are current-stage control entries; the VPS Gateway is the always-on hub; DeepSeek may trigger white-listed actions; Windows PC is the main execution node.
• Tailscale role: optional administration, troubleshooting, and private-path enhancement. It is not a G2 prerequisite; the main path uses the VPS Gateway.
• G2 runbook: docs/G2_RUNBOOK.md exists for execution-before-action planning. It does not authorize G2 execution by itself.
• Future communication target: when the baseline path is stable, design an event-driven coordinator using Gitea webhooks, Gitea Issues, OpenClaw events, or Cursor SDK agent orchestration.

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/services, 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, sync-health failures, conflicts, unsafe changes, missing evidence, and rollback needs	handoff/CORRECTION.md, tasks/T7-correction-monitor.md
COACH	Guide user experience, session freeze, knowledge capture, and reusable method	handoff/COACH.md, USER_STATUS.md, docs/, knowledge/, archive/

Quality Gates

Gate	Required Evidence	Owner	Status
G0A Collaboration mechanism aligned	User-approved agent roles, Git polling MVP, sync-health handling, status entry, and hard safety boundaries	ORCHESTRATOR	Done
G0B OpenClaw system requirements aligned	User-approved target architecture, component boundaries, PC permissions, Tailscale role, phone/QQ behavior, and G2/G3/G4 acceptance criteria	ORCHESTRATOR	Done
G1 Baseline discovered	PC and VPS read-only status snapshots accepted by independent verifiers	PC_EXECUTOR, VPS_EXECUTOR, verifiers	Done
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 open on PC/VPS Cursor	ORCHESTRATOR + VPS_EXECUTOR	T1	Done
T2.1	Add polling sync and task-file communication MVP	ORCHESTRATOR	T2	Done
T3	Run read-only PC baseline discovery	PC_EXECUTOR	T2.1	Accepted
T4	Run read-only VPS baseline discovery	VPS_EXECUTOR	T2.1	Accepted
T5	Verify PC baseline before any PC change	PC_VERIFIER	T3	Accepted
T6	Verify VPS baseline before any VPS change	VPS_VERIFIER	T4	Accepted
T7	Monitor drift, sync-health failures, conflicts, unsafe changes, and missing evidence	CORRECTION	G0A	Claimed
T8	Solidify COACH role, session freeze, and knowledge capture	COACH	T2.1	Done
T9	G2 PC foreground node run	PC_EXECUTOR	User G2 authorization, T7 healthy	Draft
T10	G2 VPS pairing approval	VPS_EXECUTOR	T9, explicit approval authorization	Draft
T11	Verify G2 PC evidence	PC_VERIFIER	T9	Draft
T12	Verify G2 VPS evidence and freeze compliance	VPS_VERIFIER	T10	Draft
T13	Guard G2 sync, secret, and freeze risks	CORRECTION	User G2 authorization	Draft

Confirmed OpenClaw Target Design

• QQ is included in the current stage as a primary natural-language entry.
• Phone Control UI must be able to start basic tasks, show status/results, and approve high-risk actions.
• VPS OpenClaw Gateway is the always-on hub for device connection, routing, approval flow, state aggregation, and audit.
• DeepSeek may understand, split, and autonomously trigger white-listed actions. High-risk or non-white-listed actions require human approval.
• Docker stack hosts Gateway alongside existing Gitea, Nginx, Confluence, and Postgres services. The smartmotor.cloud filing-review freeze remains a hard boundary.
• Windows PC is the main execution node and may perform broad user-level local execution.
• PC system-level changes, service installation, network/firewall changes, and large destructive file operations require human approval and rollback notes.
• Tailscale is optional for administration, troubleshooting, and private-path enhancement. It is not a G2 prerequisite.
• Future multiple PCs, phones, and endpoint model nodes should join through the same Gateway model.

Acceptance Criteria

• 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 for basic tasks, status/results, and high-risk approvals.
• QQ is included in the current stage as a natural-language control entry.

Gate Acceptance Details

• G2 Gateway/node pairing is accepted only when the PC node can connect to the VPS Gateway, the VPS can show pending/approved node state, approval does not leak secrets, and the frozen smartmotor.cloud website output remains unchanged.
• G3 execution smoke test is accepted only when a harmless task starts from QQ or phone Control UI, routes through the Gateway to the Windows PC, returns visible results, and verifier evidence proves execution came from the PC rather than the VPS.
• G4 persistent service verification is accepted only when the PC node can run as a persistent service or startup item, service install/start/status and reboot survival evidence exist, rollback notes exist for system-level changes, and approval guardrails still work.

G2 Authorization Boundary

• docs/G2_RUNBOOK.md and T9-T13 are planning artifacts only while G2 is pending.
• G2 requires explicit user authorization before token injection, openclaw node run, VPS pairing approval, or any executor action.
• G2 must remain foreground-only for the PC node; service persistence belongs to G4.
• G2 must not change the frozen smartmotor.cloud homepage, homepage-linked content, static assets, Nginx routing, Docker bind mounts, container images, /opt/services/docker-compose.openclaw.yml, or any equivalent website-affecting compose/service entries.

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 and related service definitions as frozen during filing review: no edits to homepage content, linked page content, routing, static assets, bind mounts, container images, Nginx rules, /opt/services/docker-compose.openclaw.yml, or any equivalent compose/service entries that could alter what public visitors see.
• Polling sync scripts are convenience automation only. If they report conflict, authentication failure, or unexpected files, stop and let CORRECTION review.
• Sync scripts must publish non-secret heartbeat/error status under sync-state/. Heartbeat older than 2 minutes is warning; older than 5 minutes is blocked.
• Task files under tasks/ are the agent-to-agent work contract. Chat messages are not the source of truth.
• COACH should keep user-facing guidance in USER_STATUS.md and reusable practice in docs/, knowledge/, and archive/.
• Before context exhaustion or major handoff, active roles must perform session freeze using docs/SESSION_FREEZE_PROTOCOL.md.
• 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.