vilvona 1.0.0

package/docs/plan/ui-channels.md

@@ -0,0 +1,284 @@
+---
+summary: Decouple semantic message presentation from channel native UI renderers.
+title: Channel presentation refactor plan
+read_when:
+  - Refactoring channel message UI, interactive payloads, or native channel renderers
+  - Changing message tool capabilities, delivery hints, or cross-context markers
+  - Debugging Discord Carbon import fanout or channel plugin runtime laziness
+---
+
+## Status
+
+Implemented for the shared agent, CLI, plugin capability, and outbound delivery surfaces:
+
+- `ReplyPayload.presentation` carries semantic message UI.
+- `ReplyPayload.delivery.pin` carries sent-message pin requests.
+- Shared message actions expose `presentation`, `delivery`, and `pin` instead of provider-native `components`, `blocks`, `buttons`, or `card`.
+- Core renders or auto-degrades presentation through plugin-declared outbound capabilities.
+- Discord, Slack, Telegram, Mattermost, MS Teams, and Feishu renderers consume the generic contract.
+- Discord channel control-plane code no longer imports Carbon-backed UI containers.
+
+Canonical docs now live in [Message Presentation](/plugins/message-presentation).
+Keep this plan as historical implementation context; update the canonical guide
+for contract, renderer, or fallback behavior changes.
+
+## Problem
+
+Channel UI is currently split across several incompatible surfaces:
+
+- Core owns a Discord-shaped cross-context renderer hook through `buildCrossContextComponents`.
+- Discord `channel.ts` can import native Carbon UI through `DiscordUiContainer`, which pulls runtime UI dependencies into the channel plugin control plane.
+- The agent and CLI expose native payload escape hatches such as Discord `components`, Slack `blocks`, Telegram or Mattermost `buttons`, and Teams or Feishu `card`.
+- `ReplyPayload.channelData` carries both transport hints and native UI envelopes.
+- The generic `interactive` model exists, but it is narrower than the richer layouts already used by Discord, Slack, Teams, Feishu, LINE, Telegram, and Mattermost.
+
+This makes core aware of native UI shapes, weakens plugin runtime laziness, and gives agents too many provider-specific ways to express the same message intent.
+
+## Goals
+
+- Core decides the best semantic presentation for a message from declared capabilities.
+- Extensions declare capabilities and render semantic presentation into native transport payloads.
+- Web Control UI remains separate from chat native UI.
+- Native channel payloads are not exposed through the shared agent or CLI message surface.
+- Unsupported presentation features auto-degrade to the best text representation.
+- Delivery behavior such as pinning a sent message is generic delivery metadata, not presentation.
+
+## Non goals
+
+- No backwards compatibility shim for `buildCrossContextComponents`.
+- No public native escape hatches for `components`, `blocks`, `buttons`, or `card`.
+- No core imports of channel-native UI libraries.
+- No provider-specific SDK seams for bundled channels.
+
+## Target model
+
+Add a core-owned `presentation` field to `ReplyPayload`.
+
+```ts
+type MessagePresentationTone = "neutral" | "info" | "success" | "warning" | "danger";
+
+type MessagePresentation = {
+  tone?: MessagePresentationTone;
+  title?: string;
+  blocks: MessagePresentationBlock[];
+};
+
+type MessagePresentationBlock =
+  | { type: "text"; text: string }
+  | { type: "context"; text: string }
+  | { type: "divider" }
+  | { type: "buttons"; buttons: MessagePresentationButton[] }
+  | { type: "select"; placeholder?: string; options: MessagePresentationOption[] };
+
+type MessagePresentationButton = {
+  label: string;
+  value?: string;
+  url?: string;
+  style?: "primary" | "secondary" | "success" | "danger";
+};
+
+type MessagePresentationOption = {
+  label: string;
+  value: string;
+};
+```
+
+`interactive` becomes a subset of `presentation` during migration:
+
+- `interactive` text block maps to `presentation.blocks[].type = "text"`.
+- `interactive` buttons block maps to `presentation.blocks[].type = "buttons"`.
+- `interactive` select block maps to `presentation.blocks[].type = "select"`.
+
+The external agent and CLI schemas now use `presentation`; `interactive` remains an internal legacy parser/rendering helper for existing reply producers.
+The public producer-facing API treats `interactive` as deprecated. Runtime
+support remains so existing approval helpers and older plugins continue to
+work while new code emits `presentation`.
+
+## Delivery metadata
+
+Add a core-owned `delivery` field for send behavior that is not UI.
+
+```ts
+type ReplyPayloadDelivery = {
+  pin?:
+    | boolean
+    | {
+        enabled: boolean;
+        notify?: boolean;
+        required?: boolean;
+      };
+};
+```
+
+Semantics:
+
+- `delivery.pin = true` means pin the first successfully delivered message.
+- `notify` defaults to `false`.
+- `required` defaults to `false`; unsupported channels or failed pinning auto-degrade by continuing delivery.
+- Manual `pin`, `unpin`, and `list-pins` message actions remain for existing messages.
+
+Current Telegram ACP topic binding should move from `channelData.telegram.pin = true` to `delivery.pin = true`.
+
+## Runtime capability contract
+
+Add presentation and delivery render hooks to the runtime outbound adapter, not the control-plane channel plugin.
+
+```ts
+type ChannelPresentationCapabilities = {
+  supported: boolean;
+  buttons?: boolean;
+  selects?: boolean;
+  context?: boolean;
+  divider?: boolean;
+  tones?: MessagePresentationTone[];
+  limits?: {
+    actions?: {
+      maxActions?: number;
+      maxActionsPerRow?: number;
+      maxRows?: number;
+      maxLabelLength?: number;
+      maxValueBytes?: number;
+      supportsStyles?: boolean;
+      supportsDisabled?: boolean;
+      supportsLayoutHints?: boolean;
+    };
+    selects?: {
+      maxOptions?: number;
+      maxLabelLength?: number;
+      maxValueBytes?: number;
+    };
+    text?: {
+      maxLength?: number;
+      encoding?: "characters" | "utf8-bytes" | "utf16-units";
+      markdownDialect?: "plain" | "markdown" | "html" | "slack-mrkdwn" | "discord-markdown";
+      supportsEdit?: boolean;
+    };
+  };
+};
+
+type ChannelDeliveryCapabilities = {
+  pinSentMessage?: boolean;
+};
+
+type ChannelOutboundAdapter = {
+  presentationCapabilities?: ChannelPresentationCapabilities;
+
+  renderPresentation?: (params: {
+    payload: ReplyPayload;
+    presentation: MessagePresentation;
+    ctx: ChannelOutboundSendContext;
+  }) => ReplyPayload | null;
+
+  deliveryCapabilities?: ChannelDeliveryCapabilities;
+
+  pinDeliveredMessage?: (params: {
+    cfg: OpenClawConfig;
+    accountId?: string | null;
+    to: string;
+    threadId?: string | number | null;
+    messageId: string;
+    notify: boolean;
+  }) => Promise<void>;
+};
+```
+
+Core behavior:
+
+- Resolve target channel and runtime adapter.
+- Ask for presentation capabilities.
+- Degrade unsupported blocks and apply generic capability limits before
+  rendering.
+- Call `renderPresentation`.
+- If no renderer exists, convert presentation to text fallback.
+- After successful send, call `pinDeliveredMessage` when `delivery.pin` is requested and supported.
+
+## Channel mapping
+
+Discord:
+
+- Render `presentation` to components v2 and Carbon containers in runtime-only modules.
+- Keep accent color helpers in light modules.
+- Remove `DiscordUiContainer` imports from channel plugin control-plane code.
+
+Slack:
+
+- Render `presentation` to Block Kit.
+- Remove agent and CLI `blocks` input.
+
+Telegram:
+
+- Render text, context, and dividers as text.
+- Render actions and select as inline keyboards when configured and allowed for the target surface.
+- Use text fallback when inline buttons are disabled.
+- Move ACP topic pinning to `delivery.pin`.
+
+Mattermost:
+
+- Render actions as interactive buttons where configured.
+- Render other blocks as text fallback.
+
+MS Teams:
+
+- Render `presentation` to Adaptive Cards.
+- Keep manual pin/unpin/list-pins actions.
+- Optionally implement `pinDeliveredMessage` if Graph support is reliable for the target conversation.
+
+Feishu:
+
+- Render `presentation` to interactive cards.
+- Keep manual pin/unpin/list-pins actions.
+- Optionally implement `pinDeliveredMessage` for sent-message pinning if API behavior is reliable.
+
+LINE:
+
+- Render `presentation` to Flex or template messages where possible.
+- Fall back to text for unsupported blocks.
+- Remove LINE UI payloads from `channelData`.
+
+Plain or limited channels:
+
+- Convert presentation to text with conservative formatting.
+
+## Refactor steps
+
+1. Reapply the Discord release fix that splits `ui-colors.ts` from Carbon-backed UI and removes `DiscordUiContainer` from `extensions/discord/src/channel.ts`.
+2. Add `presentation` and `delivery` to `ReplyPayload`, outbound payload normalization, delivery summaries, and hook payloads.
+3. Add `MessagePresentation` schema and parser helpers in a narrow SDK/runtime subpath.
+4. Replace message capabilities `buttons`, `cards`, `components`, and `blocks` with semantic presentation capabilities.
+5. Add runtime outbound adapter hooks for presentation render and delivery pinning.
+6. Replace cross-context component construction with `buildCrossContextPresentation`.
+7. Delete `src/infra/outbound/channel-adapters.ts` and remove `buildCrossContextComponents` from channel plugin types.
+8. Change `maybeApplyCrossContextMarker` to attach `presentation` instead of native params.
+9. Update plugin-dispatch send paths to consume only semantic presentation and delivery metadata.
+10. Remove agent and CLI native payload params: `components`, `blocks`, `buttons`, and `card`.
+11. Remove SDK helpers that create native message-tool schemas, replacing them with presentation schema helpers.
+12. Remove UI/native envelopes from `channelData`; keep only transport metadata until each remaining field is reviewed.
+13. Migrate Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, and LINE renderers.
+14. Update docs for message CLI, channel pages, plugin SDK, and capability cookbook.
+15. Run import fanout profiling for Discord and affected channel entrypoints.
+
+Steps 1-11 and 13-14 are implemented in this refactor for the shared agent, CLI, plugin capability, and outbound adapter contracts. Step 12 remains a deeper internal cleanup pass for provider-private `channelData` transport envelopes. Step 15 remains follow-up validation if we want quantified import-fanout numbers beyond the type/test gate.
+
+## Tests
+
+Add or update:
+
+- Presentation normalization tests.
+- Presentation auto-degrade tests for unsupported blocks.
+- Cross-context marker tests for plugin dispatch and core delivery paths.
+- Channel render matrix tests for Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, LINE, and text fallback.
+- Message tool schema tests proving native fields are gone.
+- CLI tests proving native flags are gone.
+- Discord entrypoint import-laziness regression covering Carbon.
+- Delivery pin tests covering Telegram and generic fallback.
+
+## Open questions
+
+- Should `delivery.pin` be implemented for Discord, Slack, MS Teams, and Feishu in the first pass, or only Telegram first?
+- Should `delivery` eventually absorb existing fields such as `replyToId`, `replyToCurrent`, `silent`, and `audioAsVoice`, or stay focused on post-send behaviors?
+- Should presentation support images or file references directly, or should media remain separate from UI layout for now?
+
+## Related
+
+- [Channels overview](/channels)
+- [Message presentation](/plugins/message-presentation)

package/docs/platforms/android.md

@@ -0,0 +1,286 @@
+---
+summary: "Android app (node): connection runbook + Connect/Chat/Voice/Canvas command surface"
+read_when:
+  - Pairing or reconnecting the Android node
+  - Debugging Android gateway discovery or auth
+  - Verifying chat history parity across clients
+title: "Android app"
+---
+
+<Note>
+The official Android app is available on [Google Play](https://play.google.com/store/apps/details?id=ai.openclaw.app&hl=en_IN). It is a companion node and requires a running OpenClaw Gateway. The source code is also available in the [OpenClaw repository](https://github.com/openclaw/openclaw) under `apps/android`; see [apps/android/README.md](https://github.com/openclaw/openclaw/blob/main/apps/android/README.md) for build instructions.
+</Note>
+
+## Support snapshot
+
+- Role: companion node app (Android does not host the Gateway).
+- Gateway required: yes (run it on macOS, Linux, or Windows via WSL2).
+- Install: [Google Play](https://play.google.com/store/apps/details?id=ai.openclaw.app&hl=en_IN) for the app, [Getting Started](/start/getting-started) for the Gateway, then [Pairing](/channels/pairing).
+- Gateway: [Runbook](/gateway) + [Configuration](/gateway/configuration).
+  - Protocols: [Gateway protocol](/gateway/protocol) (nodes + control plane).
+
+## System control
+
+System control (launchd/systemd) lives on the Gateway host. See [Gateway](/gateway).
+
+## Connection runbook
+
+Android node app ⇄ (mDNS/NSD + WebSocket) ⇄ **Gateway**
+
+Android connects directly to the Gateway WebSocket and uses device pairing (`role: node`).
+
+For Tailscale or public hosts, Android requires a secure endpoint:
+
+- Preferred: Tailscale Serve / Funnel with `https://<magicdns>` / `wss://<magicdns>`
+- Also supported: any other `wss://` Gateway URL with a real TLS endpoint
+- Cleartext `ws://` remains supported on private LAN addresses / `.local` hosts, plus `localhost`, `127.0.0.1`, and the Android emulator bridge (`10.0.2.2`)
+
+### Prerequisites
+
+- You can run the Gateway on the "master" machine.
+- Android device/emulator can reach the gateway WebSocket:
+  - Same LAN with mDNS/NSD, **or**
+  - Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or**
+  - Manual gateway host/port (fallback)
+- Tailnet/public mobile pairing does **not** use raw tailnet IP `ws://` endpoints. Use Tailscale Serve or another `wss://` URL instead.
+- You can run the CLI (`openclaw`) on the gateway machine (or via SSH).
+
+### 1) Start the Gateway
+
+```bash
+openclaw gateway --port 18789 --verbose
+```
+
+Confirm in logs you see something like:
+
+- `listening on ws://0.0.0.0:18789`
+
+For remote Android access over Tailscale, prefer Serve/Funnel instead of a raw tailnet bind:
+
+```bash
+openclaw gateway --tailscale serve
+```
+
+This gives Android a secure `wss://` / `https://` endpoint. A plain `gateway.bind: "tailnet"` setup is not enough for first-time remote Android pairing unless you also terminate TLS separately.
+
+### 2) Verify discovery (optional)
+
+From the gateway machine:
+
+```bash
+dns-sd -B _openclaw-gw._tcp local.
+```
+
+More debugging notes: [Bonjour](/gateway/bonjour).
+
+If you also configured a wide-area discovery domain, compare against:
+
+```bash
+openclaw gateway discover --json
+```
+
+That shows `local.` plus the configured wide-area domain in one pass and uses the resolved
+service endpoint instead of TXT-only hints.
+
+#### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
+
+Android NSD/mDNS discovery won't cross networks. If your Android node and the gateway are on different networks but connected via Tailscale, use Wide-Area Bonjour / unicast DNS-SD instead.
+
+Discovery alone is not sufficient for tailnet/public Android pairing. The discovered route still needs a secure endpoint (`wss://` or Tailscale Serve):
+
+1. Set up a DNS-SD zone (example `openclaw.internal.`) on the gateway host and publish `_openclaw-gw._tcp` records.
+2. Configure Tailscale split DNS for your chosen domain pointing at that DNS server.
+
+Details and example CoreDNS config: [Bonjour](/gateway/bonjour).
+
+### 3) Connect from Android
+
+In the Android app:
+
+- The app keeps its gateway connection alive via a **foreground service** (persistent notification).
+- Open the **Connect** tab.
+- Use **Setup Code** or **Manual** mode.
+- If discovery is blocked, use manual host/port in **Advanced controls**. For private LAN hosts, `ws://` still works. For Tailscale/public hosts, turn on TLS and use a `wss://` / Tailscale Serve endpoint.
+
+After the first successful pairing, Android auto-reconnects on launch:
+
+- Manual endpoint (if enabled), otherwise
+- The last discovered gateway (best-effort).
+
+### Presence alive beacons
+
+After the authenticated node session connects, and when the app moves to the background while the
+foreground service is still connected, Android calls `node.event` with
+`event: "node.presence.alive"`. The gateway records this as `lastSeenAtMs`/`lastSeenReason` on the
+paired node/device metadata only after the authenticated node device identity is known.
+
+The app counts the beacon as successfully recorded only when the gateway response includes
+`handled: true`. Older gateways may acknowledge `node.event` with `{ "ok": true }`; that response is
+compatible but does not count as a durable last-seen update.
+
+### 4) Approve pairing (CLI)
+
+On the gateway machine:
+
+```bash
+openclaw devices list
+openclaw devices approve <requestId>
+openclaw devices reject <requestId>
+```
+
+Pairing details: [Pairing](/channels/pairing).
+
+Optional: if the Android node always connects from a tightly controlled subnet,
+you can opt in to first-time node auto-approval with explicit CIDRs or exact IPs:
+
+```json5
+{
+  gateway: {
+    nodes: {
+      pairing: {
+        autoApproveCidrs: ["192.168.1.0/24"],
+      },
+    },
+  },
+}
+```
+
+This is disabled by default. It applies only to fresh `role: node` pairing with
+no requested scopes. Operator/browser pairing and any role, scope, metadata, or
+public-key change still require manual approval.
+
+### 5) Verify the node is connected
+
+- Via nodes status:
+
+  ```bash
+  openclaw nodes status
+  ```
+
+- Via Gateway:
+
+  ```bash
+  openclaw gateway call node.list --params "{}"
+  ```
+
+### 6) Chat + history
+
+The Android Chat tab supports session selection (default `main`, plus other existing sessions):
+
+- History: `chat.history` (display-normalized; inline directive tags are
+  stripped from visible text, plain-text tool-call XML payloads (including
+  `<tool_call>...</tool_call>`, `<function_call>...</function_call>`,
+  `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, and
+  truncated tool-call blocks) and leaked ASCII/full-width model control tokens
+  are stripped, pure silent-token assistant rows such as exact `NO_REPLY` /
+  `no_reply` are omitted, and oversized rows can be replaced with placeholders)
+- Send: `chat.send`
+- Push updates (best-effort): `chat.subscribe` → `event:"chat"`
+
+### 7) Canvas + camera
+
+#### Gateway Canvas Host (recommended for web content)
+
+If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point the node at the Gateway canvas host.
+
+<Note>
+Nodes load canvas from the Gateway HTTP server (same port as `gateway.port`, default `18789`).
+</Note>
+
+1. Create `~/.openclaw/workspace/canvas/index.html` on the gateway host.
+
+2. Navigate the node to it (LAN):
+
+```bash
+openclaw nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__openclaw__/canvas/"}'
+```
+
+Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18789/__openclaw__/canvas/`.
+
+This server injects a live-reload client into HTML and reloads on file changes.
+The Gateway also serves `/__openclaw__/a2ui/`, but the Android app treats remote A2UI pages as render-only. Action-capable A2UI commands use the bundled app-owned A2UI page before applying messages.
+
+Canvas commands (foreground only):
+
+- `canvas.eval`, `canvas.snapshot`, `canvas.navigate` (use `{"url":""}` or `{"url":"/"}` to return to the default scaffold). `canvas.snapshot` returns `{ format, base64 }` (default `format="jpeg"`).
+- A2UI: `canvas.a2ui.push`, `canvas.a2ui.reset` (`canvas.a2ui.pushJSONL` legacy alias). These commands use the bundled app-owned A2UI page for action-capable rendering.
+
+Camera commands (foreground only; permission-gated):
+
+- `camera.snap` (jpg)
+- `camera.clip` (mp4)
+
+See [Camera node](/nodes/camera) for parameters and CLI helpers.
+
+### 8) Voice + expanded Android command surface
+
+- Voice tab: Android has two explicit capture modes. **Mic** is a manual Voice-tab session that sends each pause as a chat turn and stops when the app leaves the foreground or the user leaves the Voice tab. **Talk** is continuous Talk Mode and keeps listening until toggled off or the node disconnects.
+- Talk Mode promotes the existing foreground service from `connectedDevice` to `connectedDevice|microphone` before capture starts, then demotes it when Talk Mode stops. The node service declares `FOREGROUND_SERVICE_CONNECTED_DEVICE` with `CHANGE_NETWORK_STATE`; Android 14+ also requires the `FOREGROUND_SERVICE_MICROPHONE` declaration, the `RECORD_AUDIO` runtime grant, and the microphone service type at runtime.
+- By default, Android Talk uses native speech recognition, Gateway chat, and `talk.speak` through the configured gateway Talk provider. Local system TTS is used only when `talk.speak` is unavailable.
+- Android Talk uses realtime Gateway relay only when `talk.realtime.mode` is `realtime` and `talk.realtime.transport` is `gateway-relay`.
+- Voice wake remains disabled in the Android UX/runtime.
+- Additional Android command families (availability depends on device, permissions, and user settings):
+  - `device.status`, `device.info`, `device.permissions`, `device.health`
+  - `device.apps` only when **Settings > Phone Capabilities > Installed Apps** is enabled; it lists launcher-visible apps by default.
+  - `notifications.list`, `notifications.actions` (see [Notification forwarding](#notification-forwarding) below)
+  - `photos.latest`
+  - `contacts.search`, `contacts.add`
+  - `calendar.events`, `calendar.add`
+  - `callLog.search`
+  - `sms.search`
+  - `motion.activity`, `motion.pedometer`
+
+## Assistant entrypoints
+
+Android supports launching OpenClaw from the system assistant trigger (Google
+Assistant). When configured, holding the home button or saying "Hey Google, ask
+OpenClaw..." opens the app and hands the prompt into the chat composer.
+
+This uses Android **App Actions** metadata declared in the app manifest. No
+extra configuration is needed on the gateway side -- the assistant intent is
+handled entirely by the Android app and forwarded as a normal chat message.
+
+<Note>
+App Actions availability depends on the device, Google Play Services version,
+and whether the user has set OpenClaw as the default assistant app.
+</Note>
+
+## Notification forwarding
+
+Android can forward device notifications to the gateway as events. Several controls let you scope which notifications are forwarded and when.
+
+| Key                              | Type           | Description                                                                                       |
+| -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------- |
+| `notifications.allowPackages`    | string[]       | Only forward notifications from these package names. If set, all other packages are ignored.      |
+| `notifications.denyPackages`     | string[]       | Never forward notifications from these package names. Applied after `allowPackages`.              |
+| `notifications.quietHours.start` | string (HH:mm) | Start of quiet hours window (local device time). Notifications are suppressed during this window. |
+| `notifications.quietHours.end`   | string (HH:mm) | End of quiet hours window.                                                                        |
+| `notifications.rateLimit`        | number         | Maximum forwarded notifications per package per minute. Excess notifications are dropped.         |
+
+The notification picker also uses safer behavior for forwarded notification events, preventing accidental forwarding of sensitive system notifications.
+
+Example configuration:
+
+```json5
+{
+  notifications: {
+    allowPackages: ["com.slack", "com.whatsapp"],
+    denyPackages: ["com.android.systemui"],
+    quietHours: {
+      start: "22:00",
+      end: "07:00",
+    },
+    rateLimit: 5,
+  },
+}
+```
+
+<Note>
+Notification forwarding requires the Android Notification Listener permission. The app prompts for this during setup.
+</Note>
+
+## Related
+
+- [iOS app](/platforms/ios)
+- [Nodes](/nodes)
+- [Android node troubleshooting](/nodes/troubleshooting)

package/docs/platforms/digitalocean.md

@@ -0,0 +1,12 @@
+---
+summary: "Redirect to /install/digitalocean"
+title: "DigitalOcean (platform)"
+redirect: /install/digitalocean
+---
+
+This page has moved to [DigitalOcean](/install/digitalocean).
+
+## Related
+
+- [Install overview](/install)
+- [VPS hosting](/vps)

package/docs/platforms/easyrunner.md

@@ -0,0 +1,109 @@
+---
+summary: "Run the OpenClaw Gateway on EasyRunner with Podman and Caddy"
+read_when:
+  - Deploying OpenClaw on EasyRunner
+  - Running the Gateway behind EasyRunner's Caddy proxy
+  - Choosing persistent volumes and auth for a hosted Gateway
+title: "EasyRunner"
+---
+
+EasyRunner can host the OpenClaw Gateway as a small containerized app behind its
+Caddy proxy. This guide assumes an EasyRunner host that runs Podman-compatible
+Compose apps and exposes HTTPS through Caddy.
+
+## Before you begin
+
+- An EasyRunner server with a domain routed to it.
+- A built or published OpenClaw container image.
+- A persistent config volume for `/home/node/.openclaw`.
+- A persistent workspace volume for `/workspace`.
+- A strong Gateway token or password.
+
+Keep device auth enabled when possible. If your reverse proxy deployment cannot
+carry device identity correctly, fix trusted-proxy settings first; use
+dangerous auth bypasses only for a fully private, operator-controlled network.
+
+## Compose app
+
+Create an EasyRunner app with a Compose file shaped like this:
+
+```yaml
+services:
+  openclaw:
+    image: ghcr.io/openclaw/openclaw:latest
+    restart: unless-stopped
+    environment:
+      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
+      OPENCLAW_HOME: /home/node
+      OPENCLAW_STATE_DIR: /home/node/.openclaw
+      OPENCLAW_CONFIG_PATH: /home/node/.openclaw/openclaw.json
+      OPENCLAW_WORKSPACE_DIR: /workspace
+    volumes:
+      - openclaw-config:/home/node/.openclaw
+      - openclaw-workspace:/workspace
+    labels:
+      caddy: openclaw.example.com
+      caddy.reverse_proxy: "{{upstreams 1455}}"
+    command: ["openclaw", "gateway", "--bind", "lan", "--port", "1455"]
+
+volumes:
+  openclaw-config:
+  openclaw-workspace:
+```
+
+Replace `openclaw.example.com` with your Gateway hostname. Store
+`OPENCLAW_GATEWAY_TOKEN` in EasyRunner's secret/environment manager instead of
+committing it to the app definition.
+
+## Configure OpenClaw
+
+Inside the persistent config volume, keep the Gateway reachable only through
+the proxy and require auth:
+
+```json5
+{
+  gateway: {
+    bind: "lan",
+    port: 1455,
+    auth: {
+      token: "${OPENCLAW_GATEWAY_TOKEN}",
+    },
+  },
+}
+```
+
+If Caddy terminates TLS for the Gateway, configure trusted proxy settings for
+the exact proxy path rather than disabling auth checks globally. See
+[Trusted proxy auth](/gateway/trusted-proxy-auth).
+
+## Verify
+
+From your workstation:
+
+```bash
+openclaw gateway probe --url https://openclaw.example.com --token <token>
+openclaw gateway status --url https://openclaw.example.com --token <token>
+```
+
+From the EasyRunner host, check the app logs for a listening Gateway and no
+startup SecretRef, plugin, or channel auth failures.
+
+## Updates and backups
+
+- Pull or build the new OpenClaw image, then redeploy the EasyRunner app.
+- Back up the `openclaw-config` volume before updates.
+- Back up `openclaw-workspace` if agents write durable project data there.
+- Run `openclaw doctor` after major updates to catch config migrations and
+  service warnings.
+
+## Troubleshooting
+
+- `gateway probe` cannot connect: confirm the Caddy hostname points at the app
+  and that the container listens on `0.0.0.0:1455`.
+- Auth fails: rotate the token in EasyRunner secrets and the local client
+  command together.
+- Files are root-owned after restore: repair the mounted volumes so the
+  container user can write `/home/node/.openclaw` and `/workspace`.
+- Browser or channel plugins fail: check whether the required external
+  binaries, network egress, and mounted credentials are available inside the
+  container.