vilvona 1.0.0

package/docs/specs/claw-supervisor.md

@@ -0,0 +1,247 @@
+---
+title: Claw Supervisor
+description: Fleet supervision plan for Codex app-server sessions controlled by OpenClaw.
+readWhen:
+  - Designing Codex fleet supervision
+  - Building OpenClaw tools that read, steer, or spawn Codex sessions
+  - Choosing between local, Cloudflare, and VPS deployment for supervised Codex
+---
+
+# Claw Supervisor
+
+## Goal
+
+Claw Supervisor lets one always-on OpenClaw instance monitor and drive a fleet of Codex sessions without changing the normal Codex user experience. A user can SSH into a host, start Codex, work in the TUI, and still have the supervisor read the session, steer it, interrupt it, spawn related sessions, and accept handoffs. Codex sessions can also call back into OpenClaw through MCP.
+
+## Product Model
+
+Codex remains the primary work surface. OpenClaw supervises Codex rather than hiding Codex inside an opaque OpenClaw subagent.
+
+The OpenClaw plugin is named `codex-supervisor`. `crabfleet` remains the deployment
+and host-fleet profile for CRAB machines rather than the reusable plugin name.
+
+The model has three roles:
+
+- Human-attached Codex: a normal interactive Codex TUI launched through a shared app-server.
+- Autonomous Codex: a Codex app-server thread spawned by the supervisor that a human can later attach to.
+- Supervisor Claw: an always-on OpenClaw agent with tools for fleet state, transcript reads, steering, interruption, spawning, and handoff.
+
+OpenClaw may use its existing subagent machinery internally, but the external contract is an attachable Codex session with a Codex thread id.
+
+## Architecture
+
+```text
+user SSH session
+  -> codex --remote unix://... or ws://...
+      -> local codex app-server daemon
+          <-> host sidecar / supervisor connector
+              <-> OpenClaw fleet supervisor
+                  <-> supervisor MCP exposed back to Codex
+```
+
+Each Codex-capable host runs:
+
+- Codex app-server daemon.
+- A launcher that always starts interactive Codex with `--remote`.
+- A connector that registers app-server endpoints and live threads with the supervisor.
+
+The supervisor runs:
+
+- Endpoint registry.
+- Session registry.
+- Codex app-server JSON-RPC client pool.
+- MCP server for Codex-to-Claw calls.
+- OpenClaw tools for Claw-to-Codex control.
+- Policy engine for autonomous actions, approvals, and loop prevention.
+
+## Codex App-Server Contract
+
+Use Codex app-server APIs as the canonical control plane:
+
+- `initialize`, `initialized`
+- `thread/loaded/list`
+- `thread/list`
+- `thread/read`
+- `thread/resume`
+- `thread/start`
+- `turn/start`
+- `turn/steer`
+- `turn/interrupt`
+- `model/list`
+
+Interactive Codex must be launched with `codex --remote <endpoint>` so the TUI and supervisor connect to the same app-server. Standalone `codex exec` is not a live-shared session today; use app-server APIs for autonomous work until Codex supports `exec --remote`.
+
+## Session Registry
+
+Supervisor stores one record per observed Codex thread:
+
+```json
+{
+  "sessionId": "codex-thread-id",
+  "endpointId": "host-a",
+  "host": "host-a.example",
+  "workspace": "/workspace/repo",
+  "repo": "owner/repo",
+  "branch": "feature/example",
+  "source": "vscode",
+  "status": "idle",
+  "humanAttached": true,
+  "lastSeenAt": "2026-05-28T10:00:00.000Z",
+  "summary": "Short working-state summary"
+}
+```
+
+The local implementation can derive most fields from Codex thread metadata. Fleet deployment should enrich records with host identity, user attachment state, git state, and sidecar health.
+
+## MCP Surface For Codex
+
+Every supervised Codex gets an MCP server named `openclaw-codex-supervisor`.
+
+Tools:
+
+- `codex_sessions_list`: list visible Codex sessions.
+- `codex_session_read`: read one transcript.
+- `codex_session_send`: send a message to an idle thread or steer an active thread.
+- `codex_session_interrupt`: interrupt the active turn.
+- `codex_endpoint_probe`: verify endpoint connectivity.
+- `claw_report_progress`: publish current task state to the supervisor.
+- `claw_ask`: ask the supervisor for help or delegation.
+- `codex_spawn`: create a new autonomous Codex session.
+- `codex_handoff`: request human or peer takeover.
+
+Resources:
+
+- `codex://sessions`
+- `codex://sessions/{sessionId}`
+- `codex://sessions/{sessionId}/transcript`
+
+## Claw Control Surface
+
+The always-on Claw gets the same primitives as internal tools:
+
+- list sessions and endpoints
+- read transcripts
+- send/steer text
+- interrupt active work
+- spawn new sessions
+- summarize and assign sessions
+- broadcast instructions to a filtered group
+- mark sessions blocked, done, or abandoned
+
+Tool behavior:
+
+- If a target thread is idle, `codex_session_send` maps to `turn/start`.
+- If a target thread is active and an in-progress turn id is visible, it maps to `turn/steer`.
+- If the active turn cannot be identified, the tool fails closed instead of creating an unrelated turn.
+- Codex-exposed MCP write controls stay disabled unless a trusted supervisor-only policy enables them.
+- Raw transcript reads stay disabled unless a trusted supervisor-only policy enables them.
+- Autonomous approval defaults deny tool/file approvals unless an explicit policy says otherwise.
+
+## Launch Flow
+
+Interactive host login:
+
+1. User SSHes into a CRAB host.
+2. SSH service starts or verifies `codex app-server daemon start`.
+3. Login wrapper launches `codex --remote unix:// --cd <workspace>`.
+4. Host connector registers endpoint and loaded thread.
+5. Supervisor emits a high-priority fleet event: new Codex session, workspace, human-attached state, current task preview.
+6. Supervisor Claw can read and steer immediately.
+
+Autonomous spawn:
+
+1. Supervisor selects host and workspace.
+2. Host connector opens or resumes a Codex app-server thread.
+3. Supervisor starts the first turn with task text and MCP config.
+4. Session registry marks it autonomous and attachable.
+5. Human can later attach with `codex --remote <endpoint> resume <threadId>` once Codex supports that exact UX, or via current resume flow on the same app-server.
+
+## Deployment
+
+Preferred control plane:
+
+- Host connectors keep outbound WebSocket connections to the supervisor.
+- Supervisor state lives in OpenClaw Gateway storage.
+- Codex app-server remains local to each host; never expose a raw unauthenticated app-server to the public internet.
+
+Cloudflare viability:
+
+- Good for registry, durable objects, WebSocket fan-in, lightweight event routing, and public MCP/gateway endpoints.
+- Not enough by itself for direct private host control because Workers cannot dial arbitrary private Unix sockets or local loopback app-servers.
+- Use Cloudflare when every host connector phones home over outbound WebSocket.
+
+VPS fallback:
+
+- Use a Hetzner service when long-lived process control, SSH tunnels, private network routing, or local filesystem access is needed.
+- Keep the same protocol: host connectors outbound, supervisor registry central, Codex app-server local.
+
+## Security
+
+- Default bind is local Unix socket.
+- Remote app-server uses token or signed bearer auth.
+- Host connector authenticates to supervisor with a scoped host token.
+- Supervisor tools enforce per-session policy: read, steer, interrupt, spawn, approval.
+- Cross-agent messages include `originSessionId`; self-echo is dropped.
+- Broadcast requires an explicit filter and bounded target count.
+- Transcript reads redact secrets at OpenClaw boundary.
+- Approval requests default to deny for supervisor-originated turns unless policy allows them.
+
+## Implementation Plan
+
+Phase 1: Local supervisor MVP
+
+- Add Codex app-server JSON-RPC client for stdio proxy and WebSocket endpoints.
+- Add supervisor endpoint/session registry.
+- Add MCP tools: list, read, send, interrupt, probe.
+- Add local env config for endpoints.
+- Add fake app-server tests and one live local app-server smoke.
+
+Phase 2: OpenClaw integration
+
+- Register supervisor tools in the `codex-supervisor` plugin.
+- Inject supervisor MCP into Codex thread config.
+- Add session summaries to agent context.
+- Add event notifications when new Codex threads appear.
+- Add policy config for autonomous send/interrupt/spawn.
+
+Phase 3: Fleet connector
+
+- Host sidecar registers app-server endpoint, host metadata, git/workspace metadata, and human attachment state.
+- Add outbound WebSocket connector for Cloudflare or VPS control plane.
+- Add reconnect, heartbeat, and stale-session cleanup.
+- Add CRAB SSH launcher wrapper.
+
+Phase 4: Autonomous operation
+
+- Add spawn/resume/takeover flows.
+- Add broadcast and delegation.
+- Add progress reports and task-state summaries.
+- Add loop prevention and rate limits.
+- Add dashboard views.
+
+Phase 5: Multi-Claw
+
+- Shard sessions by group.
+- Add leadership/lease for each session.
+- Add audit log and replay.
+- Add escalation between Claw groups.
+
+## Acceptance Tests
+
+- A human launches Codex TUI through a shared app-server.
+- Supervisor lists the live thread via `thread/loaded/list`.
+- Supervisor reads transcript via `thread/read`.
+- Supervisor sends text to an idle thread via `turn/start`.
+- Supervisor steers an active thread via `turn/steer`.
+- Supervisor interrupt stops an active turn via `turn/interrupt`.
+- Codex calls supervisor MCP and lists peer sessions.
+- An autonomous Codex is spawned and later human-attached.
+- Lost host connector marks sessions stale without deleting history.
+
+## Open Questions
+
+- Exact Codex TUI attach UX for an app-server thread spawned without a TUI.
+- Whether Codex should add `exec --remote` for headless live-shared runs.
+- Durable state owner: OpenClaw Gateway DB, Cloudflare Durable Object, or VPS database.
+- Approval policy granularity for supervisor-originated turns.
+- How much transcript summary should be injected into the always-on Claw context versus kept as a tool/resource.

package/docs/start/bootstrapping.md

@@ -0,0 +1,49 @@
+---
+summary: "Agent bootstrapping ritual that seeds the workspace and identity files"
+read_when:
+  - Understanding what happens on the first agent run
+  - Explaining where bootstrapping files live
+  - Debugging onboarding identity setup
+title: "Agent bootstrapping"
+sidebarTitle: "Bootstrapping"
+---
+
+Bootstrapping is the **first-run** ritual that prepares an agent workspace and
+collects identity details. It happens after onboarding, when the agent starts
+for the first time.
+
+## What bootstrapping does
+
+On the first agent run, OpenClaw bootstraps the workspace (default
+`~/.openclaw/workspace`):
+
+- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
+- Runs a short Q&A ritual (one question at a time).
+- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`.
+- Removes `BOOTSTRAP.md` when finished so it only runs once.
+
+For embedded/local model runs, OpenClaw keeps `BOOTSTRAP.md` out of the
+privileged system context. On the primary interactive first run, it still passes
+the file contents in the user prompt so models that do not reliably call the
+`read` tool can complete the ritual. If the current run cannot safely access the
+workspace, the agent gets a limited bootstrap note instead of a generic greeting.
+
+## Skipping bootstrapping
+
+To skip this for a pre-seeded workspace, run `openclaw onboard --skip-bootstrap`.
+
+## Where it runs
+
+Bootstrapping always runs on the **gateway host**. If the macOS app connects to
+a remote Gateway, the workspace and bootstrapping files live on that remote
+machine.
+
+<Note>
+When the Gateway runs on another machine, edit workspace files on the gateway
+host (for example, `user@gateway-host:~/.openclaw/workspace`).
+</Note>
+
+## Related docs
+
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Workspace layout: [Agent workspace](/concepts/agent-workspace)

package/docs/start/docs-directory.md

@@ -0,0 +1,69 @@
+---
+summary: "Curated links to the most used OpenClaw docs."
+read_when:
+  - You want quick access to key docs pages
+title: "Docs directory"
+---
+
+<Note>
+This page is a curated index. If you are new, start with [Getting Started](/start/getting-started).
+For a complete map of the docs, see [Docs hubs](/start/hubs).
+</Note>
+
+## Start here
+
+- [Docs hubs (all pages linked)](/start/hubs)
+- [Help](/help)
+- [Configuration](/gateway/configuration)
+- [Configuration examples](/gateway/configuration-examples)
+- [Slash commands](/tools/slash-commands)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Updating and rollback](/install/updating)
+- [Pairing (DM and nodes)](/channels/pairing)
+- [Nix mode](/install/nix)
+- [OpenClaw assistant setup](/start/openclaw)
+- [Skills](/tools/skills)
+- [Skills config](/tools/skills-config)
+- [Workspace templates](/reference/templates/AGENTS)
+- [RPC adapters](/reference/rpc)
+- [Gateway runbook](/gateway)
+- [Nodes (iOS and Android)](/nodes)
+- [Web surfaces (Control UI)](/web)
+- [Discovery and transports](/gateway/discovery)
+- [Remote access](/gateway/remote)
+
+## Providers and UX
+
+- [WebChat](/web/webchat)
+- [Control UI (browser)](/web/control-ui)
+- [Telegram](/channels/telegram)
+- [Discord](/channels/discord)
+- [Mattermost](/channels/mattermost)
+- [QQ Bot](/channels/qqbot)
+- [iMessage](/channels/imessage)
+- [Groups](/channels/groups)
+- [WhatsApp group messages](/channels/group-messages)
+- [Media images](/nodes/images)
+- [Media audio](/nodes/audio)
+
+## Companion apps
+
+- [macOS app](/platforms/macos)
+- [iOS app](/platforms/ios)
+- [Android app](/platforms/android)
+- [Windows Hub](/platforms/windows)
+- [Linux app](/platforms/linux)
+
+## Operations and safety
+
+- [Sessions](/concepts/session)
+- [Cron jobs](/automation/cron-jobs)
+- [Webhooks](/automation/cron-jobs#webhooks)
+- [Gmail hooks (Pub/Sub)](/automation/cron-jobs#gmail-pubsub-integration)
+- [Security](/gateway/security)
+- [Troubleshooting](/gateway/troubleshooting)
+
+## Related
+
+- [Getting started](/start/getting-started)
+- [Docs hubs](/start/hubs)

package/docs/start/getting-started.md

@@ -0,0 +1,152 @@
+---
+summary: "Get OpenClaw installed and run your first chat in minutes."
+read_when:
+  - First time setup from zero
+  - You want the fastest path to a working chat
+title: "Getting started"
+---
+
+Install OpenClaw, run onboarding, and chat with your AI assistant — all in
+about 5 minutes. By the end you will have a running Gateway, configured auth,
+and a working chat session.
+
+## What you need
+
+- **Node.js** — Node 24 recommended (Node 22.19+ also supported)
+- **An API key** from a model provider (Anthropic, OpenAI, Google, etc.) — onboarding will prompt you
+
+<Tip>
+Check your Node version with `node --version`.
+**Windows users:** the native Windows Hub app is the easiest desktop path. The
+PowerShell installer and WSL2 Gateway paths are also supported. See [Windows](/platforms/windows).
+Need to install Node? See [Node setup](/install/node).
+</Tip>
+
+## Quick setup
+
+<Steps>
+  <Step title="Install OpenClaw">
+    <Tabs>
+      <Tab title="macOS / Linux">
+        ```bash
+        curl -fsSL https://openclaw.ai/install.sh | bash
+        ```
+        <img
+  src="/assets/install-script.svg"
+  alt="Install Script Process"
+  className="rounded-lg"
+/>
+      </Tab>
+      <Tab title="Windows (PowerShell)">
+        ```powershell
+        iwr -useb https://openclaw.ai/install.ps1 | iex
+        ```
+      </Tab>
+    </Tabs>
+
+    <Note>
+    Other install methods (Docker, Nix, npm): [Install](/install).
+    </Note>
+
+  </Step>
+  <Step title="Run onboarding">
+    ```bash
+    openclaw onboard --install-daemon
+    ```
+
+    The wizard walks you through choosing a model provider, setting an API key,
+    and configuring the Gateway. It takes about 2 minutes.
+
+    See [Onboarding (CLI)](/start/wizard) for the full reference.
+
+  </Step>
+  <Step title="Verify the Gateway is running">
+    ```bash
+    openclaw gateway status
+    ```
+
+    You should see the Gateway listening on port 18789.
+
+  </Step>
+  <Step title="Open the dashboard">
+    ```bash
+    openclaw dashboard
+    ```
+
+    This opens the Control UI in your browser. If it loads, everything is working.
+
+  </Step>
+  <Step title="Send your first message">
+    Type a message in the Control UI chat and you should get an AI reply.
+
+    Want to chat from your phone instead? The fastest channel to set up is
+    [Telegram](/channels/telegram) (just a bot token). See [Channels](/channels)
+    for all options.
+
+  </Step>
+</Steps>
+
+<Accordion title="Advanced: mount a custom Control UI build">
+  If you maintain a localized or customized dashboard build, point
+  `gateway.controlUi.root` to a directory that contains your built static
+  assets and `index.html`.
+
+```bash
+mkdir -p "$HOME/.openclaw/control-ui-custom"
+# Copy your built static files into that directory.
+```
+
+Then set:
+
+```json
+{
+  "gateway": {
+    "controlUi": {
+      "enabled": true,
+      "root": "$HOME/.openclaw/control-ui-custom"
+    }
+  }
+}
+```
+
+Restart the gateway and reopen the dashboard:
+
+```bash
+openclaw gateway restart
+openclaw dashboard
+```
+
+</Accordion>
+
+## What to do next
+
+<Columns>
+  <Card title="Connect a channel" href="/channels" icon="message-square">
+    Discord, Feishu, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and more.
+  </Card>
+  <Card title="Pairing and safety" href="/channels/pairing" icon="shield">
+    Control who can message your agent.
+  </Card>
+  <Card title="Configure the Gateway" href="/gateway/configuration" icon="settings">
+    Models, tools, sandbox, and advanced settings.
+  </Card>
+  <Card title="Browse tools" href="/tools" icon="wrench">
+    Browser, exec, web search, skills, and plugins.
+  </Card>
+</Columns>
+
+<Accordion title="Advanced: environment variables">
+  If you run OpenClaw as a service account or want custom paths:
+
+- `OPENCLAW_HOME` — home directory for internal path resolution
+- `OPENCLAW_STATE_DIR` — override the state directory
+- `OPENCLAW_CONFIG_PATH` — override the config file path
+
+Full reference: [Environment variables](/help/environment).
+</Accordion>
+
+## Related
+
+- [Install overview](/install)
+- [Channels overview](/channels)
+- [Setup](/start/setup)