OpenClaw 从安装到入门的完全指南（2026-02-04）

┌─────────────────────────────────────────────────────────────┐ │ 你的聊天应用 │ │ (Telegram / WhatsApp / Discord / Signal / WebChat) │ └────────────────────┬──────────────────────────────────────┘ │ 消息流入/流出 ▼ ┌─────────────────────────────────────────────────────────────┐ │ Gateway (守护进程) │ │ • 管理所有 Channels（Telegram、WhatsApp 等） │ │ • 暴露 WebSocket API (默认 127.0.0.1:18789) │ │ • 处理配对（pairing）、认证、事件分发 │ │ • 一个 Gateway 控制一台机器上的所有会话 │ └────────────────────┬──────────────────────────────────────┘ │ RPC 调用 ▼ ┌─────────────────────────────────────────────────────────────┐ │ Agent Runtime (智能体运行时) │ │ • 维护会话（Session）与上下文（Context） │ │ • 执行 Agent Loop：接收消息 → 调用模型 → 执行工具 → 返回 │ │ • 管理持久记忆（Memory） │ │ • 可配置多个 Agent（不同 workspace、不同模型） │ └────────────────────┬──────────────────────────────────────┘ │ 工具调用 ┌─────────────┼─────────────┬─────────────┐ ▼ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Browser │ │ Exec │ │ Web │ │ Skills │ │ (浏览器) │ │ (终端命令) │ │ (网页搜索) │ │ (插件) │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ └─────────────┴─────────────┴─────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Model Provider │ │ (Anthropic / OpenAI / Moonshot / 本地模型) │ └─────────────────────────────────────────────────────────────┘

wsl --install # 或者指定发行版： wsl --list --online wsl --install -d Ubuntu-24.04

sudo tee /etc/wsl.conf >/dev/null <<'EOF' [boot] systemd=true EOF

wsl --shutdown

systemctl --user status

node -v npm -v

v22.0.0 # 或更高版本 10.0.0 # npm 版本

curl -fsSL https://openclaw.ai/install.sh | bash

🦞 OpenClaw Installer ───────────────────────────────────── Detected platform: linux (WSL2) Node version: v22.1.0 ✓ Installing openclaw@latest... ✓ Installed successfully Next step: Run 'openclaw onboard --install-daemon'

iwr -useb https://openclaw.ai/install.ps1 | iex

npm install -g openclaw@latest

pnpm add -g openclaw@latest pnpm approve-builds -g

openclaw onboard --install-daemon openclaw doctor openclaw dashboard

git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm ui:build pnpm build openclaw onboard --install-daemon

openclaw onboard --install-daemon

🦞 OpenClaw Onboarding Wizard ───────────────────────────────────── Welcome! This wizard will help you set up OpenClaw. Mode selection: [1] QuickStart (recommended for first-time users) [2] Advanced (full control over every setting) Choose mode [1]:

Found existing config at ~/.openclaw/openclaw.json What would you like to do? [1] Keep existing config [2] Modify existing config [3] Reset (start fresh) Choose [1-3] [1]:

Gateway mode: [1] Local (run Gateway on this machine) [2] Remote (connect to Gateway elsewhere) Choose [1-2] [1]:

✓ Selected: Local mode Gateway will run on this machine Default port: 18789 Default bind: 127.0.0.1 (loopback)

Checking for existing API keys... ✓ Found ANTHROPIC_API_KEY in environment ✓ Found OPENAI_API_KEY in environment ✗ No MOONSHOT_API_KEY found Authentication method: [1] Anthropic API Key (recommended) [2] Anthropic OAuth (Claude Code CLI) [3] Anthropic setup-token (paste) [4] OpenAI Code (Codex) subscription [5] OpenAI API Key [6] Moonshot (Kimi K2) [7] MiniMax M2.1 [8] OpenCode Zen [9] Vercel AI Gateway [10] Synthetic [11] Skip (configure later) Choose [1-11] [1]:

✓ Using ANTHROPIC_API_KEY from environment Key: sk-ant-...* (masked) Default model selection: Detected providers: anthropic Available models: [1] anthropic/claude-3.5-sonnet- [2] anthropic/claude-3-opus- [3] anthropic/claude-3.5-haiku- Choose default model [1]:

Workspace location: Default: ~/.openclaw/workspace [1] Use default [2] Custom path Choose [1-2] [1]:

✓ Workspace: ~/.openclaw/workspace Creating bootstrap files... ✓ Created BOOT.md ✓ Created IDENTITY.md ✓ Created SOUL.md ✓ Created TOOLS.md

Gateway settings: Port: 18789 Bind: 127.0.0.1 (loopback) Auth: Token (auto-generated) [1] Keep defaults [2] Customize Choose [1-2] [1]:

Enter port [18789]: Enter bind address [127.0.0.1]: [1] 127.0.0.1 (loopback, localhost only) [2] 0.0.0.0 (all interfaces, LAN access) [3] Custom IP Choose [1-3] [1]:

✓ Gateway configured Port: 18789 Bind: 127.0.0.1 Auth token: oc_gw_...* (saved to config) Dashboard: http://127.0.0.1:18789/

Channel setup: [1] Telegram [2] WhatsApp [3] Discord [4] Google Chat [5] Signal [6] Skip (configure later) Choose channels (comma-separated, e.g., 1,3) [1]:

Telegram setup: Enter bot token from @BotFather: (You can get this by messaging @BotFather and running /newbot)

✓ Telegram configured Bot token: :* (masked) DM policy: pairing (default) Groups: disabled (can enable later) Next step: DM your bot in Telegram, then approve pairing: openclaw pairing list telegram openclaw pairing approve telegram 

Daemon installation: Install Gateway as a background service? This allows Gateway to run automatically on startup. [1] Yes (recommended) [2] No (run manually) Choose [1-2] [1]:

✓ Installing LaunchAgent... Service file: ~/Library/LaunchAgents/com.openclaw.gateway.plist ✓ Enabled for current user ✓ Gateway will start on login Runtime selection: [1] Node (recommended, required for WhatsApp/Telegram) [2] Bun (experimental, not recommended for WhatsApp/Telegram) Choose [1-2] [1]:

✓ Installing systemd user unit... Service file: ~/.config/systemd/user/openclaw-gateway.service ✓ Enabled for current user ✓ Attempting to enable lingering (stay up after logout)... This may require sudo. Continue? [Y/n]: y Password: ✓ Lingering enabled

✓ Installing LaunchAgent... Service file: ~/Library/LaunchAgents/com.openclaw.gateway.plist ✓ Enabled for current user ✓ Gateway will start on login Note: For headless macOS, you may need a custom LaunchDaemon (not shipped with OpenClaw)

Running health check... Starting Gateway... ✓ Gateway started ✓ Health check passed ✓ Model API accessible ✓ Telegram channel connected Status: Gateway: running (PID 12345) Port: 18789 Channels: telegram (connected) Model: anthropic/claude-3.5-sonnet-

✗ Health check failed Issue: Model API returned 401 (Unauthorized) Possible causes: - API key invalid or expired - Network issue - Rate limit exceeded [1] Retry health check [2] Skip (configure manually later) [3] Go back to auth step Choose [1-3] [1]:

Skills installation: Skills are plugins that extend Agent capabilities. Recommended skills: - gmail (email management) - calendar (calendar integration) - web-search (Brave Search API) [1] Install recommended skills [2] Skip (install later) Choose [1-2] [1]:

Node manager selection: [1] npm [2] pnpm (recommended) Choose [1-2] [2]:

Installing skills... ✓ gmail@latest ✓ calendar@latest ✓ web-search@latest Some skills require additional setup: - gmail: Requires OAuth setup (run 'openclaw configure --section gmail') - web-search: Requires Brave Search API key (run 'openclaw configure --section web')

 2. Test the connection: openclaw status openclaw health 3. Open the dashboard: openclaw dashboard (or visit http://127.0.0.1:18789/) 4. Configure skills (optional): openclaw configure --section web openclaw configure --section gmail Config saved to: ~/.openclaw/openclaw.json

# 注意：以下参数为示例，实际参数请运行 'openclaw onboard --help' 查看 openclaw onboard --non-interactive \\ --mode local \\ --auth-choice moonshot-api-key \\ --moonshot-api-key "$MOONSHOT_API_KEY" \\ --gateway-port 18789 \\ --gateway-bind loopback \\ --install-daemon \\ --daemon-runtime node \\ --skip-skills

🦞 OpenClaw Onboarding (non-interactive) ───────────────────────────────────── ✓ Config written: ~/.openclaw/openclaw.json ✓ Daemon installed ✓ Gateway started

openclaw configure

🦞 OpenClaw Configuration ───────────────────────────────────── What would you like to configure? [1] Model / Auth [2] Gateway [3] Channels [4] Skills [5] Web search (Brave API) [6] Exit Choose [1-6]: 

openclaw dashboard

🦞 Opening dashboard... URL: http://127.0.0.1:18789/ Token: oc_gw_...* (auto-filled in browser) If browser doesn't open automatically, visit the URL above.

Authentication method: ... [6] Moonshot (Kimi K2) ... Choose [1-11] [6]:

Moonshot API Key: Enter your Moonshot API Key: sk-... ✓ Key saved to ~/.openclaw/.env Default model selection: Available Kimi models: [1] moonshot/kimi-k2.5 (recommended) [2] moonshot/kimi-k2-0905-preview [3] moonshot/kimi-k2-turbo-preview [4] moonshot/kimi-k2-thinking [5] moonshot/kimi-k2-thinking-turbo Choose default model [1]:

{ "env": { "MOONSHOT_API_KEY": "sk-..." }, "agents": { "defaults": { "model": { "primary": "moonshot/kimi-k2.5" } } }, "models": { "providers": { "moonshot": { "baseUrl": "https://api.moonshot.ai/v1", "apiKey": "${MOONSHOT_API_KEY}", "api": "openai-completions", "models": [ { "id": "kimi-k2.5", "name": "Kimi K2.5", "contextWindow": , "maxTokens": 8192 } ] } } } }

openclaw configure --section models

🦞 Model Configuration ───────────────────────────────────── Current model: anthropic/claude-3.5-sonnet- Add provider: [1] Anthropic [2] OpenAI [3] Moonshot (Kimi) [4] MiniMax [5] Cancel Choose [1-5] [3]:

Enter Moonshot API Key: sk-... ✓ Provider added Set as default model? [1] Yes [2] No Choose [1-2] [1]:

{ "env": { "MOONSHOT_API_KEY": "sk-你的key" }, "agents": { "defaults": { "model": { "primary": "moonshot/kimi-k2.5" } } }, "models": { "mode": "merge", "providers": { "moonshot": { "baseUrl": "https://api.moonshot.ai/v1", "apiKey": "${MOONSHOT_API_KEY}", "api": "openai-completions", "models": [ { "id": "kimi-k2.5", "name": "Kimi K2.5", "reasoning": false, "input": ["text"], "contextWindow": , "maxTokens": 8192 } ] } } } }

openclaw status

🦞 OpenClaw Status ───────────────────────────────────── Gateway: Status: running Port: 18789 Bind: 127.0.0.1 Agent: Model: moonshot/kimi-k2.5 Provider: moonshot Workspace: ~/.openclaw/workspace Channels: telegram: connected Health: ✓ Gateway reachable ✓ Model API accessible ✓ Telegram connected

openclaw health

🦞 Health Check ───────────────────────────────────── Gateway: ✓ healthy Model API: ✓ accessible (moonshot/kimi-k2.5) Response time: 1.2s Token: valid Channels: telegram: ✓ connected Sessions: 0 active

Model API: ✗ failed Error: 401 Unauthorized Possible causes: - API key invalid - API key expired - Network issue Check your API key: openclaw configure --section models

你好，请用一句话介绍你自己

你好！我是 OpenClaw，一个运行在你机器上的 AI 助手。 我可以通过 Telegram、WhatsApp 等渠道与你对话，并执行你授权的任务， 比如管理邮件、查看日历、运行命令等。

/model moonshot/kimi-k2-thinking

openclaw configure --section models

{ "agents": { "defaults": { "model": { "primary": "moonshot/kimi-k2-thinking" } } } }

openclaw gateway restart

# 通过 onboard 向导选择 Kimi Coding（如果支持） openclaw onboard # 或在向导中选择对应的选项

{ "env": { "KIMI_API_KEY": "sk-..." // 注意：环境变量名可能因版本而异 }, "agents": { "defaults": { "model": { "primary": "kimi-coding/k2p5" // 模型 ID 请以官方文档为准 } } } }

openclaw status openclaw health openclaw security audit --deep

openclaw gateway status

openclaw gateway run --port 18789 --verbose

# 检查配置 openclaw doctor

🦞 Doctor Check ───────────────────────────────────── Config: ✓ valid Gateway: ✓ running Channels: telegram: ✗ token format error Expected: ":ABC..." Found: ": ABC..." # 注意这里有空格 Fix: Run 'openclaw configure --section channels' # 重新配置 Telegram openclaw configure --section channels

openclaw config set models.providers.moonshot.baseUrl "https://api.moonshot.cn/v1" openclaw gateway restart openclaw agent --agent main --message "你好" openclaw config set auth.profiles.moonshot:default.apiKey "你的中国区Key" openclaw gateway restart

Error: Cannot find module 'openclaw' 或 bash: openclaw: command not found

# 检查 openclaw 是否在 PATH which openclaw # 如果找不到，添加 npm global bin 到 PATH export PATH="$(npm prefix -g)/bin:$PATH" # 永久添加（添加到 ~/.bashrc 或 ~/.zshrc） echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc source ~/.bashrc # 或重新安装 npm install -g openclaw@latest

# 检查 openclaw 是否在 PATH where.exe openclaw # 如果找不到，添加 npm global bin 到 PATH $npmPath = npm prefix -g $env:Path += ";$npmPath" # 永久添加（添加到用户环境变量） [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$npmPath", "User") # 或重新安装 npm install -g openclaw@latest

launchctl list | grep openclaw

12345 0 com.openclaw.gateway

# 推荐：使用官方 CLI 查看日志 openclaw logs --follow # 或查看 macOS 系统日志（如果 LaunchAgent 有问题） log show --predicate 'process == "openclaw"' --last 5m

# 重新安装 daemon openclaw configure --section gateway # 选择 "Install daemon" # 或手动重启服务 launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist

systemctl --user status openclaw-gateway

● openclaw-gateway.service - OpenClaw Gateway Loaded: loaded (/home/user/.config/systemd/user/openclaw-gateway.service) Active: failed (Result: exit-code) Error: Cannot find module 'openclaw'

# 重新安装 daemon openclaw configure --section gateway # 选择 "Install daemon" # 或手动重启服务 systemctl --user restart openclaw-gateway systemctl --user status openclaw-gateway

openclaw health

🦞 Health Check ───────────────────────────────────── Gateway: ✓ healthy Model API: ✗ failed Error: 401 Unauthorized Provider: moonshot Model: moonshot/kimi-k2.5 Possible causes: - API key invalid or expired - Network issue - Rate limit exceeded

Error: Permission denied: /path/to/file

openclaw sandbox explain

🦞 Sandbox Inspector ───────────────────────────────────── Agent: main Sandbox mode: non-main Current session: sandboxed (non-main) Workspace access: rw Tool policy: allow [exec, read, write, ...] Elevated: disabled

{ "agents": { "defaults": { "sandbox": { "mode": "off" // "off" = 主机运行, "non-main" = 仅非主会话沙箱, "all" = 全部沙箱 } } } }

Error: Browser launch failed: Chrome/Chromium not found

Error: Port 18789 is already in use

# 方法 1：使用 lsof lsof -i :18789 # 命令行输出： # COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME # node 12345 user 23u IPv4 12345 0t0 TCP *:18789 (LISTEN) # 方法 2：使用 netstat netstat -tulpn | grep 18789 # 方法 3：使用 ss（现代 Linux） ss -tulpn | grep 18789

# 方法 1：使用 netstat netstat -ano | findstr :18789 # 命令行输出： # TCP 0.0.0.0:18789 0.0.0.0:0 LISTENING 12345 # 方法 2：使用 Get-NetTCPConnection（PowerShell 5.1+） Get-NetTCPConnection -LocalPort 18789 # 查看进程详情 Get-Process -Id 12345

# 方法 1：杀死占用进程 kill -9 12345 # 替换为实际 PID # 方法 2：改用其他端口 openclaw configure --section gateway # 选择不同的端口（如 18790）

# 方法 1：杀死占用进程 Stop-Process -Id 12345 -Force # 替换为实际 PID # 方法 2：改用其他端口 openclaw configure --section gateway # 选择不同的端口（如 18790）

openclaw doctor

🦞 Doctor Check ───────────────────────────────────── Config: ✗ invalid JSON Error: Unexpected token } in JSON at position 1234 File: ~/.openclaw/openclaw.json Fix: Check JSON syntax or run 'openclaw reset' to start fresh

openclaw reset # 选择 "Config only" 保留凭证和会话

openclaw sandbox explain

🦞 Sandbox Inspector ───────────────────────────────────── Agent: main Sandbox mode: non-main Current session: sandboxed (non-main) Workspace access: rw Tool policy: allow [exec, read, write, browser, ...] Elevated: disabled

{ "agents": { "defaults": { "sandbox": { "mode": "non-main" // 非主会话在沙箱中运行 }, "tools": { "allow": ["read", "exec"], // 只允许读取和执行 "deny": ["write", "delete", "edit"], // 禁止写入/删除/编辑 "sandbox": { "tools": { "allow": ["read", "exec"], // 沙箱内也只允许读取和执行 "deny": ["write", "delete"] } } } } } }

openclaw sandbox explain --agent main

openclaw status --all | grep "Bind"

Bind: 0.0.0.0:18789 # 监听所有网络接口，危险！

openclaw configure --section gateway # 选择 bind: 127.0.0.1 (loopback)

Bind: 127.0.0.1:18789 # 只监听本地，安全

# 在本地机器执行 ssh -N -L 18789:127.0.0.1:18789 user@remote-host # 然后访问 http://127.0.0.1:18789/（实际连接到远程 Gateway）

openclaw configure --section gateway # 选择 "Enable Tailscale exposure"

openclaw approvals get

🦞 Exec Approvals ───────────────────────────────────── No approvals configured (all commands allowed)

# 添加危险命令到审批列表（需要匹配完整路径） openclaw approvals allowlist add "rm -rf" openclaw approvals allowlist add "/usr/bin/dd" openclaw approvals allowlist add "~/.scripts/dangerous.sh" # 查看更新后的配置 openclaw approvals get

🦞 Exec Approvals ───────────────────────────────────── Allowlist: - rm -rf - /usr/bin/dd - ~/.scripts/dangerous.sh

{ "allowlist": [ "rm -rf", "/usr/bin/dd", "~/.scripts/dangerous.sh" ] }

openclaw approvals set --file ./exec-approvals.json

openclaw security audit --deep

🦞 Security Audit ───────────────────────────────────── Gateway: ✓ Bind: 127.0.0.1 (safe) ✓ Auth: Token enabled ✗ Token exposed in logs (fix: use environment variable) Channels: ✓ Telegram: pairing enabled ✓ WhatsApp: pairing enabled Agents: ✓ Sandbox: enabled ✗ Elevated mode: enabled (consider disabling) Recommendations: 1. Move gateway token to environment variable 2. Disable elevated mode unless needed 3. Review active sessions monthly

阶段 1：基础使用（当前） ├─ ✅ 安装和配置 ├─ ✅ 跑通最小闭环 └─ ✅ 接入一个渠道 阶段 2：扩展能力 ├─ 📖 阅读：https://docs.openclaw.ai/tools/skills ├─ 🔧 安装第一个 Skill（如 gmail） ├─ 📝 学习配置 Skills └─ 🎯 实现一个具体场景（如"每天清邮件"） 阶段 3：高级功能 ├─ 📖 阅读：https://docs.openclaw.ai/automation/cron-jobs ├─ 🔧 配置定时任务 ├─ 📖 阅读：https://docs.openclaw.ai/concepts/multi-agent └─ 🎯 配置多 Agent 路由 阶段 4：自定义开发 ├─ 📖 阅读：https://docs.openclaw.ai/tools/skills（开发部分） ├─ 🔧 开发自己的 Skill └─ 🎯 贡献到社区

# Linux/macOS/WSL2 echo ~/.openclaw # Windows PowerShell $env:USERPROFILE\\.openclaw