@termix-it/cryptoclaw 1.0.0

package/docs/images/groups-flow.svg

@@ -0,0 +1,52 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="260" viewBox="0 0 960 260" role="img" aria-label="Group message flow">
+  <defs>
+    <style>
+      .box { fill: #f6f5f3; stroke: #2b2b2b; stroke-width: 2; }
+      .drop { fill: #fff1f1; stroke: #a33; stroke-width: 2; }
+      .note { fill: #fffaf0; stroke: #9a7b00; stroke-width: 2; }
+      .text { font: 14px "SF Pro Text", -apple-system, Helvetica, Arial, sans-serif; fill: #1a1a1a; }
+      .label { font: 12px "SF Pro Text", -apple-system, Helvetica, Arial, sans-serif; fill: #333; }
+      .arrow { stroke: #2b2b2b; stroke-width: 2; fill: none; marker-end: url(#arrow); }
+    </style>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6 Z" fill="#2b2b2b" />
+    </marker>
+  </defs>
+
+  <rect class="box" x="20" y="40" width="140" height="60" rx="8" />
+  <text class="text" x="90" y="75" text-anchor="middle">Group message</text>
+
+  <rect class="box" x="200" y="40" width="160" height="60" rx="8" />
+  <text class="text" x="280" y="68" text-anchor="middle">Group policy</text>
+  <text class="label" x="280" y="86" text-anchor="middle">open / disabled / allowlist</text>
+
+  <rect class="box" x="400" y="40" width="150" height="60" rx="8" />
+  <text class="text" x="475" y="75" text-anchor="middle">Allowlist</text>
+
+  <rect class="box" x="580" y="40" width="170" height="60" rx="8" />
+  <text class="text" x="665" y="68" text-anchor="middle">Mention gating</text>
+  <text class="label" x="665" y="86" text-anchor="middle">requireMention</text>
+
+  <rect class="box" x="780" y="40" width="140" height="60" rx="8" />
+  <text class="text" x="850" y="75" text-anchor="middle">Reply</text>
+
+  <line class="arrow" x1="160" y1="70" x2="200" y2="70" />
+  <line class="arrow" x1="360" y1="70" x2="400" y2="70" />
+  <line class="arrow" x1="550" y1="70" x2="580" y2="70" />
+  <line class="arrow" x1="750" y1="70" x2="780" y2="70" />
+
+  <rect class="drop" x="220" y="150" width="120" height="50" rx="8" />
+  <text class="text" x="280" y="180" text-anchor="middle">Drop</text>
+  <line class="arrow" x1="280" y1="100" x2="280" y2="150" />
+  <text class="label" x="250" y="130" text-anchor="end">disabled</text>
+
+  <rect class="drop" x="410" y="150" width="120" height="50" rx="8" />
+  <text class="text" x="470" y="180" text-anchor="middle">Drop</text>
+  <line class="arrow" x1="475" y1="100" x2="470" y2="150" />
+  <text class="label" x="445" y="130" text-anchor="end">not allowed</text>
+
+  <rect class="note" x="600" y="150" width="200" height="50" rx="8" />
+  <text class="text" x="700" y="175" text-anchor="middle">Store for context</text>
+  <text class="label" x="700" y="192" text-anchor="middle">(no mention)</text>
+  <line class="arrow" x1="665" y1="100" x2="700" y2="150" />
+</svg>

package/docs/index.md

@@ -0,0 +1,192 @@
+---
+summary: "OpenClaw is a multi-channel gateway for AI agents that runs on any OS."
+read_when:
+  - Introducing OpenClaw to newcomers
+title: "OpenClaw"
+---
+
+# OpenClaw 🦞
+
+<p align="center">
+    <img
+        src="/assets/openclaw-logo-text-dark.png"
+        alt="OpenClaw"
+        width="500"
+        class="dark:hidden"
+    />
+    <img
+        src="/assets/openclaw-logo-text.png"
+        alt="OpenClaw"
+        width="500"
+        class="hidden dark:block"
+    />
+</p>
+
+> _"EXFOLIATE! EXFOLIATE!"_ — A space lobster, probably
+
+<p align="center">
+  <strong>Any OS gateway for AI agents across WhatsApp, Telegram, Discord, iMessage, and more.</strong><br />
+  Send a message, get an agent response from your pocket. Plugins add Mattermost and more.
+</p>
+
+<Columns>
+  <Card title="Get Started" href="/start/getting-started" icon="rocket">
+    Install OpenClaw and bring up the Gateway in minutes.
+  </Card>
+  <Card title="Run the Wizard" href="/start/wizard" icon="sparkles">
+    Guided setup with `openclaw onboard` and pairing flows.
+  </Card>
+  <Card title="Open the Control UI" href="/web/control-ui" icon="layout-dashboard">
+    Launch the browser dashboard for chat, config, and sessions.
+  </Card>
+</Columns>
+
+## What is OpenClaw?
+
+OpenClaw is a **self-hosted gateway** that connects your favorite chat apps — WhatsApp, Telegram, Discord, iMessage, and more — to AI coding agents like Pi. You run a single Gateway process on your own machine (or a server), and it becomes the bridge between your messaging apps and an always-available AI assistant.
+
+**Who is it for?** Developers and power users who want a personal AI assistant they can message from anywhere — without giving up control of their data or relying on a hosted service.
+
+**What makes it different?**
+
+- **Self-hosted**: runs on your hardware, your rules
+- **Multi-channel**: one Gateway serves WhatsApp, Telegram, Discord, and more simultaneously
+- **Agent-native**: built for coding agents with tool use, sessions, memory, and multi-agent routing
+- **Open source**: MIT licensed, community-driven
+
+**What do you need?** Node 22+, an API key (Anthropic recommended), and 5 minutes.
+
+## How it works
+
+```mermaid
+flowchart LR
+  A["Chat apps + plugins"] --> B["Gateway"]
+  B --> C["Pi agent"]
+  B --> D["CLI"]
+  B --> E["Web Control UI"]
+  B --> F["macOS app"]
+  B --> G["iOS and Android nodes"]
+```
+
+The Gateway is the single source of truth for sessions, routing, and channel connections.
+
+## Key capabilities
+
+<Columns>
+  <Card title="Multi-channel gateway" icon="network">
+    WhatsApp, Telegram, Discord, and iMessage with a single Gateway process.
+  </Card>
+  <Card title="Plugin channels" icon="plug">
+    Add Mattermost and more with extension packages.
+  </Card>
+  <Card title="Multi-agent routing" icon="route">
+    Isolated sessions per agent, workspace, or sender.
+  </Card>
+  <Card title="Media support" icon="image">
+    Send and receive images, audio, and documents.
+  </Card>
+  <Card title="Web Control UI" icon="monitor">
+    Browser dashboard for chat, config, sessions, and nodes.
+  </Card>
+  <Card title="Mobile nodes" icon="smartphone">
+    Pair iOS and Android nodes with Canvas support.
+  </Card>
+</Columns>
+
+## Quick start
+
+<Steps>
+  <Step title="Install OpenClaw">
+    ```bash
+    npm install -g openclaw@latest
+    ```
+  </Step>
+  <Step title="Onboard and install the service">
+    ```bash
+    openclaw onboard --install-daemon
+    ```
+  </Step>
+  <Step title="Pair WhatsApp and start the Gateway">
+    ```bash
+    openclaw channels login
+    openclaw gateway --port 18789
+    ```
+  </Step>
+</Steps>
+
+Need the full install and dev setup? See [Quick start](/start/quickstart).
+
+## Dashboard
+
+Open the browser Control UI after the Gateway starts.
+
+- Local default: http://127.0.0.1:18789/
+- Remote access: [Web surfaces](/web) and [Tailscale](/gateway/tailscale)
+
+<p align="center">
+  <img src="whatsapp-openclaw.jpg" alt="OpenClaw" width="420" />
+</p>
+
+## Configuration (optional)
+
+Config lives at `~/.openclaw/openclaw.json`.
+
+- If you **do nothing**, OpenClaw uses the bundled Pi binary in RPC mode with per-sender sessions.
+- If you want to lock it down, start with `channels.whatsapp.allowFrom` and (for groups) mention rules.
+
+Example:
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      allowFrom: ["+15555550123"],
+      groups: { "*": { requireMention: true } },
+    },
+  },
+  messages: { groupChat: { mentionPatterns: ["@openclaw"] } },
+}
+```
+
+## Start here
+
+<Columns>
+  <Card title="Docs hubs" href="/start/hubs" icon="book-open">
+    All docs and guides, organized by use case.
+  </Card>
+  <Card title="Configuration" href="/gateway/configuration" icon="settings">
+    Core Gateway settings, tokens, and provider config.
+  </Card>
+  <Card title="Remote access" href="/gateway/remote" icon="globe">
+    SSH and tailnet access patterns.
+  </Card>
+  <Card title="Channels" href="/channels/telegram" icon="message-square">
+    Channel-specific setup for WhatsApp, Telegram, Discord, and more.
+  </Card>
+  <Card title="Nodes" href="/nodes" icon="smartphone">
+    iOS and Android nodes with pairing and Canvas.
+  </Card>
+  <Card title="Help" href="/help" icon="life-buoy">
+    Common fixes and troubleshooting entry point.
+  </Card>
+</Columns>
+
+## Learn more
+
+<Columns>
+  <Card title="Full feature list" href="/concepts/features" icon="list">
+    Complete channel, routing, and media capabilities.
+  </Card>
+  <Card title="Multi-agent routing" href="/concepts/multi-agent" icon="route">
+    Workspace isolation and per-agent sessions.
+  </Card>
+  <Card title="Security" href="/gateway/security" icon="shield">
+    Tokens, allowlists, and safety controls.
+  </Card>
+  <Card title="Troubleshooting" href="/gateway/troubleshooting" icon="wrench">
+    Gateway diagnostics and common errors.
+  </Card>
+  <Card title="About and credits" href="/reference/credits" icon="info">
+    Project origins, contributors, and license.
+  </Card>
+</Columns>

package/docs/install/ansible.md

@@ -0,0 +1,208 @@
+---
+summary: "Automated, hardened OpenClaw installation with Ansible, Tailscale VPN, and firewall isolation"
+read_when:
+  - You want automated server deployment with security hardening
+  - You need firewall-isolated setup with VPN access
+  - You're deploying to remote Debian/Ubuntu servers
+title: "Ansible"
+---
+
+# Ansible Installation
+
+The recommended way to deploy OpenClaw to production servers is via **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** — an automated installer with security-first architecture.
+
+## Quick Start
+
+One-command install:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash
+```
+
+> **📦 Full guide: [github.com/openclaw/openclaw-ansible](https://github.com/openclaw/openclaw-ansible)**
+>
+> The openclaw-ansible repo is the source of truth for Ansible deployment. This page is a quick overview.
+
+## What You Get
+
+- 🔒 **Firewall-first security**: UFW + Docker isolation (only SSH + Tailscale accessible)
+- 🔐 **Tailscale VPN**: Secure remote access without exposing services publicly
+- 🐳 **Docker**: Isolated sandbox containers, localhost-only bindings
+- 🛡️ **Defense in depth**: 4-layer security architecture
+- 🚀 **One-command setup**: Complete deployment in minutes
+- 🔧 **Systemd integration**: Auto-start on boot with hardening
+
+## Requirements
+
+- **OS**: Debian 11+ or Ubuntu 20.04+
+- **Access**: Root or sudo privileges
+- **Network**: Internet connection for package installation
+- **Ansible**: 2.14+ (installed automatically by quick-start script)
+
+## What Gets Installed
+
+The Ansible playbook installs and configures:
+
+1. **Tailscale** (mesh VPN for secure remote access)
+2. **UFW firewall** (SSH + Tailscale ports only)
+3. **Docker CE + Compose V2** (for agent sandboxes)
+4. **Node.js 22.x + pnpm** (runtime dependencies)
+5. **OpenClaw** (host-based, not containerized)
+6. **Systemd service** (auto-start with security hardening)
+
+Note: The gateway runs **directly on the host** (not in Docker), but agent sandboxes use Docker for isolation. See [Sandboxing](/gateway/sandboxing) for details.
+
+## Post-Install Setup
+
+After installation completes, switch to the openclaw user:
+
+```bash
+sudo -i -u openclaw
+```
+
+The post-install script will guide you through:
+
+1. **Onboarding wizard**: Configure OpenClaw settings
+2. **Provider login**: Connect WhatsApp/Telegram/Discord/Signal
+3. **Gateway testing**: Verify the installation
+4. **Tailscale setup**: Connect to your VPN mesh
+
+### Quick commands
+
+```bash
+# Check service status
+sudo systemctl status openclaw
+
+# View live logs
+sudo journalctl -u openclaw -f
+
+# Restart gateway
+sudo systemctl restart openclaw
+
+# Provider login (run as openclaw user)
+sudo -i -u openclaw
+openclaw channels login
+```
+
+## Security Architecture
+
+### 4-Layer Defense
+
+1. **Firewall (UFW)**: Only SSH (22) + Tailscale (41641/udp) exposed publicly
+2. **VPN (Tailscale)**: Gateway accessible only via VPN mesh
+3. **Docker Isolation**: DOCKER-USER iptables chain prevents external port exposure
+4. **Systemd Hardening**: NoNewPrivileges, PrivateTmp, unprivileged user
+
+### Verification
+
+Test external attack surface:
+
+```bash
+nmap -p- YOUR_SERVER_IP
+```
+
+Should show **only port 22** (SSH) open. All other services (gateway, Docker) are locked down.
+
+### Docker Availability
+
+Docker is installed for **agent sandboxes** (isolated tool execution), not for running the gateway itself. The gateway binds to localhost only and is accessible via Tailscale VPN.
+
+See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for sandbox configuration.
+
+## Manual Installation
+
+If you prefer manual control over the automation:
+
+```bash
+# 1. Install prerequisites
+sudo apt update && sudo apt install -y ansible git
+
+# 2. Clone repository
+git clone https://github.com/openclaw/openclaw-ansible.git
+cd openclaw-ansible
+
+# 3. Install Ansible collections
+ansible-galaxy collection install -r requirements.yml
+
+# 4. Run playbook
+./run-playbook.sh
+
+# Or run directly (then manually execute /tmp/openclaw-setup.sh after)
+# ansible-playbook playbook.yml --ask-become-pass
+```
+
+## Updating OpenClaw
+
+The Ansible installer sets up OpenClaw for manual updates. See [Updating](/install/updating) for the standard update flow.
+
+To re-run the Ansible playbook (e.g., for configuration changes):
+
+```bash
+cd openclaw-ansible
+./run-playbook.sh
+```
+
+Note: This is idempotent and safe to run multiple times.
+
+## Troubleshooting
+
+### Firewall blocks my connection
+
+If you're locked out:
+
+- Ensure you can access via Tailscale VPN first
+- SSH access (port 22) is always allowed
+- The gateway is **only** accessible via Tailscale by design
+
+### Service won't start
+
+```bash
+# Check logs
+sudo journalctl -u openclaw -n 100
+
+# Verify permissions
+sudo ls -la /opt/openclaw
+
+# Test manual start
+sudo -i -u openclaw
+cd ~/openclaw
+pnpm start
+```
+
+### Docker sandbox issues
+
+```bash
+# Verify Docker is running
+sudo systemctl status docker
+
+# Check sandbox image
+sudo docker images | grep openclaw-sandbox
+
+# Build sandbox image if missing
+cd /opt/openclaw/openclaw
+sudo -u openclaw ./scripts/sandbox-setup.sh
+```
+
+### Provider login fails
+
+Make sure you're running as the `openclaw` user:
+
+```bash
+sudo -i -u openclaw
+openclaw channels login
+```
+
+## Advanced Configuration
+
+For detailed security architecture and troubleshooting:
+
+- [Security Architecture](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md)
+- [Technical Details](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md)
+- [Troubleshooting Guide](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md)
+
+## Related
+
+- [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — full deployment guide
+- [Docker](/install/docker) — containerized gateway setup
+- [Sandboxing](/gateway/sandboxing) — agent sandbox configuration
+- [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) — per-agent isolation

package/docs/install/bun.md

@@ -0,0 +1,59 @@
+---
+summary: "Bun workflow (experimental): installs and gotchas vs pnpm"
+read_when:
+  - You want the fastest local dev loop (bun + watch)
+  - You hit Bun install/patch/lifecycle script issues
+title: "Bun (Experimental)"
+---
+
+# Bun (experimental)
+
+Goal: run this repo with **Bun** (optional, not recommended for WhatsApp/Telegram)
+without diverging from pnpm workflows.
+
+⚠️ **Not recommended for Gateway runtime** (WhatsApp/Telegram bugs). Use Node for production.
+
+## Status
+
+- Bun is an optional local runtime for running TypeScript directly (`bun run …`, `bun --watch …`).
+- `pnpm` is the default for builds and remains fully supported (and used by some docs tooling).
+- Bun cannot use `pnpm-lock.yaml` and will ignore it.
+
+## Install
+
+Default:
+
+```sh
+bun install
+```
+
+Note: `bun.lock`/`bun.lockb` are gitignored, so there’s no repo churn either way. If you want _no lockfile writes_:
+
+```sh
+bun install --no-save
+```
+
+## Build / Test (Bun)
+
+```sh
+bun run build
+bun run vitest run
+```
+
+## Bun lifecycle scripts (blocked by default)
+
+Bun may block dependency lifecycle scripts unless explicitly trusted (`bun pm untrusted` / `bun pm trust`).
+For this repo, the commonly blocked scripts are not required:
+
+- `@whiskeysockets/baileys` `preinstall`: checks Node major >= 20 (we run Node 22+).
+- `protobufjs` `postinstall`: emits warnings about incompatible version schemes (no build artifacts).
+
+If you hit a real runtime issue that requires these scripts, trust them explicitly:
+
+```sh
+bun pm trust @whiskeysockets/baileys protobufjs
+```
+
+## Caveats
+
+- Some scripts still hardcode pnpm (e.g. `docs:build`, `ui:*`, `protocol:check`). Run those via pnpm for now.

package/docs/install/development-channels.md

@@ -0,0 +1,75 @@
+---
+summary: "Stable, beta, and dev channels: semantics, switching, and tagging"
+read_when:
+  - You want to switch between stable/beta/dev
+  - You are tagging or publishing prereleases
+title: "Development Channels"
+---
+
+# Development channels
+
+Last updated: 2026-01-21
+
+OpenClaw ships three update channels:
+
+- **stable**: npm dist-tag `latest`.
+- **beta**: npm dist-tag `beta` (builds under test).
+- **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).
+
+We ship builds to **beta**, test them, then **promote a vetted build to `latest`**
+without changing the version number — dist-tags are the source of truth for npm installs.
+
+## Switching channels
+
+Git checkout:
+
+```bash
+openclaw update --channel stable
+openclaw update --channel beta
+openclaw update --channel dev
+```
+
+- `stable`/`beta` check out the latest matching tag (often the same tag).
+- `dev` switches to `main` and rebases on the upstream.
+
+npm/pnpm global install:
+
+```bash
+openclaw update --channel stable
+openclaw update --channel beta
+openclaw update --channel dev
+```
+
+This updates via the corresponding npm dist-tag (`latest`, `beta`, `dev`).
+
+When you **explicitly** switch channels with `--channel`, OpenClaw also aligns
+the install method:
+
+- `dev` ensures a git checkout (default `~/openclaw`, override with `OPENCLAW_GIT_DIR`),
+  updates it, and installs the global CLI from that checkout.
+- `stable`/`beta` installs from npm using the matching dist-tag.
+
+Tip: if you want stable + dev in parallel, keep two clones and point your gateway at the stable one.
+
+## Plugins and channels
+
+When you switch channels with `openclaw update`, OpenClaw also syncs plugin sources:
+
+- `dev` prefers bundled plugins from the git checkout.
+- `stable` and `beta` restore npm-installed plugin packages.
+
+## Tagging best practices
+
+- Tag releases you want git checkouts to land on (`vYYYY.M.D` or `vYYYY.M.D-<patch>`).
+- Keep tags immutable: never move or reuse a tag.
+- npm dist-tags remain the source of truth for npm installs:
+  - `latest` → stable
+  - `beta` → candidate build
+  - `dev` → main snapshot (optional)
+
+## macOS app availability
+
+Beta and dev builds may **not** include a macOS app release. That’s OK:
+
+- The git tag and npm dist-tag can still be published.
+- Call out “no macOS build for this beta” in release notes or changelog.