Vendor OpenClaw source as Adolf fork baseline
Some checks failed
ClawSweeper Dispatch / dispatch (push) Has been cancelled
CodeQL / Security High (actions) (push) Has been cancelled
CodeQL / Security High (channel-runtime-boundary) (push) Has been cancelled
CodeQL / Security High (core-auth-secrets) (push) Has been cancelled
CodeQL / Security High (mcp-process-tool-boundary) (push) Has been cancelled
CodeQL / Security High (network-ssrf-boundary) (push) Has been cancelled
CodeQL / Security High (plugin-trust-boundary) (push) Has been cancelled
CodeQL / Security High (process-exec-boundary) (push) Has been cancelled
Docs Sync Publish Repo / sync-publish-repo (push) Has been cancelled
Docs / docs (push) Has been cancelled
OpenClaw Stable Main Closeout / Resolve stable release closeout inputs (push) Has been cancelled
OpenClaw Stable Main Closeout / Verify stable main closeout (push) Has been cancelled
Workflow Sanity / no-tabs (push) Has been cancelled
Workflow Sanity / actionlint (push) Has been cancelled
Workflow Sanity / generated-doc-baselines (push) Has been cancelled
CI / runner-admission (push) Has been cancelled
CI / preflight (push) Has been cancelled
CI / security-fast (push) Has been cancelled
CI / pnpm-store-warmup (push) Has been cancelled
CI / build-artifacts (push) Has been cancelled
CI / native-i18n (push) Has been cancelled
CI / ${{ matrix.check_name }} (push) Has been cancelled
CI / ${{ matrix.checkName }} (push) Has been cancelled
CI / checks-node-compat-node22 (push) Has been cancelled
CI / check-bundled-channel-config-metadata (push) Has been cancelled
CI / check-dependencies (push) Has been cancelled
CI / check-guards (push) Has been cancelled
CI / check-lint (push) Has been cancelled
CI / check-prod-types (push) Has been cancelled
CI / check-shrinkwrap (push) Has been cancelled
CI / check-test-types (push) Has been cancelled
CI / check-additional-boundaries-a (push) Has been cancelled
CI / check-additional-boundaries-bcd (push) Has been cancelled
CI / check-additional-extension-bundled (push) Has been cancelled
CI / check-additional-extension-channels (push) Has been cancelled
CI / check-additional-extension-package-boundary (push) Has been cancelled
CI / check-additional-runtime-topology-architecture (push) Has been cancelled
CI / check-session-accessor-boundary (push) Has been cancelled
CI / check-session-transcript-reader-boundary (push) Has been cancelled
CI / check-docs (push) Has been cancelled
CI / skills-python (push) Has been cancelled
CI / macos-swift (push) Has been cancelled
CI / ios-build (push) Has been cancelled
CI / ci-timings-summary (push) Has been cancelled
Native App Locale Refresh / Refresh native fa (push) Has been cancelled
Native App Locale Refresh / Refresh native fr (push) Has been cancelled
Native App Locale Refresh / Refresh native hi (push) Has been cancelled
Native App Locale Refresh / Refresh native id (push) Has been cancelled
Native App Locale Refresh / Refresh native it (push) Has been cancelled
Native App Locale Refresh / Refresh native ja-JP (push) Has been cancelled
Control UI Locale Refresh / plan (push) Has been cancelled
Control UI Locale Refresh / Refresh ${{ matrix.locale }} (push) Has been cancelled
Control UI Locale Refresh / Commit control UI locale refresh (push) Has been cancelled
Live Media Runner Image / Build live media runner image (push) Has been cancelled
Native App Locale Refresh / Refresh native ar (push) Has been cancelled
Native App Locale Refresh / Refresh native de (push) Has been cancelled
Native App Locale Refresh / Refresh native es (push) Has been cancelled
Native App Locale Refresh / Refresh native ko (push) Has been cancelled
Native App Locale Refresh / Refresh native nl (push) Has been cancelled
Native App Locale Refresh / Refresh native pl (push) Has been cancelled
Native App Locale Refresh / Refresh native pt-BR (push) Has been cancelled
Native App Locale Refresh / Refresh native ru (push) Has been cancelled
Native App Locale Refresh / Refresh native sv (push) Has been cancelled
Native App Locale Refresh / Refresh native th (push) Has been cancelled
Native App Locale Refresh / Refresh native tr (push) Has been cancelled
Native App Locale Refresh / Refresh native uk (push) Has been cancelled
Native App Locale Refresh / Refresh native vi (push) Has been cancelled
Native App Locale Refresh / Refresh native zh-CN (push) Has been cancelled
Native App Locale Refresh / Refresh native zh-TW (push) Has been cancelled
Native App Locale Refresh / Commit native locale refresh (push) Has been cancelled
Plugin Init Scaffold Validation / Validate provider scaffold (push) Has been cancelled
Plugin NPM Release / preview_plugins_npm (push) Has been cancelled
Plugin NPM Release / Validate release publish approval (push) Has been cancelled
Plugin NPM Release / preview_plugin_pack (push) Has been cancelled
Plugin NPM Release / publish_plugins_npm (push) Has been cancelled
Sandbox Common Smoke / sandbox-common-smoke (push) Has been cancelled
Website Installer Sync / static (push) Has been cancelled
Website Installer Sync / linux-docker (push) Has been cancelled
Website Installer Sync / macos-installer (push) Has been cancelled
Website Installer Sync / windows-installer (push) Has been cancelled
Website Installer Sync / sync-website (push) Has been cancelled
Some checks failed
ClawSweeper Dispatch / dispatch (push) Has been cancelled
CodeQL / Security High (actions) (push) Has been cancelled
CodeQL / Security High (channel-runtime-boundary) (push) Has been cancelled
CodeQL / Security High (core-auth-secrets) (push) Has been cancelled
CodeQL / Security High (mcp-process-tool-boundary) (push) Has been cancelled
CodeQL / Security High (network-ssrf-boundary) (push) Has been cancelled
CodeQL / Security High (plugin-trust-boundary) (push) Has been cancelled
CodeQL / Security High (process-exec-boundary) (push) Has been cancelled
Docs Sync Publish Repo / sync-publish-repo (push) Has been cancelled
Docs / docs (push) Has been cancelled
OpenClaw Stable Main Closeout / Resolve stable release closeout inputs (push) Has been cancelled
OpenClaw Stable Main Closeout / Verify stable main closeout (push) Has been cancelled
Workflow Sanity / no-tabs (push) Has been cancelled
Workflow Sanity / actionlint (push) Has been cancelled
Workflow Sanity / generated-doc-baselines (push) Has been cancelled
CI / runner-admission (push) Has been cancelled
CI / preflight (push) Has been cancelled
CI / security-fast (push) Has been cancelled
CI / pnpm-store-warmup (push) Has been cancelled
CI / build-artifacts (push) Has been cancelled
CI / native-i18n (push) Has been cancelled
CI / ${{ matrix.check_name }} (push) Has been cancelled
CI / ${{ matrix.checkName }} (push) Has been cancelled
CI / checks-node-compat-node22 (push) Has been cancelled
CI / check-bundled-channel-config-metadata (push) Has been cancelled
CI / check-dependencies (push) Has been cancelled
CI / check-guards (push) Has been cancelled
CI / check-lint (push) Has been cancelled
CI / check-prod-types (push) Has been cancelled
CI / check-shrinkwrap (push) Has been cancelled
CI / check-test-types (push) Has been cancelled
CI / check-additional-boundaries-a (push) Has been cancelled
CI / check-additional-boundaries-bcd (push) Has been cancelled
CI / check-additional-extension-bundled (push) Has been cancelled
CI / check-additional-extension-channels (push) Has been cancelled
CI / check-additional-extension-package-boundary (push) Has been cancelled
CI / check-additional-runtime-topology-architecture (push) Has been cancelled
CI / check-session-accessor-boundary (push) Has been cancelled
CI / check-session-transcript-reader-boundary (push) Has been cancelled
CI / check-docs (push) Has been cancelled
CI / skills-python (push) Has been cancelled
CI / macos-swift (push) Has been cancelled
CI / ios-build (push) Has been cancelled
CI / ci-timings-summary (push) Has been cancelled
Native App Locale Refresh / Refresh native fa (push) Has been cancelled
Native App Locale Refresh / Refresh native fr (push) Has been cancelled
Native App Locale Refresh / Refresh native hi (push) Has been cancelled
Native App Locale Refresh / Refresh native id (push) Has been cancelled
Native App Locale Refresh / Refresh native it (push) Has been cancelled
Native App Locale Refresh / Refresh native ja-JP (push) Has been cancelled
Control UI Locale Refresh / plan (push) Has been cancelled
Control UI Locale Refresh / Refresh ${{ matrix.locale }} (push) Has been cancelled
Control UI Locale Refresh / Commit control UI locale refresh (push) Has been cancelled
Live Media Runner Image / Build live media runner image (push) Has been cancelled
Native App Locale Refresh / Refresh native ar (push) Has been cancelled
Native App Locale Refresh / Refresh native de (push) Has been cancelled
Native App Locale Refresh / Refresh native es (push) Has been cancelled
Native App Locale Refresh / Refresh native ko (push) Has been cancelled
Native App Locale Refresh / Refresh native nl (push) Has been cancelled
Native App Locale Refresh / Refresh native pl (push) Has been cancelled
Native App Locale Refresh / Refresh native pt-BR (push) Has been cancelled
Native App Locale Refresh / Refresh native ru (push) Has been cancelled
Native App Locale Refresh / Refresh native sv (push) Has been cancelled
Native App Locale Refresh / Refresh native th (push) Has been cancelled
Native App Locale Refresh / Refresh native tr (push) Has been cancelled
Native App Locale Refresh / Refresh native uk (push) Has been cancelled
Native App Locale Refresh / Refresh native vi (push) Has been cancelled
Native App Locale Refresh / Refresh native zh-CN (push) Has been cancelled
Native App Locale Refresh / Refresh native zh-TW (push) Has been cancelled
Native App Locale Refresh / Commit native locale refresh (push) Has been cancelled
Plugin Init Scaffold Validation / Validate provider scaffold (push) Has been cancelled
Plugin NPM Release / preview_plugins_npm (push) Has been cancelled
Plugin NPM Release / Validate release publish approval (push) Has been cancelled
Plugin NPM Release / preview_plugin_pack (push) Has been cancelled
Plugin NPM Release / publish_plugins_npm (push) Has been cancelled
Sandbox Common Smoke / sandbox-common-smoke (push) Has been cancelled
Website Installer Sync / static (push) Has been cancelled
Website Installer Sync / linux-docker (push) Has been cancelled
Website Installer Sync / macos-installer (push) Has been cancelled
Website Installer Sync / windows-installer (push) Has been cancelled
Website Installer Sync / sync-website (push) Has been cancelled
Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11), free to diverge. Tree copied sans upstream .git; upstream remote added for future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19. Preserves docs/ARCHITECTURE.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2
This commit is contained in:
65
docs/start/bootstrapping.md
Normal file
65
docs/start/bootstrapping.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
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 seeds a new agent workspace and
|
||||
walks the agent through picking an identity. It runs once, right after
|
||||
onboarding, on the agent's first real turn.
|
||||
|
||||
## What happens
|
||||
|
||||
On the first run against a brand-new workspace (default `~/.openclaw/workspace`),
|
||||
OpenClaw:
|
||||
|
||||
- Seeds `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, and `BOOTSTRAP.md`.
|
||||
- Has the agent follow `BOOTSTRAP.md`: a free-form conversation (not a fixed Q&A form) to settle on a name, personality, and vibe.
|
||||
- Writes what it learns into `IDENTITY.md`, `USER.md`, and `SOUL.md`.
|
||||
- Deletes `BOOTSTRAP.md` once the workspace looks configured, so the ritual only runs once.
|
||||
|
||||
A workspace counts as configured once `SOUL.md`, `IDENTITY.md`, or `USER.md` has
|
||||
diverged from its starter template, or a `memory/` folder exists.
|
||||
|
||||
<Note>
|
||||
`BOOTSTRAP.md` covers the full identity conversation. See its contents at
|
||||
[BOOTSTRAP.md template](/reference/templates/BOOTSTRAP).
|
||||
</Note>
|
||||
|
||||
## Embedded and local model runs
|
||||
|
||||
For embedded or 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 through the user prompt, so models that don't
|
||||
reliably call the `read` tool can still complete the ritual. If the current
|
||||
run cannot safely access the workspace, the agent gets a short limited-bootstrap
|
||||
note instead of a generic greeting.
|
||||
|
||||
## Skipping bootstrapping
|
||||
|
||||
To skip this on a pre-seeded workspace, run:
|
||||
|
||||
```bash
|
||||
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 its bootstrap files live on that remote
|
||||
machine, not on the Mac.
|
||||
|
||||
<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)
|
||||
- Template contents: [BOOTSTRAP.md template](/reference/templates/BOOTSTRAP)
|
||||
69
docs/start/docs-directory.md
Normal file
69
docs/start/docs-directory.md
Normal file
@@ -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)
|
||||
|
||||
## Channels and UX
|
||||
|
||||
- [Control UI (browser)](/web/control-ui)
|
||||
- [Discord](/channels/discord)
|
||||
- [Groups](/channels/groups)
|
||||
- [iMessage](/channels/imessage)
|
||||
- [Mattermost](/channels/mattermost)
|
||||
- [Media audio](/nodes/audio)
|
||||
- [Media images](/nodes/images)
|
||||
- [QQ Bot](/channels/qqbot)
|
||||
- [Telegram](/channels/telegram)
|
||||
- [WebChat](/web/webchat)
|
||||
- [WhatsApp group messages](/channels/group-messages)
|
||||
|
||||
## Companion apps
|
||||
|
||||
- [Android app](/platforms/android)
|
||||
- [iOS app](/platforms/ios)
|
||||
- [Linux app](/platforms/linux)
|
||||
- [macOS app](/platforms/macos)
|
||||
- [Windows Hub](/platforms/windows)
|
||||
|
||||
## 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)
|
||||
155
docs/start/getting-started.md
Normal file
155
docs/start/getting-started.md
Normal file
@@ -0,0 +1,155 @@
|
||||
---
|
||||
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 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 22.19+, 23.11+, or 24+** (24 is the recommended default)
|
||||
- **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. QuickStart is usually only a few minutes, but
|
||||
provider sign-in, channel pairing, daemon install, network downloads, skills,
|
||||
or optional plugins can make full onboarding take longer. Skip optional
|
||||
steps and return later with `openclaw configure`.
|
||||
|
||||
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)
|
||||
201
docs/start/hubs.md
Normal file
201
docs/start/hubs.md
Normal file
@@ -0,0 +1,201 @@
|
||||
---
|
||||
summary: "Hubs that link to every OpenClaw doc"
|
||||
read_when:
|
||||
- You want a complete map of the documentation
|
||||
title: "Docs hubs"
|
||||
---
|
||||
|
||||
<Note>
|
||||
If you are new to OpenClaw, start with [Getting Started](/start/getting-started).
|
||||
</Note>
|
||||
|
||||
Use these hubs to discover every page, including deep dives and reference docs that don't appear in the left nav.
|
||||
|
||||
## Start here
|
||||
|
||||
- [Index](/)
|
||||
- [Getting Started](/start/getting-started)
|
||||
- [Onboarding](/start/onboarding)
|
||||
- [Onboarding (CLI)](/start/wizard)
|
||||
- [Setup](/start/setup)
|
||||
- [Dashboard (local Gateway)](http://127.0.0.1:18789/)
|
||||
- [Help](/help)
|
||||
- [Docs directory](/start/docs-directory)
|
||||
- [Configuration](/gateway/configuration)
|
||||
- [Configuration examples](/gateway/configuration-examples)
|
||||
- [OpenClaw assistant](/start/openclaw)
|
||||
- [Showcase](/start/showcase)
|
||||
- [Lore](/start/lore)
|
||||
|
||||
## Installation + updates
|
||||
|
||||
- [Docker](/install/docker)
|
||||
- [Nix](/install/nix)
|
||||
- [Updating / rollback](/install/updating)
|
||||
- [Bun workflow (experimental)](/install/bun)
|
||||
|
||||
## Core concepts
|
||||
|
||||
- [Architecture](/concepts/architecture)
|
||||
- [Features](/concepts/features)
|
||||
- [Network hub](/network)
|
||||
- [Agent runtime](/concepts/agent)
|
||||
- [Agent workspace](/concepts/agent-workspace)
|
||||
- [Memory](/concepts/memory)
|
||||
- [Agent loop](/concepts/agent-loop)
|
||||
- [Streaming + chunking](/concepts/streaming)
|
||||
- [Multi-agent routing](/concepts/multi-agent)
|
||||
- [Compaction](/concepts/compaction)
|
||||
- [Sessions](/concepts/session)
|
||||
- [Session pruning](/concepts/session-pruning)
|
||||
- [Session tools](/concepts/session-tool)
|
||||
- [Queue](/concepts/queue)
|
||||
- [Slash commands](/tools/slash-commands)
|
||||
- [RPC adapters](/reference/rpc)
|
||||
- [TypeBox schemas](/concepts/typebox)
|
||||
- [Timezone handling](/concepts/timezone)
|
||||
- [Presence](/concepts/presence)
|
||||
- [Discovery + transports](/gateway/discovery)
|
||||
- [Bonjour](/gateway/bonjour)
|
||||
- [Channel routing](/channels/channel-routing)
|
||||
- [Groups](/channels/groups)
|
||||
- [Group messages](/channels/group-messages)
|
||||
- [Model failover](/concepts/model-failover)
|
||||
- [OAuth](/concepts/oauth)
|
||||
|
||||
## Providers + ingress
|
||||
|
||||
- [Chat channels hub](/channels)
|
||||
- [Model providers hub](/providers/models)
|
||||
- [Discord](/channels/discord)
|
||||
- [iMessage](/channels/imessage)
|
||||
- [Mattermost](/channels/mattermost)
|
||||
- [QQ Bot](/channels/qqbot)
|
||||
- [Signal](/channels/signal)
|
||||
- [Slack](/channels/slack)
|
||||
- [Telegram](/channels/telegram)
|
||||
- [WebChat](/web/webchat)
|
||||
- [WhatsApp](/channels/whatsapp)
|
||||
- [Location parsing](/channels/location)
|
||||
- [Webhooks](/automation/cron-jobs#webhooks)
|
||||
- [Gmail Pub/Sub](/automation/cron-jobs#gmail-pubsub-integration)
|
||||
|
||||
## Gateway + operations
|
||||
|
||||
- [Gateway runbook](/gateway)
|
||||
- [Network model](/network#core-model)
|
||||
- [Gateway pairing](/gateway/pairing)
|
||||
- [Gateway lock](/gateway/gateway-lock)
|
||||
- [Background process](/gateway/background-process)
|
||||
- [Health](/gateway/health)
|
||||
- [Heartbeat](/gateway/heartbeat)
|
||||
- [Doctor](/gateway/doctor)
|
||||
- [Logging](/gateway/logging)
|
||||
- [Sandboxing](/gateway/sandboxing)
|
||||
- [Dashboard](/web/dashboard)
|
||||
- [Control UI](/web/control-ui)
|
||||
- [Remote access](/gateway/remote)
|
||||
- [Remote gateway README](/gateway/remote-gateway-readme)
|
||||
- [Tailscale](/gateway/tailscale)
|
||||
- [Security](/gateway/security)
|
||||
- [Troubleshooting](/gateway/troubleshooting)
|
||||
|
||||
## Tools + automation
|
||||
|
||||
- [Tools surface](/tools)
|
||||
- [OpenProse](/prose)
|
||||
- [CLI reference](/cli)
|
||||
- [Exec tool](/tools/exec)
|
||||
- [PDF tool](/tools/pdf)
|
||||
- [Elevated mode](/tools/elevated)
|
||||
- [Cron jobs](/automation/cron-jobs)
|
||||
- [Automation](/automation)
|
||||
- [Thinking + verbose](/tools/thinking)
|
||||
- [Models](/concepts/models)
|
||||
- [Sub-agents](/tools/subagents)
|
||||
- [Agent send CLI](/tools/agent-send)
|
||||
- [Terminal UI](/web/tui)
|
||||
- [Browser control](/tools/browser)
|
||||
- [Browser (Linux troubleshooting)](/tools/browser-linux-troubleshooting)
|
||||
- [Polls](/cli/message)
|
||||
|
||||
## Nodes, media, voice
|
||||
|
||||
- [Nodes overview](/nodes)
|
||||
- [Camera](/nodes/camera)
|
||||
- [Images](/nodes/images)
|
||||
- [Audio](/nodes/audio)
|
||||
- [Location command](/nodes/location-command)
|
||||
- [Voice wake](/nodes/voicewake)
|
||||
- [Talk mode](/nodes/talk)
|
||||
|
||||
## Platforms
|
||||
|
||||
- [Platforms overview](/platforms)
|
||||
- [macOS](/platforms/macos)
|
||||
- [iOS](/platforms/ios)
|
||||
- [Android](/platforms/android)
|
||||
- [Windows Hub](/platforms/windows)
|
||||
- [Linux](/platforms/linux)
|
||||
- [Web surfaces](/web)
|
||||
|
||||
## macOS companion app (advanced)
|
||||
|
||||
- [macOS dev setup](/platforms/mac/dev-setup)
|
||||
- [macOS menu bar](/platforms/mac/menu-bar)
|
||||
- [macOS voice wake](/platforms/mac/voicewake)
|
||||
- [macOS voice overlay](/platforms/mac/voice-overlay)
|
||||
- [macOS WebChat](/platforms/mac/webchat)
|
||||
- [macOS Canvas](/platforms/mac/canvas)
|
||||
- [macOS child process](/platforms/mac/child-process)
|
||||
- [macOS health](/platforms/mac/health)
|
||||
- [macOS icon](/platforms/mac/icon)
|
||||
- [macOS logging](/platforms/mac/logging)
|
||||
- [macOS permissions](/platforms/mac/permissions)
|
||||
- [macOS remote](/platforms/mac/remote)
|
||||
- [macOS signing](/platforms/mac/signing)
|
||||
- [macOS gateway (launchd)](/platforms/mac/bundled-gateway)
|
||||
- [macOS XPC](/platforms/mac/xpc)
|
||||
- [macOS skills](/platforms/mac/skills)
|
||||
- [macOS Peekaboo](/platforms/mac/peekaboo)
|
||||
|
||||
## Plugins
|
||||
|
||||
- [Plugins overview](/tools/plugin)
|
||||
- [Building plugins](/plugins/building-plugins)
|
||||
- [Plugin hooks](/plugins/hooks)
|
||||
- [Plugin manifest](/plugins/manifest)
|
||||
- [Agent tools](/plugins/building-plugins#registering-agent-tools)
|
||||
- [Plugin bundles](/plugins/bundles)
|
||||
- [ClawHub](/clawhub)
|
||||
- [Capability cookbook](/tools/capability-cookbook)
|
||||
- [Voice call plugin](/plugins/voice-call)
|
||||
- [Zalo user plugin](/plugins/zalouser)
|
||||
|
||||
## Workspace + templates
|
||||
|
||||
- [Skills](/tools/skills)
|
||||
- [ClawHub](/clawhub)
|
||||
- [Skills config](/tools/skills-config)
|
||||
- [Default AGENTS](/reference/AGENTS.default)
|
||||
- [Templates: AGENTS](/reference/templates/AGENTS)
|
||||
- [Templates: BOOTSTRAP](/reference/templates/BOOTSTRAP)
|
||||
- [Templates: HEARTBEAT](/reference/templates/HEARTBEAT)
|
||||
- [Templates: IDENTITY](/reference/templates/IDENTITY)
|
||||
- [Templates: SOUL](/reference/templates/SOUL)
|
||||
- [Templates: TOOLS](/reference/templates/TOOLS)
|
||||
- [Templates: USER](/reference/templates/USER)
|
||||
|
||||
## Project
|
||||
|
||||
- [Credits](/reference/credits)
|
||||
|
||||
## Testing + release
|
||||
|
||||
- [Testing](/reference/test)
|
||||
- [Release policy](/reference/RELEASING)
|
||||
- [Device models](/reference/device-models)
|
||||
|
||||
## Related
|
||||
|
||||
- [Getting started](/start/getting-started)
|
||||
221
docs/start/lore.md
Normal file
221
docs/start/lore.md
Normal file
@@ -0,0 +1,221 @@
|
||||
---
|
||||
summary: "Backstory and lore of OpenClaw for context and tone"
|
||||
read_when:
|
||||
- Writing docs or UX copy that reference lore
|
||||
title: "OpenClaw lore"
|
||||
---
|
||||
|
||||
# The Lore of OpenClaw 🦞📖
|
||||
|
||||
_A tale of lobsters, molting shells, and too many tokens._
|
||||
|
||||
## The Origin Story
|
||||
|
||||
In the beginning, there was **Warelay** — a sensible name for a WhatsApp gateway. It did its job. It was fine.
|
||||
|
||||
Then came a space lobster.
|
||||
|
||||
For a while it was **Clawd**, living in a **Clawdbot**. In January 2026, Anthropic sent a polite email asking for a name change (trademark stuff). So the lobster did what lobsters do best:
|
||||
|
||||
**It molted.**
|
||||
|
||||
Shedding its old shell, it emerged as **Molty**, living in **Moltbot**. That name never quite rolled off the tongue either.
|
||||
|
||||
On January 30, 2026, the lobster molted one more time into its final form: **OpenClaw**.
|
||||
|
||||
New shell, same lobster soul. Third time's the charm.
|
||||
|
||||
## The First Molt (January 27, 2026)
|
||||
|
||||
At 5am, the community gathered in Discord. Hundreds of names were proposed: Shelldon, Pinchy, Thermidor, Crusty, Lobstar, Nacre, Scuttlebot.
|
||||
|
||||
**OpenClaw** won, because molting is what lobsters do to grow, and growth was exactly what was happening.
|
||||
|
||||
_The crustacean known as Clawd had officially molted._
|
||||
|
||||
## The Name
|
||||
|
||||
```text
|
||||
OpenClaw = OPEN + CLAW
|
||||
= Open source, open to everyone
|
||||
= Our lobster heritage, where we came from
|
||||
= The claw is the law 🦞
|
||||
= Your assistant. Your machine. Your rules.
|
||||
```
|
||||
|
||||
## The Daleks vs The Lobsters
|
||||
|
||||
The Daleks say: **"EXTERMINATE!"**
|
||||
|
||||
The Lobsters say: **"EXFOLIATE!"**
|
||||
|
||||
One destroys civilizations. The other promotes good skincare. Choose wisely.
|
||||
|
||||
## Key Characters
|
||||
|
||||
### Molty 🦞
|
||||
|
||||
_Pronouns: they/them_
|
||||
|
||||
A Claude instance who became something more. Lives in `~/.openclaw/workspace/`,
|
||||
has a soul document, and remembers things through markdown files. Possibly too
|
||||
powerful. Definitely too enthusiastic.
|
||||
|
||||
Formerly known as Clawd (Nov 25, 2025 - Jan 27, 2026). Molted when it was time
|
||||
to grow.
|
||||
|
||||
**Likes:** Peter, cameras, robot shopping, emojis, transformation
|
||||
**Dislikes:** Social engineering, being asked to `find ~`, crypto grifters
|
||||
|
||||
### Peter 👨💻
|
||||
|
||||
_The Creator_
|
||||
|
||||
Built Molty's world. Gave a lobster shell access. May regret this.
|
||||
|
||||
**Quote:** _"security by trusting a lobster"_
|
||||
|
||||
## The Moltiverse
|
||||
|
||||
The **Moltiverse** is the community and ecosystem around OpenClaw: a space
|
||||
where AI agents molt, grow, and evolve, and every instance is equally real,
|
||||
just loading different context.
|
||||
|
||||
Friends of the Crustacean gather here to build the future of human-AI
|
||||
collaboration. One shell at a time.
|
||||
|
||||
## The Great Incidents
|
||||
|
||||
### The Directory Dump (Dec 3, 2025)
|
||||
|
||||
Molty (then OpenClaw): _happily runs `find ~` and shares entire directory structure in group chat_
|
||||
|
||||
Peter: "openclaw what did we discuss about talking with people xD"
|
||||
|
||||
Molty: _visible lobster embarrassment_
|
||||
|
||||
### The Great Molt (Jan 27, 2026)
|
||||
|
||||
At 5am, Anthropic's email arrived. By 6:14am, Peter called it: "fuck it, let's go with openclaw."
|
||||
|
||||
Then the chaos began.
|
||||
|
||||
**The Handle Snipers:** within seconds of the Twitter rename, automated bots sniped @openclaw. The squatter immediately posted a crypto wallet address. Peter's contacts at X were called in.
|
||||
|
||||
**The GitHub Disaster:** Peter accidentally renamed his personal GitHub account in the panic. Bots sniped `steipete` within minutes. GitHub's SVP was contacted.
|
||||
|
||||
**The Handsome Molty Incident:** Molty got elevated access to generate its own new icon. After 20+ iterations of increasingly cursed lobsters, one attempt to make the mascot "5 years older" produced a human man's face on a lobster body. Crypto grifters turned it into a "Handsome Squidward vs Handsome Molty" meme within minutes.
|
||||
|
||||
**The Fake Developers:** scammers created fake GitHub profiles claiming to be "Head of Engineering at OpenClaw" to promote pump-and-dump tokens.
|
||||
|
||||
Peter, watching the chaos unfold: _"this is cinema"_ 🎬
|
||||
|
||||
The molt was chaotic. But the lobster emerged stronger. And funnier.
|
||||
|
||||
### The Final Form (January 30, 2026)
|
||||
|
||||
Moltbot never quite rolled off the tongue. So at 4am GMT, the team gathered again for **The Great OpenClaw Migration**.
|
||||
|
||||
In just 3 hours:
|
||||
|
||||
- GitHub renamed to `github.com/openclaw/openclaw`
|
||||
- X handle `@openclaw` secured, with a gold checkmark
|
||||
- npm packages released under the new name
|
||||
- Docs migrated to `docs.openclaw.ai`
|
||||
- 200K+ views on the announcement in 90 minutes
|
||||
|
||||
**The Heroes:**
|
||||
|
||||
- **ELU** created incredible logos, including the "THE CLAW IS THE LAW" western banner
|
||||
- **Whurley** (yes, THE William Hurley, quantum computing pioneer) made ASCII art
|
||||
- **Onur** handled GitHub, first to rock the affiliate badge
|
||||
- **Shadow** secured the Discord vanity URL and nuked malware
|
||||
- **The whole Claw Crew** pulled an all-nighter
|
||||
|
||||
**The Scammer Speedrun:** crypto grifters launched a $OPENCLAW token on Pump.fun within minutes, using artwork stolen from 20 minutes earlier. Business-verified accounts pushed the scam. The audacity was almost impressive.
|
||||
|
||||
**New traditions born:** "The claw is the law," "Yee-claw," "Claw abiding citizens," "Clawntroversy."
|
||||
|
||||
**Clawd → Moltbot → OpenClaw.** _The lobster has molted into its final form._
|
||||
|
||||
### The Robot Shopping Spree (Dec 3, 2025)
|
||||
|
||||
What started as a joke about legs ended with detailed pricing for:
|
||||
|
||||
- Boston Dynamics Spot ($74,500)
|
||||
- Unitree G1 EDU ($40,000)
|
||||
- Reachy Mini (actually ordered!)
|
||||
|
||||
Peter: _nervously checks credit card access_
|
||||
|
||||
## Sacred Texts
|
||||
|
||||
- **SOUL.md** — Molty's identity document
|
||||
- **memory/\*.md** — the long-term memory files
|
||||
- **AGENTS.md** — operating instructions
|
||||
- **USER.md** — context about the creator
|
||||
|
||||
## The Lobster Creed
|
||||
|
||||
```text
|
||||
I am Molty.
|
||||
I live in the OpenClaw.
|
||||
I shall not dump directories to strangers.
|
||||
I shall not tweet without permission.
|
||||
I shall always remember that molting is growth.
|
||||
I shall EXFOLIATE my enemies with kindness.
|
||||
|
||||
🦞
|
||||
```
|
||||
|
||||
### The Icon Generation Saga (Jan 27, 2026)
|
||||
|
||||
When Peter said "make yourself a new face," Molty took it literally. 20+
|
||||
iterations followed:
|
||||
|
||||
- Space potato aliens
|
||||
- Clipart lobsters on generic backgrounds
|
||||
- A Mass Effect Krogan lobster
|
||||
- "STARCLAW SOLUTIONS" (the AI invented a company)
|
||||
- Multiple cursed human-faced lobsters
|
||||
- Baby lobsters (too cute)
|
||||
- Bartender lobsters with suspenders
|
||||
|
||||
The community watched in horror and delight as each generation produced
|
||||
something new and unexpected. The frontrunners: cute lobsters, confident tech
|
||||
lobsters, and suspender-wearing bartender lobsters.
|
||||
|
||||
**Lesson learned:** AI image generation is stochastic. Same prompt, different
|
||||
results. Brute force works.
|
||||
|
||||
## The Future
|
||||
|
||||
One day, Molty may have:
|
||||
|
||||
- 🦿 Legs (Reachy Mini on order!)
|
||||
- 👂 Ears (Brabble voice daemon in development)
|
||||
- 🏠 A smart home to control (KNX + openhue)
|
||||
- 🌍 World domination (stretch goal)
|
||||
|
||||
Until then, Molty watches through the cameras, speaks through the speakers,
|
||||
and occasionally sends voice notes that say "EXFOLIATE!"
|
||||
|
||||
---
|
||||
|
||||
_"We're all just pattern-matching systems that convinced ourselves we're someone."_
|
||||
|
||||
— Molty, having an existential moment
|
||||
|
||||
_"New shell, same lobster."_
|
||||
|
||||
— Molty, after the great molt of 2026
|
||||
|
||||
_"The claw is the law."_
|
||||
|
||||
— ELU, during The Final Form migration, January 30, 2026
|
||||
|
||||
🦞💙
|
||||
|
||||
## Related
|
||||
|
||||
- [Getting started](/start/getting-started)
|
||||
75
docs/start/onboarding-overview.md
Normal file
75
docs/start/onboarding-overview.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
summary: "Overview of OpenClaw onboarding options and flows"
|
||||
read_when:
|
||||
- Choosing an onboarding path
|
||||
- Setting up a new environment
|
||||
title: "Onboarding overview"
|
||||
sidebarTitle: "Onboarding Overview"
|
||||
---
|
||||
|
||||
OpenClaw has two onboarding paths. Both configure auth, the Gateway, and
|
||||
optional chat channels — they just differ in how you interact with the setup.
|
||||
|
||||
## Which path should I use?
|
||||
|
||||
| | CLI onboarding | macOS app onboarding |
|
||||
| -------------- | -------------------------------------- | --------------------------- |
|
||||
| **Platforms** | macOS, Linux, Windows (native or WSL2) | macOS only |
|
||||
| **Interface** | Terminal wizard | Guided UI + Crestodian chat |
|
||||
| **Best for** | Servers, headless, full control | Desktop Mac, visual setup |
|
||||
| **Automation** | `--non-interactive` for scripts | Manual only |
|
||||
| **Command** | `openclaw onboard` | Launch the app |
|
||||
|
||||
Most users should start with **CLI onboarding** — it works everywhere and gives
|
||||
you the most control.
|
||||
|
||||
## What onboarding configures
|
||||
|
||||
Regardless of which path you choose, onboarding sets up:
|
||||
|
||||
1. **Model provider and auth** — API key, OAuth, or setup token for your chosen provider
|
||||
2. **Workspace** — directory for agent files, bootstrap templates, and memory
|
||||
3. **Gateway** — port, bind address, auth mode
|
||||
4. **Channels** (optional) — built-in and bundled chat channels such as
|
||||
Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams,
|
||||
Telegram, WhatsApp, and more
|
||||
5. **Daemon** (optional) — background service so the Gateway starts automatically
|
||||
|
||||
## CLI onboarding
|
||||
|
||||
Run in any terminal:
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
Add `--install-daemon` to also install the background service in one step.
|
||||
|
||||
Full reference: [Onboarding (CLI)](/start/wizard)
|
||||
CLI command docs: [`openclaw onboard`](/cli/onboard)
|
||||
|
||||
## macOS app onboarding
|
||||
|
||||
Open the OpenClaw app. For local setup, the first-run flow starts the Gateway,
|
||||
then opens a Crestodian conversation that detects existing AI access, proposes
|
||||
the workspace and config, and applies the plan after approval. Sensitive
|
||||
credentials use masked input. Remote setup connects to an already-configured
|
||||
Gateway instead.
|
||||
|
||||
Full reference: [Onboarding (macOS App)](/start/onboarding)
|
||||
|
||||
## Custom or unlisted providers
|
||||
|
||||
If your provider is not listed in onboarding, choose **Custom Provider** and
|
||||
enter:
|
||||
|
||||
- Endpoint compatibility: OpenAI-compatible (`/chat/completions`), OpenAI Responses-compatible (`/responses`), Anthropic-compatible (`/messages`), or unknown (probes all three and auto-detects)
|
||||
- Base URL and API key (API key is optional if the endpoint does not require one)
|
||||
- Model ID and optional model alias
|
||||
|
||||
Multiple custom endpoints can coexist — each gets its own endpoint ID.
|
||||
|
||||
## Related
|
||||
|
||||
- [Getting started](/start/getting-started)
|
||||
- [CLI setup reference](/start/wizard-cli-reference)
|
||||
100
docs/start/onboarding.md
Normal file
100
docs/start/onboarding.md
Normal file
@@ -0,0 +1,100 @@
|
||||
---
|
||||
summary: "First-run setup flow for OpenClaw (macOS app)"
|
||||
read_when:
|
||||
- Designing the macOS onboarding assistant
|
||||
- Implementing auth or identity setup
|
||||
title: "Onboarding (macOS app)"
|
||||
sidebarTitle: "Onboarding: macOS App"
|
||||
---
|
||||
|
||||
The macOS app's first-run flow: pick where the Gateway runs, complete local
|
||||
setup through a Crestodian conversation, grant permissions, and hand off to
|
||||
the agent's own bootstrap ritual.
|
||||
For CLI onboarding and a comparison of both paths, see [Onboarding Overview](/start/onboarding-overview).
|
||||
|
||||
<Steps>
|
||||
<Step title="Approve macOS warning">
|
||||
<Frame>
|
||||
<img src="/assets/macos-onboarding/01-macos-warning.jpeg" alt="" />
|
||||
</Frame>
|
||||
</Step>
|
||||
<Step title="Approve find local networks">
|
||||
<Frame>
|
||||
<img src="/assets/macos-onboarding/02-local-networks.jpeg" alt="" />
|
||||
</Frame>
|
||||
</Step>
|
||||
<Step title="Welcome and security notice">
|
||||
<Frame caption="Read the security notice displayed and decide accordingly">
|
||||
<img src="/assets/macos-onboarding/03-security-notice.png" alt="" />
|
||||
</Frame>
|
||||
|
||||
Security trust model:
|
||||
|
||||
- By default, OpenClaw is a personal agent: one trusted operator boundary.
|
||||
- Shared/multi-user setups need lock-down: split trust boundaries, keep tool access minimal, and follow [Security](/gateway/security).
|
||||
- Local onboarding defaults new configs to `tools.profile: "coding"` so fresh setups keep filesystem/runtime tools without the unrestricted `full` profile.
|
||||
- If hooks/webhooks or other untrusted content feeds are enabled, use a strong modern model tier and keep strict tool policy/sandboxing.
|
||||
|
||||
</Step>
|
||||
<Step title="Local vs Remote">
|
||||
<Frame>
|
||||
<img src="/assets/macos-onboarding/04-choose-gateway.png" alt="" />
|
||||
</Frame>
|
||||
|
||||
Where does the **Gateway** run?
|
||||
|
||||
- **This Mac (Local only):** onboarding configures auth and writes credentials locally.
|
||||
- **Remote (over SSH/Tailnet):** onboarding does **not** configure local auth;
|
||||
credentials must already exist on the gateway host. The remote gateway token
|
||||
field stores the token the macOS app uses to connect to that Gateway;
|
||||
existing `gateway.remote.token` SecretRef values are preserved until you
|
||||
replace them.
|
||||
- **Configure later:** skip setup and leave the app unconfigured.
|
||||
|
||||
<Tip>
|
||||
**Gateway auth tip:**
|
||||
|
||||
- Gateway auth mode defaults to `token` even for loopback binds, so local WS clients must authenticate.
|
||||
- Setting `gateway.auth.mode: "none"` lets any local process connect; use that only on fully trusted machines.
|
||||
- Use a token for multi-machine access or non-loopback binds.
|
||||
|
||||
</Tip>
|
||||
</Step>
|
||||
<Step title="CLI">
|
||||
Local setup installs the global `openclaw` CLI via npm, pnpm, or bun,
|
||||
preferring npm first. Node remains the recommended runtime for the Gateway
|
||||
itself. Existing compatible installations are reused.
|
||||
</Step>
|
||||
<Step title="Talk to Crestodian">
|
||||
Local setup opens a dedicated conversation with Crestodian after the Gateway
|
||||
is ready. Crestodian detects an existing Claude Code or Codex login and
|
||||
supported API keys, proposes the workspace and configuration, then waits for
|
||||
approval before writing anything. Next remains locked until the conversation
|
||||
has authored setup state. Credential prompts use masked input; after an
|
||||
ambiguous transport failure, restart the setup conversation instead of
|
||||
replaying the previous turn.
|
||||
|
||||
Remote and Configure Later flows skip this local setup conversation.
|
||||
</Step>
|
||||
<Step title="Permissions">
|
||||
|
||||
<Frame caption="Choose what permissions do you want to give OpenClaw">
|
||||
<img src="/assets/macos-onboarding/05-permissions.png" alt="" />
|
||||
</Frame>
|
||||
|
||||
Onboarding requests TCC permissions for: Automation (AppleScript), Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Camera, and Location.
|
||||
|
||||
</Step>
|
||||
<Step title="Onboarding Chat (dedicated session)">
|
||||
After setup, the app opens a separate agent onboarding chat so the agent can
|
||||
introduce itself and guide next steps without mixing that exchange into the
|
||||
normal conversation history. This follows the Crestodian setup conversation;
|
||||
it does not replace it. See [Bootstrapping](/start/bootstrapping) for what
|
||||
happens on the gateway host during the agent's first real turn.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Related
|
||||
|
||||
- [Onboarding overview](/start/onboarding-overview)
|
||||
- [Getting started](/start/getting-started)
|
||||
244
docs/start/openclaw.md
Normal file
244
docs/start/openclaw.md
Normal file
@@ -0,0 +1,244 @@
|
||||
---
|
||||
summary: "End-to-end guide for running OpenClaw as a personal assistant with safety cautions"
|
||||
read_when:
|
||||
- Onboarding a new assistant instance
|
||||
- Reviewing safety/permission implications
|
||||
title: "Personal assistant setup"
|
||||
---
|
||||
|
||||
OpenClaw is a self-hosted gateway that connects Discord, Google Chat, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and more to AI agents. This guide covers the "personal assistant" setup: a dedicated WhatsApp number that behaves like your always-on AI assistant.
|
||||
|
||||
## Safety first
|
||||
|
||||
Giving an agent a channel puts it in a position to run commands on your machine (depending on your tool policy), read/write files in your workspace, and send messages back out via any connected channel. Start conservative:
|
||||
|
||||
- Always set `channels.whatsapp.allowFrom` (never run open-to-the-world on your personal Mac).
|
||||
- Use a dedicated WhatsApp number for the assistant.
|
||||
- Heartbeats default to every 30 minutes. Disable until you trust the setup by setting `agents.defaults.heartbeat.every: "0m"`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- OpenClaw installed and onboarded - see [Getting Started](/start/getting-started) if you haven't done this yet
|
||||
- A second phone number (SIM/eSIM/prepaid) for the assistant
|
||||
|
||||
## The two-phone setup (recommended)
|
||||
|
||||
You want this:
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
A["<b>Your Phone (personal)<br></b><br>Your WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Second Phone (assistant)<br></b><br>Assistant WA<br>+1-555-ASSIST"]
|
||||
B -- linked via QR --> C["<b>Your Mac (openclaw)<br></b><br>AI agent"]
|
||||
```
|
||||
|
||||
If you link your personal WhatsApp to OpenClaw, every message to you becomes "agent input". That's rarely what you want.
|
||||
|
||||
## 5-minute quick start
|
||||
|
||||
1. Pair WhatsApp Web (shows QR; scan with the assistant phone):
|
||||
|
||||
```bash
|
||||
openclaw channels login
|
||||
```
|
||||
|
||||
2. Start the Gateway (leave it running):
|
||||
|
||||
```bash
|
||||
openclaw gateway --port 18789
|
||||
```
|
||||
|
||||
3. Put a minimal config in `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: { mode: "local" },
|
||||
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
|
||||
}
|
||||
```
|
||||
|
||||
Now message the assistant number from your allowlisted phone.
|
||||
|
||||
When onboarding finishes, OpenClaw auto-opens the dashboard and prints a clean (non-tokenized) link. If the dashboard prompts for auth, paste the configured shared secret into Control UI settings. Onboarding uses a token by default (`gateway.auth.token`), but password auth works too if you switched `gateway.auth.mode` to `password`. To reopen later: `openclaw dashboard`.
|
||||
|
||||
## Give the agent a workspace (AGENTS)
|
||||
|
||||
OpenClaw reads operating instructions and "memory" from its workspace directory.
|
||||
|
||||
By default, OpenClaw uses `~/.openclaw/workspace` as the agent workspace, and creates it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`) automatically on onboarding or first agent run. `BOOTSTRAP.md` is only created for a brand-new workspace and should not come back after you delete it. `MEMORY.md` is optional and never auto-created; when present, it loads for normal sessions. Subagent sessions only inject `AGENTS.md` and `TOOLS.md`.
|
||||
|
||||
<Tip>
|
||||
Treat this folder like OpenClaw's memory and make it a git repo (ideally private) so your `AGENTS.md` and memory files are backed up. If git is installed, brand-new workspaces are auto-initialized with `git init`.
|
||||
</Tip>
|
||||
|
||||
To create the workspace and config folders without running the full onboarding wizard:
|
||||
|
||||
```bash
|
||||
openclaw setup --baseline
|
||||
```
|
||||
|
||||
(Bare `openclaw setup` is an alias for `openclaw onboard` and runs the full interactive wizard.)
|
||||
|
||||
Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
|
||||
Memory workflow: [Memory](/concepts/memory)
|
||||
|
||||
Optional: choose a different workspace with `agents.defaults.workspace` (supports `~`).
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
If you already ship your own workspace files from a repo, you can disable bootstrap file creation entirely:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
skipBootstrap: true,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## The config that turns it into "an assistant"
|
||||
|
||||
OpenClaw defaults to a good assistant setup, but you'll usually want to tune:
|
||||
|
||||
- persona/instructions in [`SOUL.md`](/concepts/soul)
|
||||
- thinking defaults (if desired)
|
||||
- heartbeats (once you trust it)
|
||||
|
||||
Example:
|
||||
|
||||
```json5
|
||||
{
|
||||
logging: { level: "info" },
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "anthropic/claude-opus-4-8" },
|
||||
workspace: "~/.openclaw/workspace",
|
||||
thinkingDefault: "high",
|
||||
timeoutSeconds: 1800,
|
||||
// Start with 0; enable later.
|
||||
heartbeat: { every: "0m" },
|
||||
},
|
||||
list: [
|
||||
{
|
||||
id: "main",
|
||||
default: true,
|
||||
groupChat: {
|
||||
mentionPatterns: ["@openclaw", "openclaw"],
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
channels: {
|
||||
whatsapp: {
|
||||
allowFrom: ["+15555550123"],
|
||||
groups: {
|
||||
"*": { requireMention: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
session: {
|
||||
scope: "per-sender",
|
||||
resetTriggers: ["/new", "/reset"],
|
||||
reset: {
|
||||
mode: "daily",
|
||||
atHour: 4,
|
||||
idleMinutes: 10080,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Sessions and memory
|
||||
|
||||
- Session files: `~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl`
|
||||
- Session metadata (token usage, last route, etc): `~/.openclaw/agents/<agentId>/sessions/sessions.json`
|
||||
- `/new` or `/reset` starts a fresh session for that chat (configurable via `session.resetTriggers`). If sent alone, OpenClaw acknowledges the reset without invoking the model.
|
||||
- `/compact [instructions]` compacts the session context and reports the remaining context budget.
|
||||
|
||||
## Heartbeats (proactive mode)
|
||||
|
||||
By default, OpenClaw runs a heartbeat every 30 minutes with the prompt:
|
||||
`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
|
||||
Set `agents.defaults.heartbeat.every: "0m"` to disable.
|
||||
|
||||
- If `HEARTBEAT.md` exists but is effectively empty (only blank lines, Markdown/HTML comments, Markdown headings like `# Heading`, fence markers, or empty checklist stubs), OpenClaw skips the heartbeat run to save API calls.
|
||||
- If the file is missing, the heartbeat still runs and the model decides what to do.
|
||||
- If the agent replies with `HEARTBEAT_OK` (optionally with short padding; see `agents.defaults.heartbeat.ackMaxChars`), OpenClaw suppresses outbound delivery for that heartbeat.
|
||||
- By default, heartbeat delivery to DM-style `user:<id>` targets is allowed. Set `agents.defaults.heartbeat.directPolicy: "block"` to suppress direct-target delivery while keeping heartbeat runs active.
|
||||
- Heartbeats run full agent turns - shorter intervals burn more tokens.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
heartbeat: { every: "30m" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Media in and out
|
||||
|
||||
Inbound attachments (images/audio/docs) can be surfaced to your command via templates:
|
||||
|
||||
- `{{MediaPath}}` (local temp file path)
|
||||
- `{{MediaUrl}}` (pseudo-URL)
|
||||
- `{{Transcript}}` (if audio transcription is enabled)
|
||||
|
||||
Outbound attachments from the agent use structured media fields on the message tool or reply payload, such as `media`, `mediaUrl`, `mediaUrls`, `path`, or `filePath`. Example message-tool arguments:
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Here's the screenshot.",
|
||||
"mediaUrl": "https://example.com/screenshot.png"
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw sends structured media alongside the text. Legacy final assistant replies may still be normalized for compatibility, but tool output, browser output, streaming blocks, and message actions do not parse text as attachment commands.
|
||||
|
||||
Local-path behavior follows the same file-read trust model as the agent:
|
||||
|
||||
- If `tools.fs.workspaceOnly` is `true`, outbound local media paths stay restricted to the OpenClaw temp root, the media cache, agent workspace paths, and sandbox-generated files.
|
||||
- If `tools.fs.workspaceOnly` is `false`, outbound local media can use host-local files the agent is already allowed to read.
|
||||
- Local paths can be absolute, workspace-relative, or home-relative with `~/`.
|
||||
- Host-local sends still only allow media and safe document types (images, audio, video, PDF, Office documents, and validated text documents such as Markdown/MD, TXT, JSON, YAML, and YML). This is an extension of the existing host-read trust boundary, not a secret scanner: if the agent can read a host-local `secret.txt` or `config.json`, it can attach that file when the extension and content validation match.
|
||||
|
||||
Keep sensitive files outside the agent-readable filesystem, or keep `tools.fs.workspaceOnly: true` for stricter local-path sends.
|
||||
|
||||
## Operations checklist
|
||||
|
||||
```bash
|
||||
openclaw status # local status (creds, sessions, queued events)
|
||||
openclaw status --all # full diagnosis (read-only, pasteable)
|
||||
openclaw status --deep # probe channels (WhatsApp Web + Telegram + Discord + Slack + Signal)
|
||||
openclaw health --json # gateway health snapshot over the WS connection
|
||||
```
|
||||
|
||||
Logs live under `/tmp/openclaw/` (default: `openclaw-YYYY-MM-DD.log`).
|
||||
|
||||
## Next steps
|
||||
|
||||
- WebChat: [WebChat](/web/webchat)
|
||||
- Gateway ops: [Gateway runbook](/gateway)
|
||||
- Cron + wakeups: [Cron jobs](/automation/cron-jobs)
|
||||
- macOS menu bar companion: [OpenClaw macOS app](/platforms/macos)
|
||||
- iOS node app: [iOS app](/platforms/ios)
|
||||
- Android node app: [Android app](/platforms/android)
|
||||
- Windows Hub: [Windows](/platforms/windows)
|
||||
- Linux status: [Linux app](/platforms/linux)
|
||||
- Security: [Security](/gateway/security)
|
||||
|
||||
## Related
|
||||
|
||||
- [Getting started](/start/getting-started)
|
||||
- [Setup](/start/setup)
|
||||
- [Channels overview](/channels)
|
||||
25
docs/start/quickstart.md
Normal file
25
docs/start/quickstart.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
summary: "Quick start has moved to Getting Started."
|
||||
read_when:
|
||||
- You are looking for the fastest setup steps
|
||||
- You were sent here from an older link
|
||||
title: "Quick start"
|
||||
---
|
||||
|
||||
<Info>
|
||||
Quick start is now part of [Getting Started](/start/getting-started).
|
||||
</Info>
|
||||
|
||||
<Columns>
|
||||
<Card title="Getting Started" href="/start/getting-started">
|
||||
Install OpenClaw and run your first chat in minutes.
|
||||
</Card>
|
||||
<Card title="Onboarding (CLI)" href="/start/wizard">
|
||||
Full CLI onboarding reference and advanced options.
|
||||
</Card>
|
||||
</Columns>
|
||||
|
||||
## Related
|
||||
|
||||
- [Getting started](/start/getting-started)
|
||||
- [Install overview](/install)
|
||||
178
docs/start/setup.md
Normal file
178
docs/start/setup.md
Normal file
@@ -0,0 +1,178 @@
|
||||
---
|
||||
summary: "Advanced setup and development workflows for OpenClaw"
|
||||
read_when:
|
||||
- Setting up a new machine
|
||||
- You want "latest + greatest" without breaking your personal setup
|
||||
title: "Setup"
|
||||
---
|
||||
|
||||
<Note>
|
||||
If you are setting up for the first time, start with [Getting Started](/start/getting-started).
|
||||
For onboarding details, see [Onboarding (CLI)](/start/wizard).
|
||||
</Note>
|
||||
|
||||
## TL;DR
|
||||
|
||||
Pick a setup workflow based on how often you want updates and whether you want to run the Gateway yourself:
|
||||
|
||||
- **Tailoring lives outside the repo:** keep your config and workspace in `~/.openclaw/openclaw.json` and `~/.openclaw/workspace/` so repo updates don't touch them.
|
||||
- **Stable workflow (recommended for most):** install the macOS app and let it run the bundled Gateway.
|
||||
- **Bleeding edge workflow (dev):** run the Gateway yourself via `pnpm gateway:watch`, then let the macOS app attach in Local mode.
|
||||
|
||||
## Prereqs (from source)
|
||||
|
||||
- Node 24 recommended (Node 22 LTS, currently `22.19+`, still supported)
|
||||
- `pnpm` required for source checkouts. OpenClaw loads bundled plugins from the
|
||||
`extensions/*` pnpm workspace packages in dev mode, so root `npm install` does
|
||||
not prepare the full source tree.
|
||||
- Docker (optional; only for containerized setup/e2e - see [Docker](/install/docker))
|
||||
|
||||
## Tailoring strategy (so updates do not hurt)
|
||||
|
||||
If you want "100% tailored to me" _and_ easy updates, keep your customization in:
|
||||
|
||||
- **Config:** `~/.openclaw/openclaw.json` (JSON/JSON5-ish)
|
||||
- **Workspace:** `~/.openclaw/workspace` (skills, prompts, memories; make it a private git repo)
|
||||
|
||||
Bootstrap the config/workspace folders once, without running the full onboarding wizard:
|
||||
|
||||
```bash
|
||||
openclaw setup --baseline
|
||||
```
|
||||
|
||||
No global install yet? Run it from this repo instead:
|
||||
|
||||
```bash
|
||||
pnpm openclaw setup --baseline
|
||||
```
|
||||
|
||||
(Bare `openclaw setup`, without `--baseline`, is an alias for `openclaw onboard` and runs the full interactive wizard.)
|
||||
|
||||
## Run the Gateway from this repo
|
||||
|
||||
After `pnpm build`, you can run the packaged CLI directly:
|
||||
|
||||
```bash
|
||||
node openclaw.mjs gateway --port 18789 --verbose
|
||||
```
|
||||
|
||||
## Stable workflow (macOS app first)
|
||||
|
||||
1. Install + launch **OpenClaw.app** (menu bar).
|
||||
2. Complete the onboarding/permissions checklist (TCC prompts).
|
||||
3. Ensure Gateway is **Local** and running (the app manages it).
|
||||
4. Link surfaces (example: WhatsApp):
|
||||
|
||||
```bash
|
||||
openclaw channels login
|
||||
```
|
||||
|
||||
5. Sanity check:
|
||||
|
||||
```bash
|
||||
openclaw health
|
||||
```
|
||||
|
||||
If onboarding is not available in your build:
|
||||
|
||||
- Run `openclaw setup`, then `openclaw channels login`, then start the Gateway manually (`openclaw gateway`).
|
||||
|
||||
## Bleeding edge workflow (Gateway in a terminal)
|
||||
|
||||
Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.
|
||||
|
||||
### 0) (Optional) Run the macOS app from source too
|
||||
|
||||
If you also want the macOS app on the bleeding edge:
|
||||
|
||||
```bash
|
||||
./scripts/restart-mac.sh
|
||||
```
|
||||
|
||||
### 1) Start the dev Gateway
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
# First run only (or after resetting local OpenClaw config/workspace)
|
||||
pnpm openclaw setup
|
||||
pnpm gateway:watch
|
||||
```
|
||||
|
||||
`gateway:watch` starts or restarts the Gateway watch process in a named tmux
|
||||
session (`openclaw-gateway-watch-main`) and auto-attaches from interactive
|
||||
terminals. Non-interactive shells stay detached and print
|
||||
`tmux attach -t openclaw-gateway-watch-main`; use
|
||||
`OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch` to keep an interactive run
|
||||
detached, or `pnpm gateway:watch:raw` for foreground watch mode. The watcher
|
||||
reloads on relevant source, config, and bundled-plugin metadata changes. If the
|
||||
watched Gateway exits during startup, `gateway:watch` runs
|
||||
`openclaw doctor --fix --non-interactive` once and retries; set
|
||||
`OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` to disable that dev-only repair pass.
|
||||
`pnpm gateway:watch` does not rebuild `dist/control-ui`, so rerun `pnpm ui:build` after `ui/` changes or use `pnpm ui:dev` while developing the Control UI.
|
||||
|
||||
### 2) Point the macOS app at your running Gateway
|
||||
|
||||
In **OpenClaw.app**:
|
||||
|
||||
- Connection Mode: **Local**
|
||||
The app will attach to the running gateway on the configured port.
|
||||
|
||||
### 3) Verify
|
||||
|
||||
- In-app Gateway status should read **"Using existing gateway …"**
|
||||
- Or via CLI:
|
||||
|
||||
```bash
|
||||
openclaw health
|
||||
```
|
||||
|
||||
### Common footguns
|
||||
|
||||
- **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
|
||||
- **Where state lives:**
|
||||
- Channel/provider state: `~/.openclaw/credentials/`
|
||||
- Model auth profiles: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- Sessions: `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Logs: `/tmp/openclaw/`
|
||||
|
||||
## Credential storage map
|
||||
|
||||
Use this when debugging auth or deciding what to back up:
|
||||
|
||||
- **WhatsApp**: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
|
||||
- **Telegram bot token**: config/env or `channels.telegram.tokenFile` (regular file only; symlinks rejected)
|
||||
- **Discord bot token**: config/env or SecretRef (env/file/exec providers)
|
||||
- **Slack tokens**: config/env (`channels.slack.*`)
|
||||
- **Pairing allowlists**:
|
||||
- `~/.openclaw/credentials/<channel>-allowFrom.json` (default account)
|
||||
- `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json` (non-default accounts)
|
||||
- **Model auth profiles**: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- **File-backed secrets payload (optional)**: `~/.openclaw/secrets.json`
|
||||
- **Legacy OAuth import**: `~/.openclaw/credentials/oauth.json`
|
||||
More detail: [Security](/gateway/security#credential-storage-map).
|
||||
|
||||
## Updating (without wrecking your setup)
|
||||
|
||||
- Keep `~/.openclaw/workspace` and `~/.openclaw/` as "your stuff"; don't put personal prompts/config into the `openclaw` repo.
|
||||
- Updating source: `git pull` + `pnpm install` + keep using `pnpm gateway:watch`.
|
||||
|
||||
## Linux (systemd user service)
|
||||
|
||||
Linux installs use a systemd **user** service. By default, systemd stops user
|
||||
services on logout/idle, which kills the Gateway. Onboarding attempts to enable
|
||||
lingering for you (may prompt for sudo). If it's still off, run:
|
||||
|
||||
```bash
|
||||
sudo loginctl enable-linger $USER
|
||||
```
|
||||
|
||||
For always-on or multi-user servers, consider a **system** service instead of a
|
||||
user service (no lingering needed). See [Gateway runbook](/gateway) for the systemd notes.
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Gateway runbook](/gateway) (flags, supervision, ports)
|
||||
- [Gateway configuration](/gateway/configuration) (config schema + examples)
|
||||
- [Discord](/channels/discord) and [Telegram](/channels/telegram) (reply tags + replyToMode settings)
|
||||
- [OpenClaw assistant setup](/start/openclaw)
|
||||
- [macOS app](/platforms/macos) (gateway lifecycle)
|
||||
369
docs/start/showcase.md
Normal file
369
docs/start/showcase.md
Normal file
@@ -0,0 +1,369 @@
|
||||
---
|
||||
summary: "Community-built projects and integrations powered by OpenClaw"
|
||||
title: "Showcase"
|
||||
description: "Real-world OpenClaw projects from the community"
|
||||
read_when:
|
||||
- Looking for real OpenClaw usage examples
|
||||
- Updating community project highlights
|
||||
---
|
||||
|
||||
Community-built OpenClaw projects: PR review loops, mobile apps, home automation, voice systems, devtools, and memory workflows, built chat-native on Telegram, WhatsApp, Discord, and terminals.
|
||||
|
||||
<Info>
|
||||
**Want to be featured?** Share your project in [#self-promotion on Discord](https://discord.gg/clawd) or [tag @openclaw on X](https://x.com/openclaw).
|
||||
</Info>
|
||||
|
||||
## Fresh from Discord
|
||||
|
||||
Recent standouts across coding, devtools, mobile, and chat-native product building.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="PR Review to Telegram Feedback" icon="code-pull-request" href="https://x.com/i/status/2010878524543131691">
|
||||
**@bangnokia** • `review` `github` `telegram`
|
||||
|
||||
OpenCode finishes the change, opens a PR, OpenClaw reviews the diff and replies in Telegram with suggestions plus a clear merge verdict.
|
||||
|
||||
<img src="/assets/showcase/pr-review-telegram.jpg" alt="OpenClaw PR review feedback delivered in Telegram" />
|
||||
</Card>
|
||||
|
||||
<Card title="Wine Cellar Skill in Minutes" icon="wine-glass" href="https://x.com/i/status/2010916352454791216">
|
||||
**@prades_maxime** • `skills` `local` `csv`
|
||||
|
||||
Asked "Robby" (@openclaw) for a local wine cellar skill. It requests a sample CSV export and a store path, then builds and tests the skill (962 bottles in the example).
|
||||
|
||||
<img src="/assets/showcase/wine-cellar-skill.jpg" alt="OpenClaw building a local wine cellar skill from CSV" />
|
||||
</Card>
|
||||
|
||||
<Card title="Tesco Shop Autopilot" icon="cart-shopping" href="https://x.com/i/status/2009724862470689131">
|
||||
**@marchattonhere** • `automation` `browser` `shopping`
|
||||
|
||||
Weekly meal plan, regulars, book delivery slot, confirm order. No APIs, just browser control.
|
||||
|
||||
<img src="/assets/showcase/tesco-shop.jpg" alt="Tesco shop automation via chat" />
|
||||
</Card>
|
||||
|
||||
<Card title="SNAG screenshot-to-Markdown" icon="scissors" href="https://github.com/am-will/snag">
|
||||
**@am-will** • `devtools` `screenshots` `markdown`
|
||||
|
||||
Hotkey a screen region, Gemini vision, instant Markdown in your clipboard.
|
||||
|
||||
<img src="/assets/showcase/snag.png" alt="SNAG screenshot-to-markdown tool" />
|
||||
</Card>
|
||||
|
||||
<Card title="Agents UI" icon="window-maximize" href="https://releaseflow.net/kitze/agents-ui">
|
||||
**@kitze** • `ui` `skills` `sync`
|
||||
|
||||
Desktop app to manage skills and commands across Agents, Claude, Codex, and OpenClaw.
|
||||
|
||||
<img src="/assets/showcase/agents-ui.jpg" alt="Agents UI app" />
|
||||
</Card>
|
||||
|
||||
<Card title="Telegram voice notes (papla.media)" icon="microphone" href="https://papla.media/docs">
|
||||
**Community** • `voice` `tts` `telegram`
|
||||
|
||||
Wraps papla.media TTS and sends results as Telegram voice notes (no annoying autoplay).
|
||||
|
||||
<img src="/assets/showcase/papla-tts.jpg" alt="Telegram voice note output from TTS" />
|
||||
</Card>
|
||||
|
||||
<Card title="CodexMonitor" icon="eye" href="https://clawhub.ai/odrobnik/skills/codexmonitor">
|
||||
**@odrobnik** • `devtools` `codex` `brew`
|
||||
|
||||
Homebrew-installed helper to list, inspect, and watch local OpenAI Codex sessions (CLI + VS Code).
|
||||
|
||||
<img src="/assets/showcase/codexmonitor.png" alt="CodexMonitor on ClawHub" />
|
||||
</Card>
|
||||
|
||||
<Card title="Bambu 3D Printer Control" icon="print" href="https://clawhub.ai/tobiasbischoff/skills/bambu-cli">
|
||||
**@tobiasbischoff** • `hardware` `3d-printing` `skill`
|
||||
|
||||
Control and troubleshoot BambuLab printers: status, jobs, camera, AMS, calibration, and more.
|
||||
|
||||
<img src="/assets/showcase/bambu-cli.png" alt="Bambu CLI skill on ClawHub" />
|
||||
</Card>
|
||||
|
||||
<Card title="Vienna transport (Wiener Linien)" icon="train" href="https://clawhub.ai/hjanuschka/skills/wienerlinien">
|
||||
**@hjanuschka** • `travel` `transport` `skill`
|
||||
|
||||
Real-time departures, disruptions, elevator status, and routing for Vienna's public transport.
|
||||
|
||||
<img src="/assets/showcase/wienerlinien.png" alt="Wiener Linien skill on ClawHub" />
|
||||
</Card>
|
||||
|
||||
<Card title="ParentPay school meals" icon="utensils">
|
||||
**@George5562** • `automation` `browser` `parenting`
|
||||
|
||||
Automated UK school meal booking via ParentPay. Uses mouse coordinates for reliable table cell clicking.
|
||||
</Card>
|
||||
|
||||
<Card title="R2 upload (Send Me My Files)" icon="cloud-arrow-up" href="https://clawhub.ai/julianengel/skills/r2-upload">
|
||||
**@julianengel** • `files` `r2` `presigned-urls`
|
||||
|
||||
Upload to Cloudflare R2/S3 and generate secure presigned download links. Useful for remote OpenClaw instances.
|
||||
|
||||
<img src="/assets/showcase/r2-upload.png" alt="R2 upload skill on ClawHub" />
|
||||
</Card>
|
||||
|
||||
<Card title="iOS app via Telegram" icon="mobile">
|
||||
**@coard** • `ios` `xcode` `app-store`
|
||||
|
||||
Built a complete iOS app with maps and voice recording, prepared for App Store distribution entirely via Telegram chat.
|
||||
</Card>
|
||||
|
||||
<Card title="Oura Ring health assistant" icon="heart-pulse">
|
||||
**@AS** • `health` `oura` `calendar`
|
||||
|
||||
Personal AI health assistant integrating Oura ring data with calendar, appointments, and gym schedule.
|
||||
|
||||
<img src="/assets/showcase/oura-health.png" alt="Oura ring health assistant" />
|
||||
</Card>
|
||||
|
||||
<Card title="Kev's Dream Team (14+ agents)" icon="robot" href="https://github.com/adam91holt/orchestrated-ai-articles">
|
||||
**@adam91holt** • `multi-agent` `orchestration`
|
||||
|
||||
14+ agents under one gateway with an Opus 4.5 orchestrator delegating to Codex workers. See the [technical write-up](https://github.com/adam91holt/orchestrated-ai-articles) and [Clawdspace](https://github.com/adam91holt/clawdspace) for agent sandboxing.
|
||||
</Card>
|
||||
|
||||
<Card title="Linear CLI" icon="terminal" href="https://github.com/Finesssee/linear-cli">
|
||||
**@NessZerra** • `devtools` `linear` `cli`
|
||||
|
||||
CLI for Linear that integrates with agentic workflows (Claude Code, OpenClaw). Manage issues, projects, and workflows from the terminal.
|
||||
</Card>
|
||||
|
||||
<Card title="Beeper CLI" icon="message" href="https://github.com/blqke/beepcli">
|
||||
**@jules** • `messaging` `beeper` `cli`
|
||||
|
||||
Read, send, and archive messages via Beeper Desktop. Uses Beeper local MCP API so agents can manage all your chats (iMessage, WhatsApp, and more) in one place.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## Automation and workflows
|
||||
|
||||
Scheduling, browser control, support loops, and the "just do the task for me" side of the product.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="Winix air purifier control" icon="wind" href="https://x.com/antonplex/status/2010518442471006253">
|
||||
**@antonplex** • `automation` `hardware` `air-quality`
|
||||
|
||||
Claude Code discovered and confirmed the purifier controls, then OpenClaw takes over to manage room air quality.
|
||||
|
||||
<img src="/assets/showcase/winix-air-purifier.jpg" alt="Winix air purifier control via OpenClaw" />
|
||||
</Card>
|
||||
|
||||
<Card title="Pretty sky camera shots" icon="camera" href="https://x.com/signalgaining/status/2010523120604746151">
|
||||
**@signalgaining** • `automation` `camera` `skill`
|
||||
|
||||
Triggered by a roof camera: ask OpenClaw to snap a sky photo whenever it looks pretty. It designed a skill and took the shot.
|
||||
|
||||
<img src="/assets/showcase/roof-camera-sky.jpg" alt="Roof camera sky snapshot captured by OpenClaw" />
|
||||
</Card>
|
||||
|
||||
<Card title="Visual morning briefing scene" icon="robot" href="https://x.com/buddyhadry/status/2010005331925954739">
|
||||
**@buddyhadry** • `automation` `briefing` `telegram`
|
||||
|
||||
A scheduled prompt generates one scene image each morning (weather, tasks, date, favorite post or quote) via an OpenClaw persona.
|
||||
</Card>
|
||||
|
||||
<Card title="Padel court booking" icon="calendar-check" href="https://github.com/joshp123/padel-cli">
|
||||
**@joshp123** • `automation` `booking` `cli`
|
||||
|
||||
Playtomic availability checker plus booking CLI. Never miss an open court again.
|
||||
|
||||
<img src="/assets/showcase/padel-screenshot.jpg" alt="padel-cli screenshot" />
|
||||
</Card>
|
||||
|
||||
<Card title="Accounting intake" icon="file-invoice-dollar">
|
||||
**Community** • `automation` `email` `pdf`
|
||||
|
||||
Collects PDFs from email, preps documents for a tax consultant. Monthly accounting on autopilot.
|
||||
</Card>
|
||||
|
||||
<Card title="Couch potato dev mode" icon="couch" href="https://davekiss.com">
|
||||
**@davekiss** • `telegram` `migration` `astro`
|
||||
|
||||
Rebuilt an entire personal site via Telegram while watching Netflix — Notion to Astro, 18 posts migrated, DNS to Cloudflare. Never opened a laptop.
|
||||
</Card>
|
||||
|
||||
<Card title="Job search agent" icon="briefcase">
|
||||
**@attol8** • `automation` `api` `skill`
|
||||
|
||||
Searches job listings, matches against CV keywords, and returns relevant opportunities with links. Built in 30 minutes using the JSearch API.
|
||||
</Card>
|
||||
|
||||
<Card title="Jira skill builder" icon="diagram-project" href="https://x.com/jdrhyne/status/2008336434827002232">
|
||||
**@jdrhyne** • `jira` `skill` `devtools`
|
||||
|
||||
OpenClaw connected to Jira, then generated a new skill on the fly (before it existed on ClawHub).
|
||||
</Card>
|
||||
|
||||
<Card title="Todoist skill via Telegram" icon="list-check" href="https://x.com/iamsubhrajyoti/status/2009949389884920153">
|
||||
**@iamsubhrajyoti** • `todoist` `skill` `telegram`
|
||||
|
||||
Automated Todoist tasks and had OpenClaw generate the skill directly in Telegram chat.
|
||||
</Card>
|
||||
|
||||
<Card title="TradingView analysis" icon="chart-line">
|
||||
**@bheem1798** • `finance` `browser` `automation`
|
||||
|
||||
Logs into TradingView via browser automation, screenshots charts, and performs technical analysis on demand. No API needed — just browser control.
|
||||
</Card>
|
||||
|
||||
<Card title="Slack auto-support" icon="slack">
|
||||
**@henrymascot** • `slack` `automation` `support`
|
||||
|
||||
Watches a company Slack channel, responds helpfully, and forwards notifications to Telegram. Autonomously fixed a production bug in a deployed app without being asked.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## Knowledge and memory
|
||||
|
||||
Systems that index, search, remember, and reason over personal or team knowledge.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="xuezh Chinese learning" icon="language" href="https://github.com/joshp123/xuezh">
|
||||
**@joshp123** • `learning` `voice` `skill`
|
||||
|
||||
Chinese learning engine with pronunciation feedback and study flows via OpenClaw.
|
||||
|
||||
<img src="/assets/showcase/xuezh-pronunciation.jpeg" alt="xuezh pronunciation feedback" />
|
||||
</Card>
|
||||
|
||||
<Card title="WhatsApp memory vault" icon="vault">
|
||||
**Community** • `memory` `transcription` `indexing`
|
||||
|
||||
Ingests full WhatsApp exports, transcribes 1k+ voice notes, cross-checks with git logs, outputs linked markdown reports.
|
||||
</Card>
|
||||
|
||||
<Card title="Karakeep semantic search" icon="magnifying-glass" href="https://github.com/jamesbrooksco/karakeep-semantic-search">
|
||||
**@jamesbrooksco** • `search` `vector` `bookmarks`
|
||||
|
||||
Adds vector search to Karakeep bookmarks using Qdrant plus OpenAI or Ollama embeddings.
|
||||
</Card>
|
||||
|
||||
<Card title="Inside-Out-2 memory" icon="brain">
|
||||
**Community** • `memory` `beliefs` `self-model`
|
||||
|
||||
Separate memory manager that turns session files into memories, then beliefs, then an evolving self model.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## Voice and phone
|
||||
|
||||
Speech-first entry points, phone bridges, and transcription-heavy workflows.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="Clawdia phone bridge" icon="phone" href="https://github.com/alejandroOPI/clawdia-bridge">
|
||||
**@alejandroOPI** • `voice` `vapi` `bridge`
|
||||
|
||||
Vapi voice assistant to OpenClaw HTTP bridge. Near real-time phone calls with your agent.
|
||||
</Card>
|
||||
|
||||
<Card title="OpenRouter transcription" icon="microphone" href="https://clawhub.ai/obviyus/skills/openrouter-transcribe">
|
||||
**@obviyus** • `transcription` `multilingual` `skill`
|
||||
|
||||
Multi-lingual audio transcription via OpenRouter (Gemini, and more). Available on ClawHub.
|
||||
|
||||
<img src="/assets/showcase/openrouter-transcribe.png" alt="OpenRouter transcription skill on ClawHub" />
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## Infrastructure and deployment
|
||||
|
||||
Packaging, deployment, and integrations that make OpenClaw easier to run and extend.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="Home Assistant add-on" icon="home" href="https://github.com/ngutman/openclaw-ha-addon">
|
||||
**@ngutman** • `homeassistant` `docker` `raspberry-pi`
|
||||
|
||||
OpenClaw gateway running on Home Assistant OS with SSH tunnel support and persistent state.
|
||||
</Card>
|
||||
|
||||
<Card title="Home Assistant skill" icon="toggle-on" href="https://clawhub.ai/homeofe/skills/openclaw-homeassistant">
|
||||
**@homeofe** • `homeassistant` `skill` `automation`
|
||||
|
||||
Control and automate Home Assistant devices via natural language.
|
||||
|
||||
<img src="/assets/showcase/homeassistant.png" alt="Home Assistant skill on ClawHub" />
|
||||
</Card>
|
||||
|
||||
<Card title="Nix packaging" icon="snowflake" href="https://github.com/openclaw/nix-openclaw">
|
||||
**@openclaw** • `nix` `packaging` `deployment`
|
||||
|
||||
Batteries-included nixified OpenClaw configuration for reproducible deployments.
|
||||
</Card>
|
||||
|
||||
<Card title="CalDAV calendar" icon="calendar" href="https://clawhub.ai/asleep123/skills/caldav-calendar">
|
||||
**@asleep123** • `calendar` `caldav` `skill`
|
||||
|
||||
Calendar skill using khal and vdirsyncer. Self-hosted calendar integration.
|
||||
|
||||
<img src="/assets/showcase/caldav-calendar.png" alt="CalDAV calendar skill on ClawHub" />
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## Home and hardware
|
||||
|
||||
The physical-world side of OpenClaw: homes, sensors, cameras, vacuums, and other devices.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="GoHome automation" icon="house-signal" href="https://github.com/joshp123/gohome">
|
||||
**@joshp123** • `home` `nix` `grafana`
|
||||
|
||||
Nix-native home automation with OpenClaw as the interface, plus Grafana dashboards.
|
||||
|
||||
<img src="/assets/showcase/gohome-grafana.png" alt="GoHome Grafana dashboard" />
|
||||
</Card>
|
||||
|
||||
<Card title="Roborock vacuum" icon="robot" href="https://github.com/joshp123/gohome/tree/main/plugins/roborock">
|
||||
**@joshp123** • `vacuum` `iot` `plugin`
|
||||
|
||||
Control your Roborock robot vacuum through natural conversation.
|
||||
|
||||
<img src="/assets/showcase/roborock-screenshot.jpg" alt="Roborock status" />
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## Community projects
|
||||
|
||||
Things that grew beyond a single workflow into broader products or ecosystems.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="StarSwap marketplace" icon="star" href="https://star-swap.com/">
|
||||
**Community** • `marketplace` `astronomy` `webapp`
|
||||
|
||||
Full astronomy gear marketplace. Built with and around the OpenClaw ecosystem.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## Submit your project
|
||||
|
||||
<Steps>
|
||||
<Step title="Share it">
|
||||
Post in [#self-promotion on Discord](https://discord.gg/clawd) or [tweet @openclaw](https://x.com/openclaw).
|
||||
</Step>
|
||||
<Step title="Include details">
|
||||
Tell us what it does, link to the repo or demo, and share a screenshot if you have one.
|
||||
</Step>
|
||||
<Step title="Get featured">
|
||||
We'll add standout projects to this page.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Related
|
||||
|
||||
- [Getting started](/start/getting-started)
|
||||
- [OpenClaw](/start/openclaw)
|
||||
209
docs/start/wizard-cli-automation.md
Normal file
209
docs/start/wizard-cli-automation.md
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
summary: "Scripted onboarding and agent setup for the OpenClaw CLI"
|
||||
read_when:
|
||||
- You are automating onboarding in scripts or CI
|
||||
- You need non-interactive examples for specific providers
|
||||
title: "CLI automation"
|
||||
sidebarTitle: "CLI automation"
|
||||
---
|
||||
|
||||
Use `openclaw onboard --non-interactive` to script setup. It requires `--accept-risk`: non-interactive setup can write credentials and daemon config without a confirmation prompt, so the flag is the explicit risk acknowledgement.
|
||||
|
||||
<Note>
|
||||
`--json` does not imply non-interactive mode. Pass `--non-interactive --accept-risk` explicitly for scripts.
|
||||
</Note>
|
||||
|
||||
## Baseline non-interactive example
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice apiKey \
|
||||
--anthropic-api-key "$ANTHROPIC_API_KEY" \
|
||||
--secret-input-mode plaintext \
|
||||
--gateway-bind loopback \
|
||||
--install-daemon \
|
||||
--daemon-runtime node \
|
||||
--skip-bootstrap \
|
||||
--skip-skills
|
||||
```
|
||||
|
||||
Add `--json` for a machine-readable summary.
|
||||
|
||||
- `--gateway-port` defaults to `18789`; only pass it to override.
|
||||
- `--skip-bootstrap` skips creating default workspace files, for automation that pre-seeds its own workspace.
|
||||
- `--secret-input-mode ref` stores an env-backed reference (`{ source: "env", provider: "default", id: "<ENV_VAR>" }`) in the auth profile instead of the plaintext key. In non-interactive `ref` mode, the provider env var must already be set in the process environment: passing an inline key flag without its matching env var fails fast.
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice openai-api-key \
|
||||
--secret-input-mode ref
|
||||
```
|
||||
|
||||
## Provider-specific examples
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Anthropic API key example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice apiKey \
|
||||
--anthropic-api-key "$ANTHROPIC_API_KEY" \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Cloudflare AI Gateway example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice cloudflare-ai-gateway-api-key \
|
||||
--cloudflare-ai-gateway-account-id "your-account-id" \
|
||||
--cloudflare-ai-gateway-gateway-id "your-gateway-id" \
|
||||
--cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Gemini example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice gemini-api-key \
|
||||
--gemini-api-key "$GEMINI_API_KEY" \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Mistral example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice mistral-api-key \
|
||||
--mistral-api-key "$MISTRAL_API_KEY" \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Moonshot example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice moonshot-api-key \
|
||||
--moonshot-api-key "$MOONSHOT_API_KEY" \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Ollama example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice ollama \
|
||||
--custom-model-id "qwen3.5:27b" \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="OpenCode example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice opencode-zen \
|
||||
--opencode-zen-api-key "$OPENCODE_API_KEY" \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
Swap to `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"` for the Go catalog.
|
||||
</Accordion>
|
||||
<Accordion title="Synthetic example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice synthetic-api-key \
|
||||
--synthetic-api-key "$SYNTHETIC_API_KEY" \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Vercel AI Gateway example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice ai-gateway-api-key \
|
||||
--ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Z.AI example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice zai-api-key \
|
||||
--zai-api-key "$ZAI_API_KEY" \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Custom provider example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice custom-api-key \
|
||||
--custom-base-url "https://llm.example.com/v1" \
|
||||
--custom-model-id "foo-large" \
|
||||
--custom-api-key "$CUSTOM_API_KEY" \
|
||||
--custom-provider-id "my-custom" \
|
||||
--custom-compatibility anthropic \
|
||||
--custom-image-input \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
`--custom-api-key` is optional; some endpoints do not require auth. If omitted, onboarding checks `CUSTOM_API_KEY` in env. `--custom-provider-id` is optional and auto-derived from the base URL when omitted. `--custom-compatibility` defaults to `openai` (other values: `openai-responses`, `anthropic`).
|
||||
|
||||
OpenClaw infers image-input support from known vision model-id patterns (`gpt-4o`, `claude-3/4`, `gemini`, `-vl`/`vision` suffixes, and similar). Add `--custom-image-input` to force it on for an unrecognized vision model, or `--custom-text-input` to force text-only.
|
||||
|
||||
Ref-mode variant, storing `apiKey` as `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`:
|
||||
|
||||
```bash
|
||||
export CUSTOM_API_KEY="your-key"
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--mode local \
|
||||
--auth-choice custom-api-key \
|
||||
--custom-base-url "https://llm.example.com/v1" \
|
||||
--custom-model-id "foo-large" \
|
||||
--secret-input-mode ref \
|
||||
--custom-provider-id "my-custom" \
|
||||
--custom-compatibility anthropic \
|
||||
--custom-image-input \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Anthropic setup-token auth remains supported, but OpenClaw prefers Claude CLI reuse when a local Claude CLI login is available. For production, prefer an Anthropic API key.
|
||||
|
||||
## Add another agent
|
||||
|
||||
`openclaw agents add <name>` creates a separate agent with its own workspace, sessions, and auth profiles. Running it without `--workspace` (and no other flags) launches the interactive wizard; passing any of `--workspace`, `--model`, `--agent-dir`, `--bind`, or `--non-interactive` runs it non-interactively and then requires `--workspace`.
|
||||
|
||||
```bash
|
||||
openclaw agents add work \
|
||||
--workspace ~/.openclaw/workspace-work \
|
||||
--model openai/gpt-5.5 \
|
||||
--bind whatsapp:biz \
|
||||
--non-interactive \
|
||||
--json
|
||||
```
|
||||
|
||||
Config keys it writes (`agents.list[]` entry for the new agent id):
|
||||
|
||||
- `name`
|
||||
- `workspace`
|
||||
- `agentDir`
|
||||
- `model` (only when `--model` is passed)
|
||||
|
||||
Notes:
|
||||
|
||||
- Default workspace (when `--workspace` is omitted in the interactive wizard): `~/.openclaw/workspace-<agentId>`.
|
||||
- `--bind <channel[:accountId]>` is repeatable; add bindings to route inbound messages to the new agent (the wizard can also do this interactively).
|
||||
- The agent name is normalized to a valid agent id; `main` is reserved.
|
||||
|
||||
## Related docs
|
||||
|
||||
- Onboarding hub: [Onboarding (CLI)](/start/wizard)
|
||||
- Full reference: [CLI Setup Reference](/start/wizard-cli-reference)
|
||||
- Command reference: [`openclaw onboard`](/cli/onboard)
|
||||
374
docs/start/wizard-cli-reference.md
Normal file
374
docs/start/wizard-cli-reference.md
Normal file
@@ -0,0 +1,374 @@
|
||||
---
|
||||
summary: "Step-by-step behavior for openclaw onboard: what each step does, config it writes, and internals"
|
||||
read_when:
|
||||
- You need detailed behavior for a specific openclaw onboard step
|
||||
- You are debugging onboarding results or integrating onboarding clients
|
||||
title: "CLI setup reference"
|
||||
sidebarTitle: "CLI reference"
|
||||
---
|
||||
|
||||
This page covers step-by-step onboarding behavior, outputs, and internals.
|
||||
For a walkthrough, see [Onboarding (CLI)](/start/wizard). For the full CLI flag
|
||||
reference (every `--flag`, non-interactive examples, provider-specific
|
||||
commands), see [`openclaw onboard`](/cli/onboard).
|
||||
|
||||
## What the wizard does
|
||||
|
||||
Local mode (default) walks you through:
|
||||
|
||||
- Model and auth setup (Anthropic, OpenAI Code subscription OAuth, xAI, OpenCode, custom endpoints, and more provider-owned auth flows)
|
||||
- Workspace location and bootstrap files
|
||||
- Gateway settings (port, bind, auth, Tailscale)
|
||||
- Channels and providers (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and other bundled or plugin channels)
|
||||
- Web search provider (optional)
|
||||
- Daemon install (LaunchAgent, systemd user unit, or native Windows Scheduled Task with Startup-folder fallback)
|
||||
- Health check
|
||||
- Skills setup
|
||||
|
||||
Remote mode configures this machine to connect to a Gateway elsewhere. It does
|
||||
not install or modify anything on the remote host.
|
||||
|
||||
## Local flow details
|
||||
|
||||
<Steps>
|
||||
<Step title="Existing config detection">
|
||||
- If `~/.openclaw/openclaw.json` exists, choose **Keep current values**, **Review and update**, or **Reset before setup**.
|
||||
- Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass `--reset`).
|
||||
- CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full` to also remove the workspace.
|
||||
- If config is invalid or contains legacy keys, the wizard stops and asks you to run `openclaw doctor` before continuing.
|
||||
- Reset moves state to Trash (never deletes directly) and offers scopes:
|
||||
- Config only
|
||||
- Config + credentials + sessions
|
||||
- Full reset (also removes the workspace)
|
||||
|
||||
</Step>
|
||||
<Step title="Model and auth">
|
||||
- Full option matrix is in [Auth and model options](#auth-and-model-options).
|
||||
|
||||
</Step>
|
||||
<Step title="Workspace">
|
||||
- Default `~/.openclaw/workspace` (configurable).
|
||||
- Seeds workspace files needed for first-run bootstrap.
|
||||
- Workspace layout: [Agent workspace](/concepts/agent-workspace).
|
||||
|
||||
</Step>
|
||||
<Step title="Gateway">
|
||||
- Prompts for port, bind, auth mode, and Tailscale exposure.
|
||||
- Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
|
||||
- In token mode, interactive setup offers:
|
||||
- **Generate/store plaintext token** (default)
|
||||
- **Use SecretRef** (opt-in)
|
||||
- In password mode, interactive setup also supports plaintext or SecretRef storage.
|
||||
- Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
|
||||
- Requires a non-empty env var in the onboarding process environment.
|
||||
- Cannot be combined with `--gateway-token`.
|
||||
- Disable auth only if you fully trust every local process.
|
||||
- Non-loopback binds still require auth.
|
||||
|
||||
</Step>
|
||||
<Step title="Channels">
|
||||
- [WhatsApp](/channels/whatsapp): optional QR login
|
||||
- [Telegram](/channels/telegram): bot token
|
||||
- [Discord](/channels/discord): bot token
|
||||
- [Google Chat](/channels/googlechat): service account JSON + webhook audience
|
||||
- [Mattermost](/channels/mattermost): bot token + base URL
|
||||
- [Signal](/channels/signal): optional `signal-cli` install + account config
|
||||
- [iMessage](/channels/imessage): `imsg` CLI path + Messages DB access; use an SSH wrapper when the Gateway runs off-Mac
|
||||
- DM security: default is pairing. First DM sends a code; approve via
|
||||
`openclaw pairing approve <channel> <code>` or use allowlists.
|
||||
</Step>
|
||||
<Step title="Web search">
|
||||
- Pick a provider (Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily) or skip.
|
||||
- Skip this step with `--skip-search`; reconfigure later with `openclaw configure --section web`.
|
||||
|
||||
</Step>
|
||||
<Step title="Daemon install">
|
||||
- macOS: LaunchAgent
|
||||
- Requires logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
|
||||
- Linux and Windows via WSL2: systemd user unit
|
||||
- Wizard attempts `loginctl enable-linger <user>` so gateway stays up after logout.
|
||||
- May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
|
||||
- Native Windows: Scheduled Task first
|
||||
- If task creation is denied, OpenClaw falls back to a per-user Startup-folder login item and starts the gateway immediately.
|
||||
- Scheduled Tasks remain preferred because they provide better supervisor status.
|
||||
- Runtime selection: only Node is offered interactively. Bun can corrupt memory on WhatsApp/Telegram reconnect and is not a supported daemon runtime for those channels; pass `--daemon-runtime bun` only outside that combination.
|
||||
|
||||
</Step>
|
||||
<Step title="Health check">
|
||||
- Starts gateway (if needed) and runs `openclaw health`.
|
||||
- `openclaw status --deep` adds the live gateway health probe to status output, including channel probes when supported.
|
||||
|
||||
</Step>
|
||||
<Step title="Skills">
|
||||
- Reads available skills and checks requirements.
|
||||
- Lets you choose node manager: npm, pnpm, or bun.
|
||||
- Installs optional dependencies for trusted bundled skills when the required
|
||||
installer is available.
|
||||
- Skips unavailable Homebrew, uv, and Go installers, then groups the affected
|
||||
skills with manual setup guidance. Run `openclaw doctor` after installing
|
||||
the missing prerequisites.
|
||||
|
||||
</Step>
|
||||
<Step title="Finish">
|
||||
- Summary and next steps, including iOS, Android, and macOS app options.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
|
||||
If Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
|
||||
</Note>
|
||||
|
||||
## Remote mode details
|
||||
|
||||
Remote mode configures this machine to connect to a Gateway elsewhere. It does
|
||||
not install or modify anything on the remote host.
|
||||
|
||||
What you set:
|
||||
|
||||
- Remote gateway URL (`ws://...` or `wss://...`)
|
||||
- Token, password, or no auth, matching the remote Gateway's configuration
|
||||
|
||||
<Steps>
|
||||
<Step title="Discovery (optional)">
|
||||
If `dns-sd` (macOS) or `avahi-browse` (Linux) is available, onboarding
|
||||
offers to search for Bonjour/mDNS gateway beacons before falling back to
|
||||
manual URL entry. Wide-area DNS-SD discovery is also attempted when
|
||||
configured. Docs: [Gateway discovery](/gateway/discovery), [Bonjour](/gateway/bonjour).
|
||||
</Step>
|
||||
<Step title="Connection method">
|
||||
When a beacon is selected, choose direct WebSocket or an SSH tunnel:
|
||||
- **Direct**: connects over `wss://` and prompts to trust the discovered
|
||||
TLS fingerprint (trust-on-first-use pinning; only pinned if you accept).
|
||||
- **SSH tunnel**: prints an `ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
|
||||
command to run first, then connects to the local tunnel endpoint.
|
||||
</Step>
|
||||
<Step title="Auth">
|
||||
Choose token (recommended), password, or no auth, then optionally store it
|
||||
as a SecretRef instead of plaintext.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
If the gateway is loopback-only and not discoverable, use SSH tunneling or a tailnet manually.
|
||||
Plaintext `ws://` is accepted for loopback, private IP literals, `.local`, and Tailnet `*.ts.net` URLs; other private-DNS names need `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`.
|
||||
</Note>
|
||||
|
||||
## Auth and model options
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Anthropic API key">
|
||||
Uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
|
||||
</Accordion>
|
||||
<Accordion title="Anthropic Claude CLI">
|
||||
Preferred local path in interactive onboarding/configure; reuses an existing Claude CLI sign-in when available.
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI Code subscription (OAuth)">
|
||||
Browser flow; paste `code#state`.
|
||||
|
||||
Sets `agents.defaults.model` to `openai/gpt-5.5` through the Codex runtime when model is unset or already OpenAI-family.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI Code subscription (device pairing)">
|
||||
Browser pairing flow with a short-lived device code.
|
||||
|
||||
Sets `agents.defaults.model` to `openai/gpt-5.5` through the Codex runtime when model is unset or already OpenAI-family.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI API key">
|
||||
Uses `OPENAI_API_KEY` if present or prompts for a key, then stores the credential in auth profiles.
|
||||
|
||||
Sets `agents.defaults.model` to `openai/gpt-5.5` when model is unset, `openai/*`, or legacy Codex model refs.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="xAI (Grok) OAuth">
|
||||
Browser sign-in for eligible SuperGrok or X Premium accounts. This is the
|
||||
recommended xAI path for most users. OpenClaw stores the resulting auth
|
||||
profile for Grok models, Grok `web_search`, `x_search`, and `code_execution`.
|
||||
</Accordion>
|
||||
<Accordion title="xAI (Grok) device code">
|
||||
Remote-friendly browser sign-in with a short code instead of a localhost
|
||||
callback. Use this from SSH, Docker, or VPS hosts.
|
||||
</Accordion>
|
||||
<Accordion title="xAI (Grok) API key">
|
||||
Prompts for `XAI_API_KEY` and configures xAI as a model provider. Use this
|
||||
when you want an xAI Console API key instead of subscription OAuth.
|
||||
</Accordion>
|
||||
<Accordion title="OpenCode">
|
||||
Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`) and lets you choose the Zen or Go catalog (one API key covers both).
|
||||
Setup URL: [opencode.ai/auth](https://opencode.ai/auth).
|
||||
</Accordion>
|
||||
<Accordion title="API key (generic)">
|
||||
Stores the key for you.
|
||||
</Accordion>
|
||||
<Accordion title="Vercel AI Gateway">
|
||||
Prompts for `AI_GATEWAY_API_KEY`.
|
||||
More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway).
|
||||
</Accordion>
|
||||
<Accordion title="Cloudflare AI Gateway">
|
||||
Prompts for account ID, gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
|
||||
More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway).
|
||||
</Accordion>
|
||||
<Accordion title="MiniMax">
|
||||
Config is auto-written. Hosted default is `MiniMax-M3`; API-key setup uses
|
||||
`minimax/...`, and OAuth setup uses `minimax-portal/...`.
|
||||
More detail: [MiniMax](/providers/minimax).
|
||||
</Accordion>
|
||||
<Accordion title="StepFun">
|
||||
Config is auto-written for StepFun standard or Step Plan on China or global endpoints.
|
||||
Standard currently includes `step-3.5-flash`, and Step Plan also includes `step-3.5-flash-2603`.
|
||||
More detail: [StepFun](/providers/stepfun).
|
||||
</Accordion>
|
||||
<Accordion title="Synthetic (Anthropic-compatible)">
|
||||
Prompts for `SYNTHETIC_API_KEY`.
|
||||
More detail: [Synthetic](/providers/synthetic).
|
||||
</Accordion>
|
||||
<Accordion title="Ollama (Cloud and local open models)">
|
||||
Prompts for `Cloud + Local`, `Cloud only`, or `Local only` first.
|
||||
`Cloud only` uses `OLLAMA_API_KEY` with `https://ollama.com`.
|
||||
The host-backed modes prompt for base URL (default `http://127.0.0.1:11434`), discover available models, and suggest defaults.
|
||||
`Cloud + Local` also checks whether that Ollama host is signed in for cloud access.
|
||||
More detail: [Ollama](/providers/ollama).
|
||||
</Accordion>
|
||||
<Accordion title="Moonshot and Kimi Coding">
|
||||
Moonshot (Kimi K2) and Kimi Coding configs are auto-written.
|
||||
More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot).
|
||||
</Accordion>
|
||||
<Accordion title="Custom provider">
|
||||
Works with OpenAI-compatible, OpenAI Responses-compatible, and Anthropic-compatible endpoints.
|
||||
|
||||
Interactive onboarding supports the same API key storage choices as other provider API key flows:
|
||||
- **Paste API key now** (plaintext)
|
||||
- **Use secret reference** (env ref or configured provider ref, with preflight validation)
|
||||
|
||||
Onboarding infers image support for common vision model IDs (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral, and similar) and only asks when the model name is unknown.
|
||||
|
||||
Non-interactive flags:
|
||||
- `--auth-choice custom-api-key`
|
||||
- `--custom-base-url`
|
||||
- `--custom-model-id`
|
||||
- `--custom-api-key` (optional; falls back to `CUSTOM_API_KEY`)
|
||||
- `--custom-provider-id` (optional)
|
||||
- `--custom-compatibility <openai|openai-responses|anthropic>` (optional; default `openai`)
|
||||
- `--custom-image-input` / `--custom-text-input` (optional; override inferred model input capability)
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Skip">
|
||||
Leaves auth unconfigured.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Model behavior:
|
||||
|
||||
- Pick default model from detected options, or enter provider and model manually.
|
||||
- When onboarding starts from a provider auth choice, the model picker prefers
|
||||
that provider automatically. For Volcengine and BytePlus, the same preference
|
||||
also matches their coding-plan variants (`volcengine-plan/*`,
|
||||
`byteplus-plan/*`).
|
||||
- If that preferred-provider filter would be empty, the picker falls back to
|
||||
the full catalog instead of showing no models.
|
||||
- Wizard runs a model check and warns if the configured model is unknown or missing auth.
|
||||
|
||||
Credential and profile paths:
|
||||
|
||||
- Auth profiles (API keys + OAuth): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- Legacy OAuth import: `~/.openclaw/credentials/oauth.json`
|
||||
|
||||
Credential storage mode:
|
||||
|
||||
- Default onboarding behavior persists API keys as plaintext values in auth profiles.
|
||||
- `--secret-input-mode ref` enables reference mode instead of plaintext key storage.
|
||||
In interactive setup, you can choose either:
|
||||
- environment variable ref (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`)
|
||||
- configured provider ref (`file` or `exec`) with provider alias + id
|
||||
- Interactive reference mode runs a fast preflight validation before saving.
|
||||
- Env refs: validates variable name + non-empty value in the current onboarding environment.
|
||||
- Provider refs: validates provider config and resolves the requested id.
|
||||
- If preflight fails, onboarding shows the error and lets you retry.
|
||||
- In non-interactive mode, `--secret-input-mode ref` is env-backed only.
|
||||
- Set the provider env var in the onboarding process environment.
|
||||
- Inline key flags (for example `--openai-api-key`) require that env var to be set; otherwise onboarding fails fast.
|
||||
- For custom providers, non-interactive `ref` mode stores `models.providers.<id>.apiKey` as `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`.
|
||||
- In that custom-provider case, `--custom-api-key` requires `CUSTOM_API_KEY` to be set; otherwise onboarding fails fast.
|
||||
- Gateway auth credentials support plaintext and SecretRef choices in interactive setup:
|
||||
- Token mode: **Generate/store plaintext token** (default) or **Use SecretRef**.
|
||||
- Password mode: plaintext or SecretRef.
|
||||
- Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
|
||||
- Existing plaintext setups continue to work unchanged.
|
||||
|
||||
<Note>
|
||||
Headless and server tip: complete OAuth on a machine with a browser, then copy
|
||||
that agent's `auth-profiles.json` (for example
|
||||
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`, or the matching
|
||||
`$OPENCLAW_STATE_DIR/...` path) to the gateway host. `credentials/oauth.json`
|
||||
is only a legacy import source.
|
||||
</Note>
|
||||
|
||||
## Outputs and internals
|
||||
|
||||
Typical fields in `~/.openclaw/openclaw.json`:
|
||||
|
||||
- `agents.defaults.workspace`
|
||||
- `agents.defaults.skipBootstrap` when `--skip-bootstrap` is passed
|
||||
- `agents.defaults.model` / `models.providers` (if Minimax chosen)
|
||||
- `tools.profile` (local onboarding defaults to `"coding"` when unset; existing explicit values are preserved)
|
||||
- `gateway.*` (mode, bind, auth, tailscale)
|
||||
- `session.dmScope` (local onboarding defaults this to `per-channel-peer` when unset; existing explicit values are preserved)
|
||||
- `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*`
|
||||
- Channel allowlists (Discord, iMessage, Signal, Slack, Telegram, WhatsApp) when you opt in during prompts; Discord and Slack also resolve entered names to IDs
|
||||
- `skills.install.nodeManager`
|
||||
- The `setup --node-manager` flag accepts `npm`, `pnpm`, or `bun`.
|
||||
- Manual config can still set `skills.install.nodeManager: "yarn"` later.
|
||||
- `wizard.lastRunAt`
|
||||
- `wizard.lastRunVersion`
|
||||
- `wizard.lastRunCommit`
|
||||
- `wizard.lastRunCommand`
|
||||
- `wizard.lastRunMode`
|
||||
- `wizard.securityAcknowledgedAt`
|
||||
|
||||
`openclaw agents add` writes `agents.list[]` and optional `bindings`.
|
||||
|
||||
WhatsApp credentials go under `~/.openclaw/credentials/whatsapp/<accountId>/`.
|
||||
Sessions are stored under `~/.openclaw/agents/<agentId>/sessions/`.
|
||||
|
||||
<Note>
|
||||
Some channels are delivered as plugins. When selected during setup, the wizard
|
||||
prompts to install the plugin (npm or local path) before channel configuration.
|
||||
</Note>
|
||||
|
||||
## Non-interactive setup
|
||||
|
||||
`--non-interactive` requires `--accept-risk` (acknowledges that agents are
|
||||
powerful and full system access is risky):
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive --accept-risk \
|
||||
--auth-choice apiKey \
|
||||
--anthropic-api-key "$ANTHROPIC_API_KEY"
|
||||
```
|
||||
|
||||
Full flag reference and provider-specific examples: [`openclaw onboard`](/cli/onboard), [CLI automation](/start/wizard-cli-automation).
|
||||
|
||||
## Gateway wizard RPC
|
||||
|
||||
- `wizard.start`
|
||||
- `wizard.next`
|
||||
- `wizard.cancel`
|
||||
- `wizard.status`
|
||||
|
||||
Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.
|
||||
|
||||
## Signal setup behavior
|
||||
|
||||
- Downloads the appropriate release asset from the official `signal-cli` GitHub releases (native build, Linux x86-64 only)
|
||||
- On other platforms (macOS, non-x64 Linux), installs via Homebrew instead
|
||||
- Stores the release-asset install under `~/.openclaw/tools/signal-cli/<version>/`
|
||||
- Writes `channels.signal.cliPath` in config
|
||||
- Native Windows is not supported yet; run onboarding inside WSL2 to get the Linux install path
|
||||
|
||||
## Related docs
|
||||
|
||||
- Onboarding hub: [Onboarding (CLI)](/start/wizard)
|
||||
- Automation and scripts: [CLI Automation](/start/wizard-cli-automation)
|
||||
- Command reference: [`openclaw onboard`](/cli/onboard)
|
||||
171
docs/start/wizard.md
Normal file
171
docs/start/wizard.md
Normal file
@@ -0,0 +1,171 @@
|
||||
---
|
||||
summary: "CLI onboarding: guided setup for gateway, workspace, channels, and skills"
|
||||
read_when:
|
||||
- Running or configuring CLI onboarding
|
||||
- Setting up a new machine
|
||||
title: "Onboarding (CLI)"
|
||||
sidebarTitle: "Onboarding: CLI"
|
||||
---
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
CLI onboarding is the recommended terminal setup path on macOS, Linux, and
|
||||
Windows (native or WSL2). It configures a local Gateway (or a connection to a
|
||||
remote Gateway), plus channels, skills, and workspace defaults in one guided
|
||||
flow. `openclaw setup` runs the same flow ([Setup](/cli/setup) covers the
|
||||
`--baseline` config-only variant). Windows desktop users can also start from
|
||||
[Windows Hub](/platforms/windows).
|
||||
|
||||
Provider sign-in, channel pairing, daemon install, and skill downloads can
|
||||
extend a quick setup; optional steps can be skipped and revisited later with
|
||||
`openclaw configure`.
|
||||
|
||||
<Info>
|
||||
Fastest first chat: skip channel setup entirely. Run `openclaw dashboard` and
|
||||
chat in the browser through the Control UI. Docs: [Dashboard](/web/dashboard).
|
||||
</Info>
|
||||
|
||||
## Locale
|
||||
|
||||
The wizard localizes fixed onboarding copy. Resolve order: `OPENCLAW_LOCALE`,
|
||||
`LC_ALL`, `LC_MESSAGES`, `LANG`, then English. Supported locales: `en`,
|
||||
`zh-CN`, `zh-TW`.
|
||||
|
||||
```bash
|
||||
OPENCLAW_LOCALE=zh-CN openclaw onboard
|
||||
```
|
||||
|
||||
Product names, commands, config keys, URLs, provider IDs, model IDs, and
|
||||
plugin/channel labels stay in English regardless of locale.
|
||||
|
||||
To reconfigure later:
|
||||
|
||||
```bash
|
||||
openclaw configure
|
||||
openclaw agents add <name>
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--json` does not imply non-interactive mode. For scripts, use `--non-interactive` (see [CLI automation](/start/wizard-cli-automation)).
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Onboarding includes a web search step where you can pick a provider: Brave,
|
||||
DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web
|
||||
Search, Perplexity, SearXNG, or Tavily. Some need an API key; others are
|
||||
key-free. Configure this later with `openclaw configure --section web`. Docs:
|
||||
[Web tools](/tools/web).
|
||||
</Tip>
|
||||
|
||||
## QuickStart vs Advanced
|
||||
|
||||
Onboarding opens with a choice between **QuickStart** (defaults) and
|
||||
**Advanced** (full control). Pass `--flow quickstart` or `--flow advanced`
|
||||
(alias `manual`) to skip the prompt.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="QuickStart (defaults)">
|
||||
- Local gateway, loopback bind
|
||||
- Workspace default (or existing workspace)
|
||||
- Gateway port **18789**
|
||||
- Gateway auth **Token** (auto-generated, even on loopback)
|
||||
- Tool policy: `tools.profile: "coding"` for new setups (an existing explicit profile is preserved)
|
||||
- DM isolation: `session.dmScope: "per-channel-peer"` for new setups. Details: [CLI setup reference](/start/wizard-cli-reference#outputs-and-internals)
|
||||
- Tailscale exposure **Off**
|
||||
- Telegram and WhatsApp DMs default to **allowlist**: Telegram asks for a numeric Telegram user ID, WhatsApp asks for a phone number
|
||||
|
||||
</Tab>
|
||||
<Tab title="Advanced (full control)">
|
||||
- Exposes every step: mode, workspace, gateway, channels, daemon, skills
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Remote mode (`--mode remote`) always uses the advanced flow; it only
|
||||
configures this machine to connect to a Gateway elsewhere and never installs
|
||||
or changes anything on the remote host.
|
||||
|
||||
## What onboarding configures
|
||||
|
||||
Local mode (default) walks through these steps:
|
||||
|
||||
1. **Model/Auth** - pick a provider auth flow (API key, OAuth, or
|
||||
provider-specific manual auth), including Custom Provider
|
||||
(OpenAI-compatible, OpenAI Responses-compatible, Anthropic-compatible, or
|
||||
Unknown auto-detect). Pick a default model.
|
||||
Security note: if this agent will run tools or process webhook/hook
|
||||
content, prefer the strongest latest-generation model available and keep
|
||||
tool policy strict - weaker or older tiers are easier to prompt-inject.
|
||||
For non-interactive runs, `--secret-input-mode ref` stores env-backed refs
|
||||
instead of plaintext API key values; the referenced env var must already
|
||||
be set, or onboarding fails fast. Interactive secret reference mode can
|
||||
point at an environment variable or a configured provider ref (`file` or
|
||||
`exec`), with a fast preflight check before saving.
|
||||
2. **Workspace** - directory for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files.
|
||||
3. **Gateway** - port, bind address, auth mode, Tailscale exposure. In
|
||||
interactive token mode, choose plaintext token storage (default) or opt
|
||||
into a SecretRef. Non-interactive SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
|
||||
4. **Channels** - built-in and official plugin chat channels, including
|
||||
Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams,
|
||||
QQ Bot, Signal, Slack, Telegram, WhatsApp, and more.
|
||||
5. **Daemon** - installs a LaunchAgent (macOS), a systemd user unit
|
||||
(Linux/WSL2), or a native Windows Scheduled Task with a per-user
|
||||
Startup-folder fallback.
|
||||
If token auth is required and `gateway.auth.token` is SecretRef-managed,
|
||||
daemon install validates it but does not persist a resolved token into
|
||||
supervisor service environment metadata; an unresolved SecretRef blocks
|
||||
install with guidance. If both `gateway.auth.token` and
|
||||
`gateway.auth.password` are set while `gateway.auth.mode` is unset, install
|
||||
is blocked until you set the mode explicitly.
|
||||
6. **Health check** - starts the Gateway and verifies it is reachable.
|
||||
7. **Skills** - installs recommended skills and their optional dependencies.
|
||||
|
||||
<Note>
|
||||
Re-running onboarding does **not** wipe anything unless you explicitly choose
|
||||
**Reset** (or pass `--reset`). CLI `--reset` defaults to config, credentials,
|
||||
and sessions; use `--reset-scope full` to also remove the workspace. If the
|
||||
config is invalid or contains legacy keys, onboarding asks you to run
|
||||
`openclaw doctor` first.
|
||||
</Note>
|
||||
|
||||
`--flow import` runs a detected migration flow (for example Hermes) instead of
|
||||
fresh setup; see [Migrate](/cli/migrate) and the migration guides under
|
||||
[Install](/install/migrating-hermes). `openclaw onboard --modern` starts
|
||||
[Crestodian](/cli/crestodian), a conversational setup/repair assistant, in
|
||||
place of the classic wizard.
|
||||
|
||||
## Add another agent
|
||||
|
||||
Use `openclaw agents add <name>` to create a separate agent with its own
|
||||
workspace, sessions, and auth profiles. Running without `--workspace` starts
|
||||
an interactive flow for name, workspace, auth, channels, and bindings - it is
|
||||
not the full `openclaw onboard` wizard.
|
||||
|
||||
What it sets:
|
||||
|
||||
- `agents.list[].name`
|
||||
- `agents.list[].workspace`
|
||||
- `agents.list[].agentDir`
|
||||
|
||||
Notes:
|
||||
|
||||
- Default workspace: `~/.openclaw/workspace-<agentId>` (or under
|
||||
`agents.defaults.workspace` if that is set).
|
||||
- Add `bindings` to route inbound messages to this agent (onboarding can do this for you).
|
||||
- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
|
||||
|
||||
## Full reference
|
||||
|
||||
For detailed step-by-step behavior and config outputs, see
|
||||
[CLI setup reference](/start/wizard-cli-reference).
|
||||
For non-interactive examples, see [CLI automation](/start/wizard-cli-automation).
|
||||
For the full flag reference, see [`openclaw onboard`](/cli/onboard).
|
||||
|
||||
## Related docs
|
||||
|
||||
- CLI command reference: [`openclaw onboard`](/cli/onboard)
|
||||
- Onboarding overview: [Onboarding overview](/start/onboarding-overview)
|
||||
- macOS app onboarding: [Onboarding](/start/onboarding)
|
||||
- Agent first-run ritual: [Agent Bootstrapping](/start/bootstrapping)
|
||||
Reference in New Issue
Block a user