diff --git a/docs/custom.css b/docs/custom.css deleted file mode 100644 index 0c88a45f7..000000000 --- a/docs/custom.css +++ /dev/null @@ -1,4 +0,0 @@ -#content-area h1:first-of-type, -.prose h1:first-of-type { - display: none !important; -} diff --git a/docs/docs.json b/docs/docs.json index d02a0673d..df6c2c100 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -334,6 +334,14 @@ "source": "/getting-started", "destination": "/start/getting-started" }, + { + "source": "/quickstart", + "destination": "/start/getting-started" + }, + { + "source": "/start/quickstart", + "destination": "/start/getting-started" + }, { "source": "/gmail-pubsub", "destination": "/automation/gmail-pubsub" @@ -732,43 +740,46 @@ "pages": ["index", "concepts/features", "start/showcase", "start/lore"] }, { - "group": "Installation", - "pages": [ - "install/index", - "install/installer", - "install/docker", - "install/bun", - "install/nix", - "install/ansible", - "install/development-channels", - "install/updating", - "install/uninstall" - ] - }, - { - "group": "Setup", + "group": "First run", "pages": [ "start/getting-started", - "start/quickstart", - "start/wizard", - "start/setup", - "start/onboarding", - "start/pairing", - "start/openclaw", - "start/hubs", - "start/docs-directory" + { + "group": "Onboarding", + "pages": ["start/wizard", "start/onboarding"] + }, + "start/pairing" ] }, { - "group": "Platforms", + "group": "Use cases", + "pages": ["start/openclaw"] + } + ] + }, + { + "tab": "Install", + "groups": [ + { + "group": "Install overview", + "pages": ["install/index", "install/installer"] + }, + { + "group": "Install methods", "pages": [ - "platforms/index", - "platforms/macos", - "platforms/linux", - "platforms/windows", - "platforms/android", - "platforms/ios" + "install/node", + "install/docker", + "install/nix", + "install/ansible", + "install/bun" ] + }, + { + "group": "Maintenance", + "pages": ["install/updating", "install/migrating", "install/uninstall"] + }, + { + "group": "Advanced", + "pages": ["install/development-channels"] } ] }, @@ -955,7 +966,7 @@ ] }, { - "tab": "Infrastructure", + "tab": "Gateway & Ops", "groups": [ { "group": "Gateway", @@ -1030,6 +1041,22 @@ { "group": "Web interfaces", "pages": ["web/index", "web/control-ui", "web/dashboard", "web/webchat", "tui"] + } + ] + }, + { + "tab": "Platforms", + "groups": [ + { + "group": "Platforms overview", + "pages": [ + "platforms/index", + "platforms/macos", + "platforms/linux", + "platforms/windows", + "platforms/android", + "platforms/ios" + ] }, { "group": "macOS companion app", @@ -1155,6 +1182,14 @@ "scripts", "reference/session-management-compaction" ] + }, + { + "group": "Developer workflows", + "pages": ["start/setup"] + }, + { + "group": "Docs meta", + "pages": ["start/hubs", "start/docs-directory"] } ] } @@ -1164,60 +1199,74 @@ "language": "zh-Hans", "tabs": [ { - "tab": "Get started", + "tab": "快速开始", "groups": [ { - "group": "Overview", - "pages": ["zh-CN/index", "zh-CN/start/showcase", "zh-CN/start/lore"] - }, - { - "group": "Installation", + "group": "概览", "pages": [ - "zh-CN/install/index", - "zh-CN/install/installer", - "zh-CN/install/docker", - "zh-CN/install/bun", - "zh-CN/install/nix", - "zh-CN/install/ansible", - "zh-CN/install/development-channels", - "zh-CN/install/updating", - "zh-CN/install/uninstall" + "zh-CN/index", + "zh-CN/concepts/features", + "zh-CN/start/showcase", + "zh-CN/start/lore" ] }, { - "group": "Setup", + "group": "首次运行", "pages": [ "zh-CN/start/getting-started", - "zh-CN/start/wizard", - "zh-CN/start/setup", - "zh-CN/start/onboarding", - "zh-CN/start/pairing", - "zh-CN/start/openclaw", - "zh-CN/start/hubs" + { + "group": "新手引导", + "pages": ["zh-CN/start/wizard", "zh-CN/start/onboarding"] + }, + "zh-CN/start/pairing" ] }, { - "group": "Platforms", - "pages": [ - "zh-CN/platforms/index", - "zh-CN/platforms/macos", - "zh-CN/platforms/linux", - "zh-CN/platforms/windows", - "zh-CN/platforms/android", - "zh-CN/platforms/ios" - ] + "group": "使用场景", + "pages": ["zh-CN/start/openclaw"] } ] }, { - "tab": "Channels", + "tab": "安装", "groups": [ { - "group": "Overview", + "group": "安装概览", + "pages": ["zh-CN/install/index", "zh-CN/install/installer"] + }, + { + "group": "安装方式", + "pages": [ + "zh-CN/install/node", + "zh-CN/install/docker", + "zh-CN/install/nix", + "zh-CN/install/ansible", + "zh-CN/install/bun" + ] + }, + { + "group": "维护", + "pages": [ + "zh-CN/install/updating", + "zh-CN/install/migrating", + "zh-CN/install/uninstall" + ] + }, + { + "group": "高级", + "pages": ["zh-CN/install/development-channels"] + } + ] + }, + { + "tab": "消息渠道", + "groups": [ + { + "group": "概览", "pages": ["zh-CN/channels/index"] }, { - "group": "Messaging platforms", + "group": "消息平台", "pages": [ "zh-CN/channels/whatsapp", "zh-CN/channels/telegram", @@ -1237,7 +1286,7 @@ ] }, { - "group": "Configuration", + "group": "配置", "pages": [ "zh-CN/concepts/group-messages", "zh-CN/concepts/groups", @@ -1250,10 +1299,10 @@ ] }, { - "tab": "Agents", + "tab": "代理", "groups": [ { - "group": "Fundamentals", + "group": "基础", "pages": [ "zh-CN/concepts/architecture", "zh-CN/concepts/agent", @@ -1265,7 +1314,7 @@ ] }, { - "group": "Sessions and memory", + "group": "会话与记忆", "pages": [ "zh-CN/concepts/session", "zh-CN/concepts/sessions", @@ -1276,11 +1325,11 @@ ] }, { - "group": "Multi-agent", + "group": "多代理", "pages": ["zh-CN/concepts/multi-agent", "zh-CN/concepts/presence"] }, { - "group": "Messages and delivery", + "group": "消息与投递", "pages": [ "zh-CN/concepts/messages", "zh-CN/concepts/streaming", @@ -1291,14 +1340,14 @@ ] }, { - "tab": "Tools", + "tab": "工具", "groups": [ { - "group": "Overview", + "group": "概览", "pages": ["zh-CN/tools/index"] }, { - "group": "Built-in tools", + "group": "内置工具", "pages": [ "zh-CN/tools/lobster", "zh-CN/tools/llm-task", @@ -1311,7 +1360,7 @@ ] }, { - "group": "Browser", + "group": "浏览器", "pages": [ "zh-CN/tools/browser", "zh-CN/tools/browser-login", @@ -1320,7 +1369,7 @@ ] }, { - "group": "Agent coordination", + "group": "代理协作", "pages": [ "zh-CN/tools/agent-send", "zh-CN/tools/subagents", @@ -1328,7 +1377,7 @@ ] }, { - "group": "Skills and extensions", + "group": "技能与扩展", "pages": [ "zh-CN/tools/slash-commands", "zh-CN/tools/skills", @@ -1340,7 +1389,7 @@ ] }, { - "group": "Automation", + "group": "自动化", "pages": [ "zh-CN/hooks", "zh-CN/hooks/soul-evil", @@ -1353,7 +1402,7 @@ ] }, { - "group": "Media and devices", + "group": "媒体与设备", "pages": [ "zh-CN/nodes/index", "zh-CN/nodes/images", @@ -1367,10 +1416,10 @@ ] }, { - "tab": "Models", + "tab": "模型", "groups": [ { - "group": "Overview", + "group": "概览", "pages": [ "zh-CN/providers/index", "zh-CN/providers/models", @@ -1378,11 +1427,11 @@ ] }, { - "group": "Configuration", + "group": "配置", "pages": ["zh-CN/concepts/model-providers", "zh-CN/concepts/model-failover"] }, { - "group": "Providers", + "group": "提供商", "pages": [ "zh-CN/providers/anthropic", "zh-CN/providers/openai", @@ -1400,14 +1449,14 @@ ] }, { - "tab": "Infrastructure", + "tab": "网关与运维", "groups": [ { - "group": "Gateway", + "group": "网关", "pages": [ "zh-CN/gateway/index", { - "group": "Configuration and operations", + "group": "配置与运维", "pages": [ "zh-CN/gateway/configuration", "zh-CN/gateway/configuration-examples", @@ -1423,7 +1472,7 @@ ] }, { - "group": "Security and sandboxing", + "group": "安全与沙箱", "pages": [ "zh-CN/gateway/security/index", "zh-CN/gateway/sandboxing", @@ -1431,7 +1480,7 @@ ] }, { - "group": "Protocols and APIs", + "group": "协议与 API", "pages": [ "zh-CN/gateway/protocol", "zh-CN/gateway/bridge-protocol", @@ -1442,8 +1491,9 @@ ] }, { - "group": "Networking and discovery", + "group": "网络与发现", "pages": [ + "zh-CN/gateway/network-model", "zh-CN/gateway/pairing", "zh-CN/gateway/discovery", "zh-CN/gateway/bonjour" @@ -1452,7 +1502,7 @@ ] }, { - "group": "Remote access and deployment", + "group": "远程访问与部署", "pages": [ "zh-CN/gateway/remote", "zh-CN/gateway/remote-gateway-readme", @@ -1468,11 +1518,11 @@ ] }, { - "group": "Security", + "group": "安全", "pages": ["zh-CN/security/formal-verification"] }, { - "group": "Web interfaces", + "group": "Web 界面", "pages": [ "zh-CN/web/index", "zh-CN/web/control-ui", @@ -1480,9 +1530,25 @@ "zh-CN/web/webchat", "zh-CN/tui" ] + } + ] + }, + { + "tab": "平台", + "groups": [ + { + "group": "平台概览", + "pages": [ + "zh-CN/platforms/index", + "zh-CN/platforms/macos", + "zh-CN/platforms/linux", + "zh-CN/platforms/windows", + "zh-CN/platforms/android", + "zh-CN/platforms/ios" + ] }, { - "group": "macOS companion app", + "group": "macOS 配套应用", "pages": [ "zh-CN/platforms/mac/dev-setup", "zh-CN/platforms/mac/menu-bar", @@ -1507,10 +1573,10 @@ ] }, { - "tab": "Reference", + "tab": "参考", "groups": [ { - "group": "CLI commands", + "group": "CLI 命令", "pages": [ "zh-CN/cli/index", "zh-CN/cli/agent", @@ -1551,11 +1617,11 @@ ] }, { - "group": "RPC and API", + "group": "RPC 与 API", "pages": ["zh-CN/reference/rpc", "zh-CN/reference/device-models"] }, { - "group": "Templates", + "group": "模板", "pages": [ "zh-CN/reference/AGENTS.default", "zh-CN/reference/templates/AGENTS", @@ -1569,7 +1635,7 @@ ] }, { - "group": "Technical reference", + "group": "技术参考", "pages": [ "zh-CN/concepts/typebox", "zh-CN/concepts/markdown-formatting", @@ -1580,20 +1646,24 @@ ] }, { - "group": "Release notes", + "group": "项目", + "pages": ["zh-CN/reference/credits"] + }, + { + "group": "发布说明", "pages": ["zh-CN/reference/RELEASING", "zh-CN/reference/test"] } ] }, { - "tab": "Help", + "tab": "帮助", "groups": [ { - "group": "Help", + "group": "帮助", "pages": ["zh-CN/help/index", "zh-CN/help/troubleshooting", "zh-CN/help/faq"] }, { - "group": "Environment and debugging", + "group": "环境与调试", "pages": [ "zh-CN/environment", "zh-CN/debugging", @@ -1601,6 +1671,14 @@ "zh-CN/scripts", "zh-CN/reference/session-management-compaction" ] + }, + { + "group": "开发者工作流", + "pages": ["zh-CN/start/setup"] + }, + { + "group": "文档元信息", + "pages": ["zh-CN/start/hubs", "zh-CN/start/docs-directory"] } ] } diff --git a/docs/install/index.md b/docs/install/index.md index 4ee9f12cd..a3637d4c5 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -102,6 +102,8 @@ openclaw onboard --install-daemon Tip: if you don’t have a global install yet, run repo commands via `pnpm openclaw ...`. +For deeper development workflows, see [Setup](/start/setup). + ### 4) Other install options - Docker: [Docker](/install/docker) diff --git a/docs/start/docs-directory.md b/docs/start/docs-directory.md index c429a7354..683b5c7dd 100644 --- a/docs/start/docs-directory.md +++ b/docs/start/docs-directory.md @@ -6,6 +6,7 @@ title: "Docs directory" --- +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). diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md index 109862b68..6c38b6e28 100644 --- a/docs/start/getting-started.md +++ b/docs/start/getting-started.md @@ -1,208 +1,120 @@ --- -summary: "Beginner guide: from zero to first message (wizard, auth, channels, pairing)" +summary: "Get OpenClaw installed and run your first chat in minutes." read_when: - First time setup from zero - - You want the fastest path from install → onboarding → first message + - You want the fastest path to a working chat title: "Getting Started" --- # Getting Started -Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible. +Goal: go from zero to a first working chat with minimal setup. + Fastest chat: open the Control UI (no channel setup needed). Run `openclaw dashboard` -and chat in the browser, or open `http://127.0.0.1:18789/` on the gateway host. +and chat in the browser, or open `http://127.0.0.1:18789/` on the +gateway host. Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui). + -Recommended path: use the **CLI onboarding wizard** (`openclaw onboard`). It sets up: +## Prereqs -- model/auth (OAuth recommended) -- gateway settings -- channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/...) -- pairing defaults (secure DMs) -- workspace bootstrap + skills -- optional background service +- Node 22 or newer -If you want the deeper reference pages, jump to: [Wizard](/start/wizard), [Setup](/start/setup), [Pairing](/start/pairing), [Security](/gateway/security). + +Check your Node version with `node --version` if you are unsure. + -Sandboxing note: `agents.defaults.sandbox.mode: "non-main"` uses `session.mainKey` (default `"main"`), -so group/channel sessions are sandboxed. If you want the main agent to always -run on host, set an explicit per-agent override: +## Quick setup (CLI) -```json -{ - "routing": { - "agents": { - "main": { - "workspace": "~/.openclaw/workspace", - "sandbox": { "mode": "off" } - } - } - } -} -``` + + + + + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash + ``` + + + ```powershell + iwr -useb https://openclaw.ai/install.ps1 | iex + ``` + + -## 0) Prereqs + + Other install methods and requirements: [Install](/install). + -- Node `>=22` -- `pnpm` (optional; recommended if you build from source) -- **Recommended:** Brave Search API key for web search. Easiest path: - `openclaw configure --section web` (stores `tools.web.search.apiKey`). - See [Web tools](/tools/web). + + + ```bash + openclaw onboard --install-daemon + ``` -macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough. -Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested, more problematic, and has poorer tool compatibility. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/platforms/windows). + The wizard configures auth, gateway settings, and optional channels. + See [Onboarding Wizard](/start/wizard) for details. -## 1) Install the CLI (recommended) + + + If you installed the service, it should already be running: -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -``` + ```bash + openclaw gateway status + ``` -Installer options (install method, non-interactive, from GitHub): [Install](/install). + + + ```bash + openclaw dashboard + ``` + + -Windows (PowerShell): + +If the Control UI loads, your Gateway is ready for use. + -```powershell -iwr -useb https://openclaw.ai/install.ps1 | iex -``` +## Optional checks and extras -Alternative (global install): + + + Useful for quick tests or troubleshooting. -```bash -npm install -g openclaw@latest -``` + ```bash + openclaw gateway --port 18789 + ``` -```bash -pnpm add -g openclaw@latest -``` + + + Requires a configured channel. -## 2) Run the onboarding wizard (and install the service) + ```bash + openclaw message send --target +15555550123 --message "Hello from OpenClaw" + ``` -```bash -openclaw onboard --install-daemon -``` + + -What you’ll choose: +## Go deeper -- **Local vs Remote** gateway -- **Auth**: OpenAI Code (Codex) subscription (OAuth) or API keys. For Anthropic we recommend an API key; `claude setup-token` is also supported. -- **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, Mattermost plugin tokens, etc. -- **Daemon**: background install (launchd/systemd; WSL2 uses systemd) - - **Runtime**: Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**. -- **Gateway token**: the wizard generates one by default (even on loopback) and stores it in `gateway.auth.token`. + + + Full CLI wizard reference and advanced options. + + + First run flow for the macOS app. + + -Wizard doc: [Wizard](/start/wizard) +## What you will have -### Auth: where it lives (important) +- A running Gateway +- Auth configured +- Control UI access or a connected channel -- **Recommended Anthropic path:** set an API key (wizard can store it for service use). `claude setup-token` is also supported if you want to reuse Claude Code credentials. +## Next steps -- OAuth credentials (legacy import): `~/.openclaw/credentials/oauth.json` -- Auth profiles (OAuth + API keys): `~/.openclaw/agents//agent/auth-profiles.json` - -Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host. - -## 3) Start the Gateway - -If you installed the service during onboarding, the Gateway should already be running: - -```bash -openclaw gateway status -``` - -Manual run (foreground): - -```bash -openclaw gateway --port 18789 --verbose -``` - -Dashboard (local loopback): `http://127.0.0.1:18789/` -If a token is configured, paste it into the Control UI settings (stored as `connect.params.auth.token`). - -⚠️ **Bun warning (WhatsApp + Telegram):** Bun has known issues with these -channels. If you use WhatsApp or Telegram, run the Gateway with **Node**. - -## 3.5) Quick verify (2 min) - -```bash -openclaw status -openclaw health -openclaw security audit --deep -``` - -## 4) Pair + connect your first chat surface - -### WhatsApp (QR login) - -```bash -openclaw channels login -``` - -Scan via WhatsApp → Settings → Linked Devices. - -WhatsApp doc: [WhatsApp](/channels/whatsapp) - -### Telegram / Discord / others - -The wizard can write tokens/config for you. If you prefer manual config, start with: - -- Telegram: [Telegram](/channels/telegram) -- Discord: [Discord](/channels/discord) -- Mattermost (plugin): [Mattermost](/channels/mattermost) - -**Telegram DM tip:** your first DM returns a pairing code. Approve it (see next step) or the bot won’t respond. - -## 5) DM safety (pairing approvals) - -Default posture: unknown DMs get a short code and messages are not processed until approved. -If your first DM gets no reply, approve the pairing: - -```bash -openclaw pairing list whatsapp -openclaw pairing approve whatsapp -``` - -Pairing doc: [Pairing](/start/pairing) - -## From source (development) - -If you’re hacking on OpenClaw itself, run from source: - -```bash -git clone https://github.com/openclaw/openclaw.git -cd openclaw -pnpm install -pnpm ui:build # auto-installs UI deps on first run -pnpm build -openclaw onboard --install-daemon -``` - -If you don’t have a global install yet, run the onboarding step via `pnpm openclaw ...` from the repo. -`pnpm build` also bundles A2UI assets; if you need to run just that step, use `pnpm canvas:a2ui:bundle`. - -Gateway (from this repo): - -```bash -node openclaw.mjs gateway --port 18789 --verbose -``` - -## 7) Verify end-to-end - -In a new terminal, send a test message: - -```bash -openclaw message send --target +15555550123 --message "Hello from OpenClaw" -``` - -If `openclaw health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it. - -Tip: `openclaw status --all` is the best pasteable, read-only debug report. -Health probes: `openclaw health` (or `openclaw status --deep`) asks the running gateway for a health snapshot. - -## Next steps (optional, but great) - -- macOS menu bar app + voice wake: [macOS app](/platforms/macos) -- iOS/Android nodes (Canvas/camera/voice): [Nodes](/nodes) -- Remote access (SSH tunnel / Tailscale Serve): [Remote access](/gateway/remote) and [Tailscale](/gateway/tailscale) -- Always-on / VPN setups: [Remote access](/gateway/remote), [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [macOS remote](/platforms/mac/remote) +- DM safety and approvals: [Pairing](/start/pairing) +- Connect more channels: [Channels](/channels) +- Advanced workflows and from source: [Setup](/start/setup) diff --git a/docs/start/hubs.md b/docs/start/hubs.md index e2c54eaa9..739b53fb9 100644 --- a/docs/start/hubs.md +++ b/docs/start/hubs.md @@ -7,13 +7,16 @@ title: "Docs Hubs" # Docs hubs + +If you are new to OpenClaw, start with [Getting Started](/start/getting-started). + + 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) -- [Quick start](/start/quickstart) - [Onboarding](/start/onboarding) - [Wizard](/start/wizard) - [Setup](/start/setup) diff --git a/docs/start/onboarding.md b/docs/start/onboarding.md index a76cb43bd..95b9ffee4 100644 --- a/docs/start/onboarding.md +++ b/docs/start/onboarding.md @@ -3,10 +3,11 @@ summary: "First-run onboarding flow for OpenClaw (macOS app)" read_when: - Designing the macOS onboarding assistant - Implementing auth or identity setup -title: "Onboarding" +title: "Onboarding (macOS App)" +sidebarTitle: "macOS app" --- -# Onboarding (macOS app) +# Onboarding (macOS App) This doc describes the **current** first‑run onboarding flow. The goal is a smooth “day 0” experience: pick where the Gateway runs, connect auth, run the diff --git a/docs/start/quickstart.md b/docs/start/quickstart.md index 3df3de9e5..238af2881 100644 --- a/docs/start/quickstart.md +++ b/docs/start/quickstart.md @@ -1,81 +1,22 @@ --- -summary: "Install OpenClaw, onboard the Gateway, and pair your first channel." +summary: "Quick start has moved to Getting Started." read_when: - - You want the fastest path from install to a working Gateway + - You are looking for the fastest setup steps + - You were sent here from an older link title: "Quick start" --- - -OpenClaw requires Node 22 or newer. - - -## Install - - - - ```bash - npm install -g openclaw@latest - ``` - - - ```bash - pnpm add -g openclaw@latest - ``` - - - -## Onboard and run the Gateway - - - - ```bash - openclaw onboard --install-daemon - ``` - - - ```bash - openclaw channels login - ``` - - - ```bash - openclaw gateway --port 18789 - ``` - - - -After onboarding, the Gateway runs via the user service. You can still run it manually with `openclaw gateway`. +# Quick start -Switching between npm and git installs later is easy. Install the other flavor and run -`openclaw doctor` to update the gateway service entrypoint. +Quick start is now part of [Getting Started](/start/getting-started). -## From source (development) - -```bash -git clone https://github.com/openclaw/openclaw.git -cd openclaw -pnpm install -pnpm ui:build # auto-installs UI deps on first run -pnpm build -openclaw onboard --install-daemon -``` - -If you do not have a global install yet, run onboarding via `pnpm openclaw ...` from the repo. - -## Multi instance quickstart (optional) - -```bash -OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ -OPENCLAW_STATE_DIR=~/.openclaw-a \ -openclaw gateway --port 19001 -``` - -## Send a test message - -Requires a running Gateway. - -```bash -openclaw message send --target +15555550123 --message "Hello from OpenClaw" -``` + + + Install OpenClaw and run your first chat in minutes. + + + Full CLI wizard reference and advanced options. + + diff --git a/docs/start/setup.md b/docs/start/setup.md index f8067a902..ee50e02af 100644 --- a/docs/start/setup.md +++ b/docs/start/setup.md @@ -1,5 +1,5 @@ --- -summary: "Setup guide: keep your OpenClaw setup tailored while staying up-to-date" +summary: "Advanced setup and development workflows for OpenClaw" read_when: - Setting up a new machine - You want “latest + greatest” without breaking your personal setup @@ -8,6 +8,11 @@ title: "Setup" # Setup + +If you are setting up for the first time, start with [Getting Started](/start/getting-started). +For wizard details, see [Onboarding Wizard](/start/wizard). + + Last updated: 2026-01-01 ## TL;DR @@ -43,6 +48,14 @@ openclaw setup If you don’t have a global install yet, run it via `pnpm openclaw setup`. +## 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). diff --git a/docs/start/wizard.md b/docs/start/wizard.md index 1269344fe..d751e2d70 100644 --- a/docs/start/wizard.md +++ b/docs/start/wizard.md @@ -3,7 +3,8 @@ summary: "CLI onboarding wizard: guided setup for gateway, workspace, channels, read_when: - Running or configuring the onboarding wizard - Setting up a new machine -title: "Onboarding Wizard" +title: "Onboarding Wizard (CLI)" +sidebarTitle: "Wizard (CLI)" --- # Onboarding Wizard (CLI) @@ -19,8 +20,10 @@ Primary entrypoint: openclaw onboard ``` + Fastest first chat: open the Control UI (no channel setup needed). Run `openclaw dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard). + Follow‑up reconfiguration: @@ -28,24 +31,29 @@ Follow‑up reconfiguration: openclaw configure ``` + Recommended: set up a Brave Search API key so the agent can use `web_search` (`web_fetch` works without a key). Easiest path: `openclaw configure --section web` which stores `tools.web.search.apiKey`. Docs: [Web tools](/tools/web). + ## QuickStart vs Advanced The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control). -**QuickStart** keeps the defaults: - -- Local gateway (loopback) -- Workspace default (or existing workspace) -- Gateway port **18789** -- Gateway auth **Token** (auto‑generated, even on loopback) -- Tailscale exposure **Off** -- Telegram + WhatsApp DMs default to **allowlist** (you’ll be prompted for your phone number) - -**Advanced** exposes every step (mode, workspace, gateway, channels, daemon, skills). + + + - Local gateway (loopback) + - Workspace default (or existing workspace) + - Gateway port **18789** + - Gateway auth **Token** (auto‑generated, even on loopback) + - Tailscale exposure **Off** + - Telegram + WhatsApp DMs default to **allowlist** (you’ll be prompted for your phone number) + + + - Exposes every step (mode, workspace, gateway, channels, daemon, skills). + + ## What the wizard does @@ -68,110 +76,124 @@ To add more isolated agents (separate workspace + sessions + auth), use: openclaw agents add ``` -Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts. + +`--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts. + ## Flow details (local) -1. **Existing config detection** - - If `~/.openclaw/openclaw.json` exists, choose **Keep / Modify / Reset**. - - Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset** - (or pass `--reset`). - - If the config is invalid or contains legacy keys, the wizard stops and asks - you to run `openclaw doctor` before continuing. - - Reset uses `trash` (never `rm`) and offers scopes: - - Config only - - Config + credentials + sessions - - Full reset (also removes workspace) + + + - If `~/.openclaw/openclaw.json` exists, choose **Keep / Modify / Reset**. + - Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset** + (or pass `--reset`). + - If the config is invalid or contains legacy keys, the wizard stops and asks + you to run `openclaw doctor` before continuing. + - Reset uses `trash` (never `rm`) and offers scopes: + - Config only + - Config + credentials + sessions + - Full reset (also removes workspace) + + + - **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use. + - **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present. + - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default). + - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it. + - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`. + - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`. + - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.openclaw/.env` so launchd can read it. + - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth). + - **API key**: stores the key for you. + - **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`. + - More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway) + - **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`. + - More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway) + - **MiniMax M2.1**: config is auto-written. + - More detail: [MiniMax](/providers/minimax) + - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`. + - More detail: [Synthetic](/providers/synthetic) + - **Moonshot (Kimi K2)**: config is auto-written. + - **Kimi Coding**: config is auto-written. + - More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot) + - **Skip**: no auth configured yet. + - Pick a default model from detected options (or enter provider/model manually). + - Wizard runs a model check and warns if the configured model is unknown or missing auth. + - OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents//agent/auth-profiles.json` (API keys + OAuth). + - More detail: [/concepts/oauth](/concepts/oauth) + + Headless/server tip: complete OAuth on a machine with a browser, then copy + `~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`) to the + gateway host. + + + + - Default `~/.openclaw/workspace` (configurable). + - Seeds the workspace files needed for the agent bootstrap ritual. + - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace) + + + - Port, bind, auth mode, tailscale exposure. + - Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate. + - Disable auth only if you fully trust every local process. + - Non‑loopback binds still require auth. + + + - [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) (plugin): 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 ` or use allowlists. + + + - macOS: LaunchAgent + - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped). + - Linux (and Windows via WSL2): systemd user unit + - Wizard attempts to enable lingering via `loginctl enable-linger ` so the Gateway stays up after logout. + - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first. + - **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**. + + + - Starts the Gateway (if needed) and runs `openclaw health`. + - Tip: `openclaw status --deep` adds gateway health probes to status output (requires a reachable gateway). + + + - Reads the available skills and checks requirements. + - Lets you choose a node manager: **npm / pnpm** (bun not recommended). + - Installs optional dependencies (some use Homebrew on macOS). + + + - Summary + next steps, including iOS/Android/macOS apps for extra features. + + -2. **Model/Auth** - - **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use. - - **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present. - - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default). - - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it. - - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`. - - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`. - - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.openclaw/.env` so launchd can read it. - - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth). - - **API key**: stores the key for you. - - **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`. - - More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway) - - **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`. - - More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway) - - **MiniMax M2.1**: config is auto-written. - - More detail: [MiniMax](/providers/minimax) - - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`. - - More detail: [Synthetic](/providers/synthetic) - - **Moonshot (Kimi K2)**: config is auto-written. - - **Kimi Coding**: config is auto-written. - - More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot) - - **Skip**: no auth configured yet. - - Pick a default model from detected options (or enter provider/model manually). - - Wizard runs a model check and warns if the configured model is unknown or missing auth. - -- OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents//agent/auth-profiles.json` (API keys + OAuth). -- More detail: [/concepts/oauth](/concepts/oauth) - -3. **Workspace** - - Default `~/.openclaw/workspace` (configurable). - - Seeds the workspace files needed for the agent bootstrap ritual. - - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace) - -4. **Gateway** - - Port, bind, auth mode, tailscale exposure. - - Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate. - - Disable auth only if you fully trust every local process. - - Non‑loopback binds still require auth. - -5. **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) (plugin): 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 ` or use allowlists. - -6. **Daemon install** - - macOS: LaunchAgent - - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped). - - Linux (and Windows via WSL2): systemd user unit - - Wizard attempts to enable lingering via `loginctl enable-linger ` so the Gateway stays up after logout. - - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first. - - **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**. - -7. **Health check** - - Starts the Gateway (if needed) and runs `openclaw health`. - - Tip: `openclaw status --deep` adds gateway health probes to status output (requires a reachable gateway). - -8. **Skills (recommended)** - - Reads the available skills and checks requirements. - - Lets you choose a node manager: **npm / pnpm** (bun not recommended). - - Installs optional dependencies (some use Homebrew on macOS). - -9. **Finish** - - Summary + next steps, including iOS/Android/macOS apps for extra features. - -- If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser. -- If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps). + +If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser. +If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps). + ## Remote mode Remote mode configures a local client to connect to a Gateway elsewhere. + +Remote mode does **not** install or change anything on the remote host. + + What you’ll set: - Remote Gateway URL (`ws://...`) - Token if the remote Gateway requires auth (recommended) -Notes: - -- No remote installs or daemon changes are performed. + - If the Gateway is loopback‑only, use SSH tunneling or a tailnet. - Discovery hints: - macOS: Bonjour (`dns-sd`) - Linux: Avahi (`avahi-browse`) + ## Add another agent @@ -208,84 +230,80 @@ openclaw onboard --non-interactive \ Add `--json` for a machine‑readable summary. -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 -``` - -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 -``` - -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 -``` - -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 -``` - -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 -``` - -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 -``` - -OpenCode Zen 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 -``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice gemini-api-key \ + --gemini-api-key "$GEMINI_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice zai-api-key \ + --zai-api-key "$ZAI_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```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 + ``` + + + ```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 + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice moonshot-api-key \ + --moonshot-api-key "$MOONSHOT_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice synthetic-api-key \ + --synthetic-api-key "$SYNTHETIC_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice opencode-zen \ + --opencode-zen-api-key "$OPENCODE_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + Add agent (non‑interactive) example: diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 000000000..78d94ecb2 --- /dev/null +++ b/docs/style.css @@ -0,0 +1,3 @@ +#content > h1:first-of-type { + display: none !important; +}