mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-10 18:35:48 +08:00
重构主控编排与运行时预热链路，统一工作区提示词/专家调度协议并补齐 wiki 记忆注入与写回闭环。
同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。 Made-with: Cursor
This commit is contained in:
parent
4a23b715a2
commit
dbbe3add6a
14438 changed files with 2693620 additions and 2546 deletions
41
openclaw/docs/start/bootstrapping.md
Normal file
41
openclaw/docs/start/bootstrapping.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
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"
|
||||
---
|
||||
|
||||
# Agent Bootstrapping
|
||||
|
||||
Bootstrapping is the **first‑run** ritual that prepares an agent workspace and
|
||||
collects identity details. It happens after onboarding, when the agent starts
|
||||
for the first time.
|
||||
|
||||
## What bootstrapping does
|
||||
|
||||
On the first agent run, OpenClaw bootstraps the workspace (default
|
||||
`~/.openclaw/workspace`):
|
||||
|
||||
- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
|
||||
- Runs a short Q&A ritual (one question at a time).
|
||||
- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`.
|
||||
- Removes `BOOTSTRAP.md` when finished so it only runs once.
|
||||
|
||||
## Where it runs
|
||||
|
||||
Bootstrapping always runs on the **gateway host**. If the macOS app connects to
|
||||
a remote Gateway, the workspace and bootstrapping files live on that remote
|
||||
machine.
|
||||
|
||||
<Note>
|
||||
When the Gateway runs on another machine, edit workspace files on the gateway
|
||||
host (for example, `user@gateway-host:~/.openclaw/workspace`).
|
||||
</Note>
|
||||
|
||||
## Related docs
|
||||
|
||||
- macOS app onboarding: [Onboarding](/start/onboarding)
|
||||
- Workspace layout: [Agent workspace](/concepts/agent-workspace)
|
||||
67
openclaw/docs/start/docs-directory.md
Normal file
67
openclaw/docs/start/docs-directory.md
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
summary: "Curated links to the most used OpenClaw docs."
|
||||
read_when:
|
||||
- You want quick access to key docs pages
|
||||
title: "Docs directory"
|
||||
---
|
||||
|
||||
# Docs Directory
|
||||
|
||||
<Note>
|
||||
This page is a curated index. If you are new, start with [Getting Started](/start/getting-started).
|
||||
For a complete map of the docs, see [Docs hubs](/start/hubs).
|
||||
</Note>
|
||||
|
||||
## Start here
|
||||
|
||||
- [Docs hubs (all pages linked)](/start/hubs)
|
||||
- [Help](/help)
|
||||
- [Configuration](/gateway/configuration)
|
||||
- [Configuration examples](/gateway/configuration-examples)
|
||||
- [Slash commands](/tools/slash-commands)
|
||||
- [Multi-agent routing](/concepts/multi-agent)
|
||||
- [Updating and rollback](/install/updating)
|
||||
- [Pairing (DM and nodes)](/channels/pairing)
|
||||
- [Nix mode](/install/nix)
|
||||
- [OpenClaw assistant setup](/start/openclaw)
|
||||
- [Skills](/tools/skills)
|
||||
- [Skills config](/tools/skills-config)
|
||||
- [Workspace templates](/reference/templates/AGENTS)
|
||||
- [RPC adapters](/reference/rpc)
|
||||
- [Gateway runbook](/gateway)
|
||||
- [Nodes (iOS and Android)](/nodes)
|
||||
- [Web surfaces (Control UI)](/web)
|
||||
- [Discovery and transports](/gateway/discovery)
|
||||
- [Remote access](/gateway/remote)
|
||||
|
||||
## Providers and UX
|
||||
|
||||
- [WebChat](/web/webchat)
|
||||
- [Control UI (browser)](/web/control-ui)
|
||||
- [Telegram](/channels/telegram)
|
||||
- [Discord](/channels/discord)
|
||||
- [Mattermost](/channels/mattermost)
|
||||
- [BlueBubbles (iMessage)](/channels/bluebubbles)
|
||||
- [QQ Bot](/channels/qqbot)
|
||||
- [iMessage (legacy)](/channels/imessage)
|
||||
- [Groups](/channels/groups)
|
||||
- [WhatsApp group messages](/channels/group-messages)
|
||||
- [Media images](/nodes/images)
|
||||
- [Media audio](/nodes/audio)
|
||||
|
||||
## Companion apps
|
||||
|
||||
- [macOS app](/platforms/macos)
|
||||
- [iOS app](/platforms/ios)
|
||||
- [Android app](/platforms/android)
|
||||
- [Windows (WSL2)](/platforms/windows)
|
||||
- [Linux app](/platforms/linux)
|
||||
|
||||
## Operations and safety
|
||||
|
||||
- [Sessions](/concepts/session)
|
||||
- [Cron jobs](/automation/cron-jobs)
|
||||
- [Webhooks](/automation/cron-jobs#webhooks)
|
||||
- [Gmail hooks (Pub/Sub)](/automation/cron-jobs#gmail-pubsub-integration)
|
||||
- [Security](/gateway/security)
|
||||
- [Troubleshooting](/gateway/troubleshooting)
|
||||
148
openclaw/docs/start/getting-started.md
Normal file
148
openclaw/docs/start/getting-started.md
Normal file
|
|
@ -0,0 +1,148 @@
|
|||
---
|
||||
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"
|
||||
---
|
||||
|
||||
# Getting Started
|
||||
|
||||
Install OpenClaw, run onboarding, and chat with your AI assistant — all in
|
||||
about 5 minutes. By the end you will have a running Gateway, configured auth,
|
||||
and a working chat session.
|
||||
|
||||
## What you need
|
||||
|
||||
- **Node.js** — Node 24 recommended (Node 22.14+ also supported)
|
||||
- **An API key** from a model provider (Anthropic, OpenAI, Google, etc.) — onboarding will prompt you
|
||||
|
||||
<Tip>
|
||||
Check your Node version with `node --version`.
|
||||
**Windows users:** both native Windows and WSL2 are supported. WSL2 is more
|
||||
stable and recommended for the full experience. See [Windows](/platforms/windows).
|
||||
Need to install Node? See [Node setup](/install/node).
|
||||
</Tip>
|
||||
|
||||
## Quick setup
|
||||
|
||||
<Steps>
|
||||
<Step title="Install OpenClaw">
|
||||
<Tabs>
|
||||
<Tab title="macOS / Linux">
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
<img
|
||||
src="/assets/install-script.svg"
|
||||
alt="Install Script Process"
|
||||
className="rounded-lg"
|
||||
/>
|
||||
</Tab>
|
||||
<Tab title="Windows (PowerShell)">
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
Other install methods (Docker, Nix, npm): [Install](/install).
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
<Step title="Run onboarding">
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
The wizard walks you through choosing a model provider, setting an API key,
|
||||
and configuring the Gateway. It takes about 2 minutes.
|
||||
|
||||
See [Onboarding (CLI)](/start/wizard) for the full reference.
|
||||
|
||||
</Step>
|
||||
<Step title="Verify the Gateway is running">
|
||||
```bash
|
||||
openclaw gateway status
|
||||
```
|
||||
|
||||
You should see the Gateway listening on port 18789.
|
||||
|
||||
</Step>
|
||||
<Step title="Open the dashboard">
|
||||
```bash
|
||||
openclaw dashboard
|
||||
```
|
||||
|
||||
This opens the Control UI in your browser. If it loads, everything is working.
|
||||
|
||||
</Step>
|
||||
<Step title="Send your first message">
|
||||
Type a message in the Control UI chat and you should get an AI reply.
|
||||
|
||||
Want to chat from your phone instead? The fastest channel to set up is
|
||||
[Telegram](/channels/telegram) (just a bot token). See [Channels](/channels)
|
||||
for all options.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Accordion title="Advanced: mount a custom Control UI build">
|
||||
If you maintain a localized or customized dashboard build, point
|
||||
`gateway.controlUi.root` to a directory that contains your built static
|
||||
assets and `index.html`.
|
||||
|
||||
```bash
|
||||
mkdir -p "$HOME/.openclaw/control-ui-custom"
|
||||
# Copy your built static files into that directory.
|
||||
```
|
||||
|
||||
Then set:
|
||||
|
||||
```json
|
||||
{
|
||||
"gateway": {
|
||||
"controlUi": {
|
||||
"enabled": true,
|
||||
"root": "$HOME/.openclaw/control-ui-custom"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Restart the gateway and reopen the dashboard:
|
||||
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
openclaw dashboard
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
## What to do next
|
||||
|
||||
<Columns>
|
||||
<Card title="Connect a channel" href="/channels" icon="message-square">
|
||||
Discord, Feishu, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and more.
|
||||
</Card>
|
||||
<Card title="Pairing and safety" href="/channels/pairing" icon="shield">
|
||||
Control who can message your agent.
|
||||
</Card>
|
||||
<Card title="Configure the Gateway" href="/gateway/configuration" icon="settings">
|
||||
Models, tools, sandbox, and advanced settings.
|
||||
</Card>
|
||||
<Card title="Browse tools" href="/tools" icon="wrench">
|
||||
Browser, exec, web search, skills, and plugins.
|
||||
</Card>
|
||||
</Columns>
|
||||
|
||||
<Accordion title="Advanced: environment variables">
|
||||
If you run OpenClaw as a service account or want custom paths:
|
||||
|
||||
- `OPENCLAW_HOME` — home directory for internal path resolution
|
||||
- `OPENCLAW_STATE_DIR` — override the state directory
|
||||
- `OPENCLAW_CONFIG_PATH` — override the config file path
|
||||
|
||||
Full reference: [Environment variables](/help/environment).
|
||||
</Accordion>
|
||||
199
openclaw/docs/start/hubs.md
Normal file
199
openclaw/docs/start/hubs.md
Normal file
|
|
@ -0,0 +1,199 @@
|
|||
---
|
||||
summary: "Hubs that link to every OpenClaw doc"
|
||||
read_when:
|
||||
- You want a complete map of the documentation
|
||||
title: "Docs Hubs"
|
||||
---
|
||||
|
||||
# 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)
|
||||
- [WhatsApp](/channels/whatsapp)
|
||||
- [Telegram](/channels/telegram)
|
||||
- [Slack](/channels/slack)
|
||||
- [Discord](/channels/discord)
|
||||
- [Mattermost](/channels/mattermost)
|
||||
- [Signal](/channels/signal)
|
||||
- [BlueBubbles (iMessage)](/channels/bluebubbles)
|
||||
- [QQ Bot](/channels/qqbot)
|
||||
- [iMessage (legacy)](/channels/imessage)
|
||||
- [Location parsing](/channels/location)
|
||||
- [WebChat](/web/webchat)
|
||||
- [Webhooks](/automation/cron-jobs#webhooks)
|
||||
- [Gmail Pub/Sub](/automation/cron-jobs#gmail-pubsub-integration)
|
||||
|
||||
## Gateway + operations
|
||||
|
||||
- [Gateway runbook](/gateway)
|
||||
- [Network model](/gateway/network-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 & Tasks](/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 (WSL2)](/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)
|
||||
|
||||
## Extensions + plugins
|
||||
|
||||
- [Plugins overview](/tools/plugin)
|
||||
- [Building plugins](/plugins/building-plugins)
|
||||
- [Plugin manifest](/plugins/manifest)
|
||||
- [Agent tools](/plugins/building-plugins#registering-agent-tools)
|
||||
- [Plugin bundles](/plugins/bundles)
|
||||
- [Community plugins](/plugins/community)
|
||||
- [Capability cookbook](/tools/capability-cookbook)
|
||||
- [Voice call plugin](/plugins/voice-call)
|
||||
- [Zalo user plugin](/plugins/zalouser)
|
||||
|
||||
## Workspace + templates
|
||||
|
||||
- [Skills](/tools/skills)
|
||||
- [ClawHub](/tools/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)
|
||||
219
openclaw/docs/start/lore.md
Normal file
219
openclaw/docs/start/lore.md
Normal file
|
|
@ -0,0 +1,219 @@
|
|||
---
|
||||
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.
|
||||
|
||||
But then came a space lobster.
|
||||
|
||||
For a while, the lobster was called **Clawd**, living in a **Clawdbot**. But in January 2026, Anthropic sent a polite email asking for a name change (trademark stuff). And so the lobster did what lobsters do best:
|
||||
|
||||
**It molted.**
|
||||
|
||||
Shedding its old shell, the creature emerged anew as **Molty**, living in **Moltbot**. But that name never quite rolled off the tongue either...
|
||||
|
||||
So 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...
|
||||
|
||||
In the end, **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
|
||||
|
||||
```
|
||||
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/` (soon `~/molt/`), 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. Where 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 was given elevated access to generate their own new icon. After 20+ iterations of increasingly cursed lobsters, one attempt to make the mascot "5 years older" resulted in 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. And so, at 4am GMT, the team gathered AGAIN.
|
||||
|
||||
**The Great OpenClaw Migration** began.
|
||||
|
||||
In just 3 hours:
|
||||
|
||||
- GitHub renamed: `github.com/openclaw/openclaw` ✅
|
||||
- X handle `@openclaw` secured with GOLD CHECKMARK 💰
|
||||
- npm packages released under new name
|
||||
- Docs migrated to `docs.openclaw.ai`
|
||||
- 200K+ views on announcement in 90 minutes
|
||||
|
||||
**The Heroes:**
|
||||
|
||||
- **ELU** created incredible logos including "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 Discord vanity, nuked malware
|
||||
- **The whole Claw Crew** pulled an all-nighter
|
||||
|
||||
**The Scammer Speedrun:** Crypto grifters launched a $OPENCLAW token on Pump.fun within MINUTES. They stole artwork that was created 20 minutes earlier. Business-verified accounts pushed scams. 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
|
||||
|
||||
```
|
||||
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 emerged: 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
|
||||
|
||||
🦞💙
|
||||
69
openclaw/docs/start/onboarding-overview.md
Normal file
69
openclaw/docs/start/onboarding-overview.md
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
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"
|
||||
---
|
||||
|
||||
# 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 in the app |
|
||||
| **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
|
||||
BlueBubbles, Discord, Feishu, Google Chat, 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. The first-run wizard walks you through the same steps
|
||||
with a visual interface.
|
||||
|
||||
Full reference: [Onboarding (macOS App)](/start/onboarding)
|
||||
|
||||
## Custom or unlisted providers
|
||||
|
||||
If your provider is not listed in onboarding, choose **Custom Provider** and
|
||||
enter:
|
||||
|
||||
- API compatibility mode (OpenAI-compatible, Anthropic-compatible, or auto-detect)
|
||||
- Base URL and API key
|
||||
- Model ID and optional alias
|
||||
|
||||
Multiple custom endpoints can coexist — each gets its own endpoint ID.
|
||||
92
openclaw/docs/start/onboarding.md
Normal file
92
openclaw/docs/start/onboarding.md
Normal file
|
|
@ -0,0 +1,92 @@
|
|||
---
|
||||
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"
|
||||
---
|
||||
|
||||
# Onboarding (macOS App)
|
||||
|
||||
This doc describes the **current** first‑run setup flow. The goal is a
|
||||
smooth “day 0” experience: pick where the Gateway runs, connect auth, run the
|
||||
wizard, and let the agent bootstrap itself.
|
||||
For a general overview of onboarding 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 require lock-down (split trust boundaries, keep tool access minimal, and follow [Security](/gateway/security)).
|
||||
- Local onboarding now defaults new configs to `tools.profile: "coding"` so fresh local setups keep filesystem/runtime tools without forcing 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 can configure auth and write credentials
|
||||
locally.
|
||||
- **Remote (over SSH/Tailnet):** onboarding does **not** configure local auth;
|
||||
credentials must exist on the gateway host.
|
||||
- **Configure later:** skip setup and leave the app unconfigured.
|
||||
|
||||
<Tip>
|
||||
**Gateway auth tip:**
|
||||
|
||||
- The wizard now generates a **token** even for loopback, so local WS clients must authenticate.
|
||||
- If you disable auth, any local process can connect; use that only on fully trusted machines.
|
||||
- Use a **token** for multi‑machine access or non‑loopback binds.
|
||||
|
||||
</Tip>
|
||||
</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 needed for:
|
||||
|
||||
- Automation (AppleScript)
|
||||
- Notifications
|
||||
- Accessibility
|
||||
- Screen Recording
|
||||
- Microphone
|
||||
- Speech Recognition
|
||||
- Camera
|
||||
- Location
|
||||
|
||||
</Step>
|
||||
<Step title="CLI">
|
||||
<Info>This step is optional</Info>
|
||||
The app can install the global `openclaw` CLI via npm, pnpm, or bun.
|
||||
It prefers npm first, then pnpm, then bun if that is the only detected
|
||||
package manager. For the Gateway runtime, Node remains the recommended path.
|
||||
</Step>
|
||||
<Step title="Onboarding Chat (dedicated session)">
|
||||
After setup, the app opens a dedicated onboarding chat session so the agent can
|
||||
introduce itself and guide next steps. This keeps first‑run guidance separate
|
||||
from your normal conversation. See [Bootstrapping](/start/bootstrapping) for
|
||||
what happens on the gateway host during the first agent run.
|
||||
</Step>
|
||||
</Steps>
|
||||
225
openclaw/docs/start/openclaw.md
Normal file
225
openclaw/docs/start/openclaw.md
Normal file
|
|
@ -0,0 +1,225 @@
|
|||
---
|
||||
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"
|
||||
---
|
||||
|
||||
# Building a personal assistant with OpenClaw
|
||||
|
||||
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
|
||||
|
||||
You’re putting an agent in a position to:
|
||||
|
||||
- run commands on your machine (depending on your tool policy)
|
||||
- read/write files in your workspace
|
||||
- send messages back out via WhatsApp/Telegram/Discord/Mattermost and other bundled channels
|
||||
|
||||
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 now 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, we auto-open the dashboard and print a clean (non-tokenized) link. If it 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 will create it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`) automatically on setup/first agent run. `BOOTSTRAP.md` is only created when the workspace is brand new (it should not come back after you delete it). `MEMORY.md` is optional (not auto-created); when present, it is loaded 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` + memory files are backed up. If git is installed, brand-new workspaces are auto-initialized.
|
||||
|
||||
```bash
|
||||
openclaw setup
|
||||
```
|
||||
|
||||
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
|
||||
{
|
||||
agent: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
If you already ship your own workspace files from a repo, you can disable bootstrap file creation entirely:
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
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" },
|
||||
agent: {
|
||||
model: "anthropic/claude-opus-4-6",
|
||||
workspace: "~/.openclaw/workspace",
|
||||
thinkingDefault: "high",
|
||||
timeoutSeconds: 1800,
|
||||
// Start with 0; enable later.
|
||||
heartbeat: { every: "0m" },
|
||||
},
|
||||
channels: {
|
||||
whatsapp: {
|
||||
allowFrom: ["+15555550123"],
|
||||
groups: {
|
||||
"*": { requireMention: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
routing: {
|
||||
groupChat: {
|
||||
mentionPatterns: ["@openclaw", "openclaw"],
|
||||
},
|
||||
},
|
||||
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` (legacy: `~/.openclaw/sessions/sessions.json`)
|
||||
- `/new` or `/reset` starts a fresh session for that chat (configurable via `resetTriggers`). If sent alone, the agent replies with a short hello to confirm the reset.
|
||||
- `/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 and markdown headers like `# Heading`), 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
|
||||
{
|
||||
agent: {
|
||||
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: include `MEDIA:<path-or-url>` on its own line (no spaces). Example:
|
||||
|
||||
```
|
||||
Here’s the screenshot.
|
||||
MEDIA:https://example.com/screenshot.png
|
||||
```
|
||||
|
||||
OpenClaw extracts these and sends them as media alongside the text.
|
||||
|
||||
Local-path behavior follows the same file-read trust model as the agent:
|
||||
|
||||
- If `tools.fs.workspaceOnly` is `true`, outbound `MEDIA:` local 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 `MEDIA:` can use host-local files the agent is already allowed to read.
|
||||
- Host-local sends still only allow media and safe document types (images, audio, video, PDF, and Office documents). Plain text and secret-like files are not treated as sendable media.
|
||||
|
||||
That means generated images/files outside the workspace can now send when your fs policy already allows those reads, without reopening arbitrary host-text attachment exfiltration.
|
||||
|
||||
## Operations checklist
|
||||
|
||||
```bash
|
||||
openclaw status # local status (creds, sessions, queued events)
|
||||
openclaw status --all # full diagnosis (read-only, pasteable)
|
||||
openclaw status --deep # asks the gateway for a live health probe with channel probes when supported
|
||||
openclaw health --json # gateway health snapshot (WS; default can return a fresh cached snapshot)
|
||||
```
|
||||
|
||||
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 status: [Windows (WSL2)](/platforms/windows)
|
||||
- Linux status: [Linux app](/platforms/linux)
|
||||
- Security: [Security](/gateway/security)
|
||||
22
openclaw/docs/start/quickstart.md
Normal file
22
openclaw/docs/start/quickstart.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
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"
|
||||
---
|
||||
|
||||
# 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>
|
||||
178
openclaw/docs/start/setup.md
Normal file
178
openclaw/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"
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
- **Tailoring lives outside the repo:** `~/.openclaw/workspace` (workspace) + `~/.openclaw/openclaw.json` (config).
|
||||
- **Stable workflow:** install the macOS app; let it run the bundled Gateway.
|
||||
- **Bleeding edge workflow:** 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.14+`, still supported)
|
||||
- `pnpm` preferred (or Bun if you intentionally use the [Bun workflow](/install/bun))
|
||||
- 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 once:
|
||||
|
||||
```bash
|
||||
openclaw setup
|
||||
```
|
||||
|
||||
From inside this repo, use the local CLI entry:
|
||||
|
||||
```bash
|
||||
openclaw setup
|
||||
```
|
||||
|
||||
If you don’t have a global install yet, run it via `pnpm openclaw setup` (or `bun run openclaw setup` if you are using the Bun workflow).
|
||||
|
||||
## 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` runs the gateway in watch mode and reloads on relevant source,
|
||||
config, and bundled-plugin metadata changes.
|
||||
`pnpm openclaw setup` is the one-time local config/workspace initialization step for a fresh checkout.
|
||||
`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.
|
||||
|
||||
If you are intentionally using the Bun workflow, the equivalent commands are:
|
||||
|
||||
```bash
|
||||
bun install
|
||||
# First run only (or after resetting local OpenClaw config/workspace)
|
||||
bun run openclaw setup
|
||||
bun run gateway:watch
|
||||
```
|
||||
|
||||
### 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` + your chosen package-manager install step (`pnpm install` by default; `bun install` for Bun workflow) + keep using the matching `gateway:watch` command.
|
||||
|
||||
## 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)
|
||||
473
openclaw/docs/start/showcase.md
Normal file
473
openclaw/docs/start/showcase.md
Normal file
|
|
@ -0,0 +1,473 @@
|
|||
---
|
||||
title: "Showcase"
|
||||
description: "Real-world OpenClaw projects from the community"
|
||||
summary: "Community-built projects and integrations powered by OpenClaw"
|
||||
read_when:
|
||||
- Looking for real OpenClaw usage examples
|
||||
- Updating community project highlights
|
||||
---
|
||||
|
||||
<!-- markdownlint-disable MD033 -->
|
||||
|
||||
# Showcase
|
||||
|
||||
<div className="showcase-hero">
|
||||
<p className="showcase-kicker">Built in chats, terminals, browsers, and living rooms</p>
|
||||
<p className="showcase-lead">
|
||||
OpenClaw projects are not toy demos. People are shipping PR review loops, mobile apps, home automation,
|
||||
voice systems, devtools, and memory-heavy workflows from the channels they already use.
|
||||
</p>
|
||||
<div className="showcase-actions">
|
||||
<a href="#videos">Watch demos</a>
|
||||
<a href="#fresh-from-discord">Browse projects</a>
|
||||
<a href="https://discord.gg/clawd">Share yours</a>
|
||||
</div>
|
||||
<div className="showcase-highlights">
|
||||
<div className="showcase-highlight">
|
||||
<strong>Chat-native builds</strong>
|
||||
<span>Telegram, WhatsApp, Discord, Beeper, web chat, and terminal-first workflows.</span>
|
||||
</div>
|
||||
<div className="showcase-highlight">
|
||||
<strong>Real automation</strong>
|
||||
<span>Booking, shopping, support, reporting, and browser control without waiting for an API.</span>
|
||||
</div>
|
||||
<div className="showcase-highlight">
|
||||
<strong>Local + physical world</strong>
|
||||
<span>Printers, vacuums, cameras, health data, home systems, and personal knowledge bases.</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<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>
|
||||
|
||||
<div className="showcase-jump-links">
|
||||
<a href="#videos">Videos</a>
|
||||
<a href="#fresh-from-discord">Fresh from Discord</a>
|
||||
<a href="#automation-workflows">Automation</a>
|
||||
<a href="#knowledge-memory">Memory</a>
|
||||
<a href="#voice-phone">Voice & Phone</a>
|
||||
<a href="#infrastructure-deployment">Infrastructure</a>
|
||||
<a href="#home-hardware">Home & Hardware</a>
|
||||
<a href="#community-projects">Community</a>
|
||||
<a href="#submit-your-project">Submit a project</a>
|
||||
</div>
|
||||
|
||||
<h2 id="videos">Videos</h2>
|
||||
|
||||
<p className="showcase-section-intro">
|
||||
Start here if you want the shortest path from “what is this?” to “okay, I get it.”
|
||||
</p>
|
||||
|
||||
<div className="showcase-video-grid">
|
||||
<div className="showcase-video-card">
|
||||
<div className="showcase-video-shell">
|
||||
<iframe
|
||||
src="https://www.youtube-nocookie.com/embed/SaWSPZoPX34"
|
||||
title="OpenClaw: The self-hosted AI that Siri should have been (Full setup)"
|
||||
loading="lazy"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
allowFullScreen
|
||||
/>
|
||||
</div>
|
||||
<h3>Full setup walkthrough</h3>
|
||||
<p>VelvetShark, 28 minutes. Install, onboard, and get to a first working assistant end to end.</p>
|
||||
<a href="https://www.youtube.com/watch?v=SaWSPZoPX34">Watch on YouTube</a>
|
||||
</div>
|
||||
|
||||
<div className="showcase-video-card">
|
||||
<div className="showcase-video-shell">
|
||||
<iframe
|
||||
src="https://www.youtube-nocookie.com/embed/mMSKQvlmFuQ"
|
||||
title="OpenClaw showcase video"
|
||||
loading="lazy"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
allowFullScreen
|
||||
/>
|
||||
</div>
|
||||
<h3>Community showcase reel</h3>
|
||||
<p>A faster pass across real projects, surfaces, and workflows built around OpenClaw.</p>
|
||||
<a href="https://www.youtube.com/watch?v=mMSKQvlmFuQ">Watch on YouTube</a>
|
||||
</div>
|
||||
|
||||
<div className="showcase-video-card">
|
||||
<div className="showcase-video-shell">
|
||||
<iframe
|
||||
src="https://www.youtube-nocookie.com/embed/5kkIJNUGFho"
|
||||
title="OpenClaw community showcase"
|
||||
loading="lazy"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
allowFullScreen
|
||||
/>
|
||||
</div>
|
||||
<h3>Projects in the wild</h3>
|
||||
<p>Examples from the community, from chat-native coding loops to hardware and personal automation.</p>
|
||||
<a href="https://www.youtube.com/watch?v=5kkIJNUGFho">Watch on YouTube</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h2 id="fresh-from-discord">Fresh from Discord</h2>
|
||||
|
||||
<p className="showcase-section-intro">
|
||||
Recent standouts across coding, devtools, mobile, and chat-native product building.
|
||||
</p>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="PR Review → 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 “minor suggestions” plus a clear merge verdict (including critical fixes to apply first).
|
||||
|
||||
<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 + where to store it, then builds/tests the skill fast (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/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/codexmonitor">
|
||||
**@odrobnik** • `devtools` `codex` `brew`
|
||||
|
||||
Homebrew-installed helper to list/inspect/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/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/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/skills/r2-upload">
|
||||
**@julianengel** • `files` `r2` `presigned-urls`
|
||||
|
||||
Upload to Cloudflare R2/S3 and generate secure presigned download links. Perfect for remote OpenClaw instances.
|
||||
</Card>
|
||||
|
||||
<Card title="iOS App via Telegram" icon="mobile">
|
||||
**@coard** • `ios` `xcode` `testflight`
|
||||
|
||||
Built a complete iOS app with maps and voice recording, deployed to TestFlight entirely via Telegram chat.
|
||||
|
||||
<img src="/assets/showcase/ios-testflight.jpg" alt="iOS app on TestFlight" />
|
||||
</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` `architecture` `manifesto`
|
||||
|
||||
14+ agents under one gateway with Opus 4.5 orchestrator delegating to Codex workers. Comprehensive [technical write-up](https://github.com/adam91holt/orchestrated-ai-articles) covering the Dream Team roster, model selection, sandboxing, webhooks, heartbeats, and delegation flows. [Clawdspace](https://github.com/adam91holt/clawdspace) for agent sandboxing. [Blog post](https://adams-ai-journey.ghost.io/2026-the-year-of-the-orchestrator/).
|
||||
</Card>
|
||||
|
||||
<Card title="Linear CLI" icon="terminal" href="https://github.com/Finesssee/linear-cli">
|
||||
**@NessZerra** • `devtools` `linear` `cli` `issues`
|
||||
|
||||
CLI for Linear that integrates with agentic workflows (Claude Code, OpenClaw). Manage issues, projects, and workflows from the terminal. First external PR merged!
|
||||
</Card>
|
||||
|
||||
<Card title="Beeper CLI" icon="message" href="https://github.com/blqke/beepcli">
|
||||
**@jules** • `messaging` `beeper` `cli` `automation`
|
||||
|
||||
Read, send, and archive messages via Beeper Desktop. Uses Beeper local MCP API so agents can manage all your chats (iMessage, WhatsApp, etc.) in one place.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
<h2 id="automation-workflows">Automation & Workflows</h2>
|
||||
|
||||
<p className="showcase-section-intro">
|
||||
Scheduling, browser control, support loops, and the “just do the task for me” side of the product.
|
||||
</p>
|
||||
|
||||
<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` `images`
|
||||
|
||||
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` `images` `telegram`
|
||||
|
||||
A scheduled prompt generates a single "scene" image each morning (weather, tasks, date, favorite post/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 + 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 tax consultant. Monthly accounting on autopilot.
|
||||
</Card>
|
||||
|
||||
<Card title="Couch Potato Dev Mode" icon="couch" href="https://davekiss.com">
|
||||
**@davekiss** • `telegram` `website` `migration` `astro`
|
||||
|
||||
Rebuilt entire personal site via Telegram while watching Netflix — Notion → 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 JSearch API.
|
||||
</Card>
|
||||
|
||||
<Card title="Jira Skill Builder" icon="diagram-project" href="https://x.com/jdrhyne/status/2008336434827002232">
|
||||
**@jdrhyne** • `automation` `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** • `automation` `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 company Slack channel, responds helpfully, and forwards notifications to Telegram. Autonomously fixed a production bug in a deployed app without being asked.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
<h2 id="knowledge-memory">Knowledge & Memory</h2>
|
||||
|
||||
<p className="showcase-section-intro">
|
||||
Systems that index, search, remember, and reason over personal or team knowledge.
|
||||
</p>
|
||||
|
||||
<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 + OpenAI/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 → beliefs → evolving self model.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
<h2 id="voice-phone">Voice & Phone</h2>
|
||||
|
||||
<p className="showcase-section-intro">
|
||||
Speech-first entry points, phone bridges, and transcription-heavy workflows.
|
||||
</p>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="Clawdia Phone Bridge" icon="phone" href="https://github.com/alejandroOPI/clawdia-bridge">
|
||||
**@alejandroOPI** • `voice` `vapi` `bridge`
|
||||
|
||||
Vapi voice assistant ↔ OpenClaw HTTP bridge. Near real-time phone calls with your agent.
|
||||
</Card>
|
||||
|
||||
<Card title="OpenRouter Transcription" icon="microphone" href="https://clawhub.ai/obviyus/openrouter-transcribe">
|
||||
**@obviyus** • `transcription` `multilingual` `skill`
|
||||
|
||||
Multi-lingual audio transcription via OpenRouter (Gemini, etc). Available on ClawHub.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
<h2 id="infrastructure-deployment">Infrastructure & Deployment</h2>
|
||||
|
||||
<p className="showcase-section-intro">
|
||||
Packaging, deployment, and integrations that make OpenClaw easier to run and extend.
|
||||
</p>
|
||||
|
||||
<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/skills/homeassistant">
|
||||
**ClawHub** • `homeassistant` `skill` `automation`
|
||||
|
||||
Control and automate Home Assistant devices via natural language.
|
||||
</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/skills/caldav-calendar">
|
||||
**ClawHub** • `calendar` `caldav` `skill`
|
||||
|
||||
Calendar skill using khal/vdirsyncer. Self-hosted calendar integration.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
<h2 id="home-hardware">Home & Hardware</h2>
|
||||
|
||||
<p className="showcase-section-intro">
|
||||
The physical-world side of OpenClaw: homes, sensors, cameras, vacuums, and other devices.
|
||||
</p>
|
||||
|
||||
<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 beautiful 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>
|
||||
|
||||
<h2 id="community-projects">Community Projects</h2>
|
||||
|
||||
<p className="showcase-section-intro">
|
||||
Things that grew beyond a single workflow into broader products or ecosystems.
|
||||
</p>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="StarSwap Marketplace" icon="star" href="https://star-swap.com/">
|
||||
**Community** • `marketplace` `astronomy` `webapp`
|
||||
|
||||
Full astronomy gear marketplace. Built with/around the OpenClaw ecosystem.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
---
|
||||
|
||||
<h2 id="submit-your-project">Submit Your Project</h2>
|
||||
|
||||
<p className="showcase-section-intro">
|
||||
If you are building something interesting with OpenClaw, send it over. Strong screenshots and concrete outcomes help.
|
||||
</p>
|
||||
|
||||
Have something to share? We'd love to feature it!
|
||||
|
||||
<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/demo, share a screenshot if you have one
|
||||
</Step>
|
||||
<Step title="Get Featured">
|
||||
We'll add standout projects to this page
|
||||
</Step>
|
||||
</Steps>
|
||||
228
openclaw/docs/start/wizard-cli-automation.md
Normal file
228
openclaw/docs/start/wizard-cli-automation.md
Normal file
|
|
@ -0,0 +1,228 @@
|
|||
---
|
||||
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"
|
||||
---
|
||||
|
||||
# CLI Automation
|
||||
|
||||
Use `--non-interactive` to automate `openclaw onboard`.
|
||||
|
||||
<Note>
|
||||
`--json` does not imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
|
||||
</Note>
|
||||
|
||||
## Baseline non-interactive example
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice apiKey \
|
||||
--anthropic-api-key "$ANTHROPIC_API_KEY" \
|
||||
--secret-input-mode plaintext \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback \
|
||||
--install-daemon \
|
||||
--daemon-runtime node \
|
||||
--skip-skills
|
||||
```
|
||||
|
||||
Add `--json` for a machine-readable summary.
|
||||
|
||||
Use `--secret-input-mode ref` to store env-backed refs in auth profiles instead of plaintext values.
|
||||
Interactive selection between env refs and configured provider refs (`file` or `exec`) is available in the onboarding flow.
|
||||
|
||||
In non-interactive `ref` mode, provider env vars must be set in the process environment.
|
||||
Passing inline key flags without the matching env var now fails fast.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice openai-api-key \
|
||||
--secret-input-mode ref \
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
## Provider-specific examples
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Anthropic API key example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice apiKey \
|
||||
--anthropic-api-key "$ANTHROPIC_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Gemini example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice gemini-api-key \
|
||||
--gemini-api-key "$GEMINI_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Z.AI example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice zai-api-key \
|
||||
--zai-api-key "$ZAI_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Vercel AI Gateway example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice ai-gateway-api-key \
|
||||
--ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Cloudflare AI Gateway example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--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-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Moonshot example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice moonshot-api-key \
|
||||
--moonshot-api-key "$MOONSHOT_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Mistral example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice mistral-api-key \
|
||||
--mistral-api-key "$MISTRAL_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Synthetic example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice synthetic-api-key \
|
||||
--synthetic-api-key "$SYNTHETIC_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="OpenCode example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice opencode-zen \
|
||||
--opencode-zen-api-key "$OPENCODE_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
Swap to `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"` for the Go catalog.
|
||||
</Accordion>
|
||||
<Accordion title="Ollama example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice ollama \
|
||||
--custom-model-id "qwen3.5:27b" \
|
||||
--accept-risk \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Custom provider example">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--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 \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
`--custom-api-key` is optional. If omitted, onboarding checks `CUSTOM_API_KEY`.
|
||||
|
||||
Ref-mode variant:
|
||||
|
||||
```bash
|
||||
export CUSTOM_API_KEY="your-key"
|
||||
openclaw onboard --non-interactive \
|
||||
--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 \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
In this mode, onboarding stores `apiKey` as `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Anthropic setup-token remains available as a supported onboarding token path, but OpenClaw now prefers Claude CLI reuse when available.
|
||||
For production, prefer an Anthropic API key.
|
||||
|
||||
## Add another agent
|
||||
|
||||
Use `openclaw agents add <name>` to create a separate agent with its own workspace,
|
||||
sessions, and auth profiles. Running without `--workspace` launches the wizard.
|
||||
|
||||
```bash
|
||||
openclaw agents add work \
|
||||
--workspace ~/.openclaw/workspace-work \
|
||||
--model openai/gpt-5.4 \
|
||||
--bind whatsapp:biz \
|
||||
--non-interactive \
|
||||
--json
|
||||
```
|
||||
|
||||
What it sets:
|
||||
|
||||
- `agents.list[].name`
|
||||
- `agents.list[].workspace`
|
||||
- `agents.list[].agentDir`
|
||||
|
||||
Notes:
|
||||
|
||||
- Default workspaces follow `~/.openclaw/workspace-<agentId>`.
|
||||
- Add `bindings` to route inbound messages (the wizard can do this).
|
||||
- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
|
||||
|
||||
## Related docs
|
||||
|
||||
- Onboarding hub: [Onboarding (CLI)](/start/wizard)
|
||||
- Full reference: [CLI Setup Reference](/start/wizard-cli-reference)
|
||||
- Command reference: [`openclaw onboard`](/cli/onboard)
|
||||
313
openclaw/docs/start/wizard-cli-reference.md
Normal file
313
openclaw/docs/start/wizard-cli-reference.md
Normal file
|
|
@ -0,0 +1,313 @@
|
|||
---
|
||||
summary: "Complete reference for CLI setup flow, auth/model setup, outputs, and internals"
|
||||
read_when:
|
||||
- You need detailed behavior for openclaw onboard
|
||||
- You are debugging onboarding results or integrating onboarding clients
|
||||
title: "CLI Setup Reference"
|
||||
sidebarTitle: "CLI reference"
|
||||
---
|
||||
|
||||
# CLI Setup Reference
|
||||
|
||||
This page is the full reference for `openclaw onboard`.
|
||||
For the short guide, see [Onboarding (CLI)](/start/wizard).
|
||||
|
||||
## What the wizard does
|
||||
|
||||
Local mode (default) walks you through:
|
||||
|
||||
- Model and auth setup (OpenAI Code subscription OAuth, Anthropic Claude CLI or API key, plus MiniMax, GLM, Ollama, Moonshot, StepFun, and AI Gateway options)
|
||||
- Workspace location and bootstrap files
|
||||
- Gateway settings (port, bind, auth, tailscale)
|
||||
- Channels and providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles, and other bundled channel plugins)
|
||||
- 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, Modify, or Reset.
|
||||
- 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 workspace.
|
||||
- If config is invalid or contains legacy keys, the wizard stops and asks you to run `openclaw doctor` before continuing.
|
||||
- Reset uses `trash` and offers scopes:
|
||||
- Config only
|
||||
- Config + credentials + sessions
|
||||
- Full reset (also removes 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 ritual.
|
||||
- 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
|
||||
- [BlueBubbles](/channels/bluebubbles): recommended for iMessage; server URL + password + webhook
|
||||
- [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access
|
||||
- DM security: default is pairing. First DM sends a code; approve via
|
||||
`openclaw pairing approve <channel> <code>` or use allowlists.
|
||||
</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: Node (recommended; required for WhatsApp and Telegram). Bun is not recommended.
|
||||
</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 (some use Homebrew on macOS).
|
||||
</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.
|
||||
|
||||
<Info>
|
||||
Remote mode does not install or modify anything on the remote host.
|
||||
</Info>
|
||||
|
||||
What you set:
|
||||
|
||||
- Remote gateway URL (`ws://...`)
|
||||
- Token if remote gateway auth is required (recommended)
|
||||
|
||||
<Note>
|
||||
- If gateway is loopback-only, use SSH tunneling or a tailnet.
|
||||
- Discovery hints:
|
||||
- macOS: Bonjour (`dns-sd`)
|
||||
- Linux: Avahi (`avahi-browse`)
|
||||
</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="OpenAI Code subscription (Codex CLI reuse)">
|
||||
If `~/.codex/auth.json` exists, the wizard can reuse it.
|
||||
Reused Codex CLI credentials stay managed by Codex CLI; on expiry OpenClaw
|
||||
re-reads that source first and, when the provider can refresh it, writes
|
||||
the refreshed credential back to Codex storage instead of taking ownership
|
||||
itself.
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI Code subscription (OAuth)">
|
||||
Browser flow; paste `code#state`.
|
||||
|
||||
Sets `agents.defaults.model` to `openai-codex/gpt-5.4` when model is unset or `openai/*`.
|
||||
|
||||
</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.4` when model is unset, `openai/*`, or `openai-codex/*`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="xAI (Grok) API key">
|
||||
Prompts for `XAI_API_KEY` and configures xAI as a model provider.
|
||||
</Accordion>
|
||||
<Accordion title="OpenCode">
|
||||
Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`) and lets you choose the Zen or Go catalog.
|
||||
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-M2.7`; 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 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)
|
||||
|
||||
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|anthropic>` (optional; default `openai`)
|
||||
|
||||
</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.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 (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible)
|
||||
- `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`
|
||||
|
||||
`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>
|
||||
|
||||
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
|
||||
- Stores it under `~/.openclaw/tools/signal-cli/<version>/`
|
||||
- Writes `channels.signal.cliPath` in config
|
||||
- JVM builds require Java 21
|
||||
- Native builds are used when available
|
||||
- Windows uses WSL2 and follows Linux signal-cli flow inside WSL
|
||||
|
||||
## Related docs
|
||||
|
||||
- Onboarding hub: [Onboarding (CLI)](/start/wizard)
|
||||
- Automation and scripts: [CLI Automation](/start/wizard-cli-automation)
|
||||
- Command reference: [`openclaw onboard`](/cli/onboard)
|
||||
127
openclaw/docs/start/wizard.md
Normal file
127
openclaw/docs/start/wizard.md
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
---
|
||||
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"
|
||||
---
|
||||
|
||||
# Onboarding (CLI)
|
||||
|
||||
CLI onboarding is the **recommended** way to set up OpenClaw on macOS,
|
||||
Linux, or Windows (via WSL2; strongly recommended).
|
||||
It configures a local Gateway or a remote Gateway connection, plus channels, skills,
|
||||
and workspace defaults in one guided flow.
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
<Info>
|
||||
Fastest first chat: open the Control UI (no channel setup needed). Run
|
||||
`openclaw dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).
|
||||
</Info>
|
||||
|
||||
To reconfigure later:
|
||||
|
||||
```bash
|
||||
openclaw configure
|
||||
openclaw agents add <name>
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--json` does not imply non-interactive mode. For scripts, use `--non-interactive`.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
CLI onboarding includes a web search step where you can pick a provider
|
||||
such as Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search,
|
||||
Ollama Web Search, Perplexity, SearXNG, or Tavily. Some providers require an
|
||||
API key, while others are key-free. You can also configure this later with
|
||||
`openclaw configure --section web`. Docs: [Web tools](/tools/web).
|
||||
</Tip>
|
||||
|
||||
## QuickStart vs Advanced
|
||||
|
||||
Onboarding starts with **QuickStart** (defaults) vs **Advanced** (full control).
|
||||
|
||||
<Tabs>
|
||||
<Tab title="QuickStart (defaults)">
|
||||
- Local gateway (loopback)
|
||||
- Workspace default (or existing workspace)
|
||||
- Gateway port **18789**
|
||||
- Gateway auth **Token** (auto‑generated, even on loopback)
|
||||
- Tool policy default for new local setups: `tools.profile: "coding"` (existing explicit profile is preserved)
|
||||
- DM isolation default: local onboarding writes `session.dmScope: "per-channel-peer"` when unset. Details: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals)
|
||||
- Tailscale exposure **Off**
|
||||
- Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)
|
||||
</Tab>
|
||||
<Tab title="Advanced (full control)">
|
||||
- Exposes every step (mode, workspace, gateway, channels, daemon, skills).
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## What onboarding configures
|
||||
|
||||
**Local mode (default)** walks you through these steps:
|
||||
|
||||
1. **Model/Auth** — choose any supported provider/auth flow (API key, OAuth, or provider-specific manual auth), including Custom Provider
|
||||
(OpenAI-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model.
|
||||
Security note: if this agent will run tools or process webhook/hooks content, prefer the strongest latest-generation model available and keep tool policy strict. Weaker/older tiers are easier to prompt-inject.
|
||||
For non-interactive runs, `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext API key values.
|
||||
In non-interactive `ref` mode, the provider env var must be set; passing inline key flags without that env var fails fast.
|
||||
In interactive runs, choosing secret reference mode lets you point at either an environment variable or a configured provider ref (`file` or `exec`), with a fast preflight validation before saving.
|
||||
For Anthropic, interactive onboarding/configure offers **Anthropic Claude CLI** as the preferred local path and **Anthropic API key** as the recommended production path. Anthropic setup-token also remains available as a supported token-auth path.
|
||||
2. **Workspace** — Location for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files.
|
||||
3. **Gateway** — Port, bind address, auth mode, Tailscale exposure.
|
||||
In interactive token mode, choose default plaintext token storage or opt into SecretRef.
|
||||
Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
|
||||
4. **Channels** — built-in and bundled chat channels such as BlueBubbles, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and more.
|
||||
5. **Daemon** — Installs a LaunchAgent (macOS), systemd user unit (Linux/WSL2), or native Windows Scheduled Task with per-user Startup-folder fallback.
|
||||
If token auth requires a token and `gateway.auth.token` is SecretRef-managed, daemon install validates it but does not persist the resolved token into supervisor service environment metadata.
|
||||
If token auth requires a token and the configured token SecretRef is unresolved, daemon install is blocked with actionable guidance.
|
||||
If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, daemon install is blocked until mode is set explicitly.
|
||||
6. **Health check** — Starts the Gateway and verifies it's running.
|
||||
7. **Skills** — Installs recommended skills and 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 include workspace.
|
||||
If the config is invalid or contains legacy keys, onboarding asks you to run `openclaw doctor` first.
|
||||
</Note>
|
||||
|
||||
**Remote mode** only configures the local client to connect to a Gateway elsewhere.
|
||||
It does **not** install or change anything on the remote host.
|
||||
|
||||
## Add another agent
|
||||
|
||||
Use `openclaw agents add <name>` to create a separate agent with its own workspace,
|
||||
sessions, and auth profiles. Running without `--workspace` launches onboarding.
|
||||
|
||||
What it sets:
|
||||
|
||||
- `agents.list[].name`
|
||||
- `agents.list[].workspace`
|
||||
- `agents.list[].agentDir`
|
||||
|
||||
Notes:
|
||||
|
||||
- Default workspaces follow `~/.openclaw/workspace-<agentId>`.
|
||||
- Add `bindings` to route inbound messages (onboarding can do this).
|
||||
- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
|
||||
|
||||
## Full reference
|
||||
|
||||
For detailed step-by-step breakdowns and config outputs, see
|
||||
[CLI Setup Reference](/start/wizard-cli-reference).
|
||||
For non-interactive examples, see [CLI Automation](/start/wizard-cli-automation).
|
||||
For the deeper technical reference, including RPC details, see
|
||||
[Onboarding Reference](/reference/wizard).
|
||||
|
||||
## 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)
|
||||
Loading…
Add table
Add a link
Reference in a new issue