OpenClaw 保姆级超详细教程：小白也能轻松上手的 AI 智能体

关键名词解释

1.3 新手使用的正确心态

1. 先跑通「发指令→真执行→回结果」的最小闭环，不要一上来就追求全自动化人生
2. 把它当成「会犯错的实习生」，先给最小权限，验证稳定后再逐步开放
3. 先只接入一个你明天就会用的能力（比如清邮件、整理日程），跑稳了再扩展其他功能

第二章 安装前的全量环境准备（避坑第一步）

2.1 系统与硬性要求

2.2 必备依赖安装（分平台手把手）

核心必装：Node.js（必须≥22.0 版本，否则必报错）

推荐使用 nvm 安装，可灵活切换版本，避免权限问题：

bash

运行

# 1. 安装nvm（macOS/Linux/WSL2） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 2. 重载终端配置 source ~/.bashrc # bash终端 source ~/.zshrc # zsh终端 # 3. 安装Node.js 22 LTS版本 nvm install 22 nvm use 22 # 4. 验证安装成功（必须输出版本≥22.0.0） node -v npm -v 

Windows 原生系统：直接前往Node.js 官网下载 22.x LTS 版本，按向导安装后，在 PowerShell 执行node -v验证。

可选依赖

• Git：源码安装时必备，macOS/Linux 执行xcode-select --install（macOS）/sudo apt install git（Linux）即可安装
• pnpm：源码构建推荐使用，执行npm install -g pnpm即可安装
• Chrome/Chromium：浏览器自动化工具必备，后续使用时安装即可

WSL2 完整安装教程（Windows 用户必看）

1. 打开 Microsoft Store，搜索「Ubuntu 22.04 LTS」，点击安装，安装完成后启动 Ubuntu，设置用户名和密码
2. 关闭 PowerShell，执行wsl --shutdown，重新打开 Ubuntu 终端，执行systemctl --user status验证 systemd 正常运行
3. 按上文 Node.js 安装步骤，在 Ubuntu 终端内安装 Node.js 22 + 版本

开启 systemd（后台服务必备），在 Ubuntu 终端执行bash运行

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

重启电脑，再次以管理员身份打开 PowerShell，设置 WSL2 为默认版本powershell

wsl --set-default-version 2 

以管理员身份打开 PowerShell，执行以下命令开启 WSL2 功能powershell

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart 

2.3 AI 模型 API Key 准备

OpenClaw 本身不提供大模型能力，需提前准备好模型 API Key，二选一即可：

1. 海外模型：Anthropic Claude（推荐）、OpenAI GPT 系列，需前往对应官网控制台创建按量付费 API Key（禁止使用 Claude Pro/Max 订阅密钥，违反服务条款）
2. 国内模型：Moonshot Kimi、MiniMax、智谱 GLM，国内网络可直连，无需代理，下文有完整接入教程
3. 本地模型：提前安装 Ollama 并下载对应大模型，实现零云端依赖，完全隐私可控

2.4 国内用户网络环境准备

如果使用海外模型，需提前配置系统代理，否则无法调用 API、启动网关：

bash

运行

# 终端临时配置代理（端口改为你自己的代理端口） export HTTPS_PROXY="http://127.0.0.1:7890" export HTTP_PROXY="http://127.0.0.1:7890" # 永久配置（写入终端配置文件） echo 'export HTTPS_PROXY="http://127.0.0.1:7890"' >> ~/.zshrc echo 'export HTTP_PROXY="http://127.0.0.1:7890"' >> ~/.zshrc source ~/.zshrc # 也可直接在OpenClaw配置中设置代理 openclaw config set gateway.proxy.url "http://127.0.0.1:7890" 

2.5 30 秒环境自检

安装完依赖后，执行以下命令，全部通过再继续后续步骤：

bash

运行

# 检查Node.js版本（必须≥22.0.0） node -v # 检查npm是否正常 npm -v # 检查网络连通性（海外模型需执行，能正常返回即代理生效） curl https://api.anthropic.com/v1/messages --head # 国内模型检查 curl https://api.moonshot.cn/v1/chat/completions --head 

第三章 OpenClaw 全方式安装教程

3.1 方式 1：一键脚本安装（新手首选，99% 兼容）

自动安装 Node.js、Python、OpenClaw CLI 及所有依赖，无需手动配置，全程无需干预。

macOS / Linux / WSL2

打开终端，执行以下命令：

bash

运行

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

Windows 原生系统（不推荐，优先用 WSL2）

以管理员身份打开 PowerShell，执行以下命令：

powershell

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

安装完成后，终端会提示Install completed，即安装成功。

3.2 方式 2：NPM/PNPM 手动安装（可控性强）

适合已有 Node.js 环境，想自主控制安装过程的用户：

bash

运行

# NPM安装（通用） npm install -g openclaw@latest # PNPM安装（推荐，性能更好） pnpm add -g openclaw@latest pnpm approve-builds -g 

3.3 方式 3：源码安装（开发者专用，适合二次开发）

适合想调试代码、贡献社区、自定义修改的用户：

bash

运行

# 1. 克隆官方仓库 git clone https://github.com/openclaw/openclaw.git cd openclaw # 2. 安装依赖 pnpm install # 3. 构建UI和项目 pnpm ui:build pnpm build # 4. 执行初始化配置 openclaw onboard --install-daemon 

3.4 安装后必做的验证 & 问题解决

1. 验证安装成功

执行以下命令，能正常输出版本号，即安装成功：

bash

运行

openclaw --version # 查看帮助文档，确认命令可用 openclaw --help 

2. 高频问题：安装后提示command not found

这是 npm 全局安装目录不在系统 PATH 中导致的，按以下方案解决：

bash

运行

# macOS/Linux/WSL2 # 1. 查找openclaw安装位置 which openclaw # 2. 若找不到，添加npm全局bin目录到PATH export PATH="$(npm prefix -g)/bin:$PATH" # 3. 永久生效 echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc # bash echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc # zsh source ~/.zshrc # 重载配置 # Windows PowerShell # 1. 查找安装位置 where.exe openclaw # 2. 添加到环境变量 $npmPath = npm prefix -g $env:Path += ";$npmPath" # 3. 永久生效 [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$npmPath", "User") 

3.5 新手安装避坑指南

1. ❌ 禁止使用 Bun 运行 WhatsApp/Telegram 渠道，官方明确说明 Bun 在这些渠道有已知兼容性问题，必须使用 Node.js
2. ❌ 不要使用低于 22.0 的 Node.js 版本，会出现大量依赖报错、功能异常
3. ❌ Windows 用户不要强行使用原生系统，优先使用 WSL2，可避免 90% 的兼容性问题
4. ❌ 不要在代理未配置好的情况下安装 / 启动，会出现依赖拉取失败、API 调用超时

第四章 手把手交互式初始化配置（onboard 向导全步骤详解）

openclaw onboard是官方推荐的配置方式，全程交互式引导，新手跟着选即可，不会出错。

4.1 启动配置向导

打开终端，执行以下命令，启动向导并自动安装后台守护进程（开机自启）：

bash

运行

openclaw onboard --install-daemon 

4.2 每一步配置详解 & 选择建议

以下是向导全步骤的命令行视图与新手选择建议，实际输出可能因版本略有差异，以官方提示为准。

步骤 1：选择配置模式

plaintext

🦞 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]: 

• 新手必选1（QuickStart），使用官方推荐的默认值，只需要填写核心配置，避免踩坑
• 有自定义需求的用户可选2（Advanced），完全自主控制所有配置项

步骤 2：处理现有配置

如果之前安装过 OpenClaw，向导会检测到现有配置，提示：

plaintext

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]: 

• 首次安装无此步骤
• 想保留之前的配置选1，想修改部分配置选2，想完全清空重来选3

步骤 3：选择 Gateway 运行模式

plaintext

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

• 新手必选1（Local），在本机运行网关，所有数据都在本地
• 2（Remote）仅用于连接远程服务器上已部署的网关，首次安装不要选

步骤 4：选择 AI 模型认证方式（最核心步骤）

向导会先检测环境变量中已有的 API Key，然后列出所有支持的认证方式：

plaintext

Checking for existing API keys... ✓ Found ANTHROPIC_API_KEY in environment ✗ No MOONSHOT_API_KEY found Authentication method: [1] Anthropic API Key (recommended) [2] Anthropic OAuth (Claude Code CLI) [3] OpenAI API Key [6] Moonshot (Kimi K2) [7] MiniMax M2.1 [8] 智谱GLM [11] Skip (configure later) Choose [1-11] [1]: 

• 选择你准备好的模型对应的选项，比如用 Kimi 就选6，用 Claude 就选1
• 选好后，向导会提示你输入对应的 API Key，粘贴后回车即可，密钥会自动加密保存到~/.openclaw/.env文件中
• 输入完成后，向导会让你选择默认模型，新手按推荐选择即可（Claude 选 sonnet，Kimi 选 kimi-k2.5，平衡性能与成本）

步骤 5：Workspace 工作目录配置

plaintext

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

• 新手必选1，使用默认工作目录，后续可随时修改
• 自定义路径需确保当前用户有读写权限

步骤 6：Gateway 网关配置

plaintext

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

• 新手必选1，使用默认配置，端口 18789，仅本地可访问，自动生成认证 Token，安全有保障
• 想修改端口、绑定地址的用户可选2，禁止新手直接绑定 0.0.0.0，会有严重安全风险

步骤 7：聊天渠道配置

plaintext

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]: 

• 新手优先选1（Telegram），配置最简单，稳定性最高，后续可添加其他渠道
• 选择后，向导会提示你输入对应渠道的凭证，比如 Telegram 需要输入 Bot Token，下文有详细的 Bot 创建教程
• 也可以选6跳过，后续通过openclaw configure命令补充配置

步骤 8：后台守护进程安装

plaintext

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]: 

• 必选1，安装后台服务，实现开机自启，关闭终端也能正常运行
• 选择后，向导会让你选择运行时，必须选 1（Node），Bun 有兼容性问题，不要选

步骤 9：技能插件安装（可选）

plaintext

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]: 

• 新手选2跳过，先跑通基础闭环，再按需安装技能插件
• 有明确需求的用户可选1，安装推荐技能，后续需单独配置 OAuth 授权

步骤 10：健康检查 & 配置完成

向导会自动执行健康检查，验证网关、模型 API、渠道是否正常：

• 健康检查通过：会显示配置保存路径、Web 仪表板地址、后续操作步骤，配置完成
• 健康检查失败：向导会提示错误原因和解决方案，比如 API Key 无效、网络不通，按提示修复后重试即可

4.3 非交互模式自动化配置（适合服务器部署）

如果你需要用脚本自动化部署，可使用非交互模式，无需手动选择，示例如下：

bash

运行

openclaw onboard --non-interactive \ --mode local \ --auth-choice moonshot-api-key \ --moonshot-api-key "你的Kimi API Key" \ --gateway-port 18789 \ --gateway-bind loopback \ --install-daemon \ --daemon-runtime node \ --skip-skills 

注意：非交互模式的参数可能因版本变化，执行openclaw onboard --help查看最新可用参数。

4.4 后续配置修改

如果后续想修改配置，无需重新跑向导，执行以下命令即可进入交互式配置界面，只修改你需要的部分：

bash

运行

openclaw configure

第五章 国内大模型完整接入教程

5.1 Kimi（Moonshot）从零到接入全流程

Kimi 是国内用户首选，网络可直连，无需代理，长上下文能力强，OpenClaw 原生支持。

步骤 1：获取 Kimi API Key

1. 访问Moonshot 开放平台，注册并登录账号
2. 进入控制台 → API Keys，点击「创建 API Key」，设置名称后，复制完整的 Key（格式为sk-xxx）
3. 重要提醒：Moonshot API Key 和 Kimi Coding Key 不通用，不要混用

步骤 2：通过 onboard 向导配置（推荐）

在openclaw onboard的认证方式步骤，选择6 Moonshot (Kimi K2)，粘贴你复制的 API Key，向导会自动配置好模型参数，无需手动修改。

步骤 3：手动配置（已完成初始化的用户）

方式 A：通过交互式命令配置

bash

运行

openclaw configure --section models # 选择3 Moonshot (Kimi) # 粘贴API Key # 选择是否设为默认模型 

方式 B：直接编辑配置文件编辑~/.openclaw/openclaw.json文件，添加以下配置：

json

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

保存后，执行openclaw gateway restart重启网关生效。

步骤 4：验证配置是否生效

bash

运行

# 查看状态，确认模型已配置 openclaw status # 健康检查，验证API可正常调用 openclaw health # 发送测试消息，验证模型响应 openclaw agent --agent main --message "你好，用一句话介绍自己" 

能正常收到回复，即 Kimi 接入成功。

可用 Kimi 模型列表

模型切换方法

• 临时切换（单次对话）：在聊天中发送 /model moonshot/kimi-k2-thinking
• 永久切换（修改默认模型）：执行openclaw models set moonshot/kimi-k2.5，然后重启网关

5.2 其他国内模型配置

MiniMax、智谱 GLM 等国内模型，配置逻辑与 Kimi 一致，在openclaw onboard向导中选择对应选项，输入 API Key 即可自动配置，也可参考官方文档手动编辑配置文件。

5.3 本地 Ollama 模型接入教程

实现零云端依赖，完全隐私可控，所有数据均在本地处理：

1. 提前安装 Ollama，执行ollama run 模型名称（比如llama3），确保本地模型正常运行
2. 保存配置，执行openclaw gateway restart重启网关，执行openclaw health验证模型连通性。

编辑~/.openclaw/openclaw.json配置文件，添加以下内容：json

{ "agents": { "defaults": { "model": { "primary": "ollama:你的模型名称" } } }, "models": { "providers": { "ollama": { "baseUrl": "http://127.0.0.1:11434", "api": "openai-completions" } } } } 

第六章 Gateway 网关启动 & Web 控制界面使用

Gateway 是 OpenClaw 的核心，所有消息、渠道、会话都由它统一管理，必须确保网关正常运行。

6.1 网关的运行方式

6.2 网关启动后的必做验证

执行以下 3 条命令，确认网关完全正常：

bash

运行

# 1. 查看网关状态，确认显示running openclaw gateway status # 2. 全量状态检查，确认渠道、模型均正常 openclaw status # 3. 健康检查，确认无报错 openclaw health 

6.3 Web 控制界面使用

网关启动后，即可通过浏览器访问可视化控制界面，无需敲命令即可完成所有配置、聊天、管理操作。

1. 本地默认访问地址：http://127.0.0.1:18789/
2. 快速打开命令：终端执行openclaw dashboard，会自动打开浏览器并跳转到仪表板
3. 核心功能模块：
   • 聊天面板：直接在浏览器中与智能体对话，测试所有能力
   • 渠道管理：可视化添加、配置、管理所有聊天渠道，无需敲命令
   • 会话管理：查看、隔离、重置不同用户的会话上下文
   • 配置管理：可视化修改所有配置项，自动校验格式，避免手动编辑 JSON 出错
   • 技能市场：一键安装、卸载、配置技能插件
   • 节点管理：配对 iOS/Android 移动节点，扩展移动端能力
   • 日志面板：实时查看网关运行日志，快速定位问题

6.4 网关常见配置修改

1. 修改端口

bash

运行

# 命令行修改 openclaw config set gateway.port 18790 # 重启网关生效 openclaw gateway restart 

2. 修改绑定地址

警告：新手禁止绑定 0.0.0.0，会将网关暴露到公网，有严重安全风险，远程访问请使用 Tailscale 或 SSH 隧道

bash

运行

# 仅本地访问（默认，安全） openclaw config set gateway.bind loopback # 仅Tailscale网络访问（推荐远程使用） openclaw config set gateway.bind tailnet # 局域网访问（仅家庭内网使用） openclaw config set gateway.bind lan # 重启网关生效 openclaw gateway restart 

第七章 聊天渠道完整接入 & 安全配对（核心必看）

7.1 渠道接入前置说明

1. 所有渠道接入后，默认开启配对安全策略：陌生用户发消息不会被处理，必须你手动批准配对后才能正常响应，防止机器人被滥用
2. 新手优先接入 Telegram，配置最简单，稳定性最高，跑通后再接入其他渠道
3. 所有渠道的状态，都可以通过openclaw channels status --probe命令查看

7.2 Telegram Bot 从零接入全流程

Telegram 是 OpenClaw 适配最完善的渠道，新手首选。

步骤 1：创建 Telegram Bot，获取 Token

1. 打开 Telegram，搜索@BotFather（带官方蓝标认证），点击进入
2. 发送/newbot命令，跟着提示设置机器人名称、用户名（用户名必须以bot结尾）
3. 创建完成后，BotFather 会给你一条消息，里面包含HTTP API，后面的一串字符就是 Bot Token（格式类似123456789:ABCdefGHIjklMNOpqrsTUVwxyz），复制保存好

步骤 2：接入 OpenClaw

方式 A：onboard 向导配置在初始化向导的渠道步骤，选择1 Telegram，粘贴你复制的 Bot Token，向导会自动完成配置。

方式 B：手动命令配置

bash

运行

# 进入渠道配置界面 openclaw configure --section channels.telegram # 按提示粘贴Bot Token，回车确认 # 重启网关生效 openclaw gateway restart 

方式 C：Web 界面配置打开 Web 仪表板 → 渠道管理 → 选择 Telegram → 粘贴 Bot Token → 点击保存，自动完成配置。

步骤 3：安全配对（最关键，否则发消息没反应）

1. 打开 Telegram，搜索你创建的机器人用户名，点击进入，发送第一条消息（比如「你好」）
2. 机器人会自动回复一个 8 位配对码，不会响应其他内容
3. 终端提示✓ Pairing approved，即配对完成，回到 Telegram，重新发送消息，机器人就会正常响应了。

执行以下命令，批准配对（替换为你的配对码）：bash运行

openclaw pairing approve telegram <你的配对码> 

回到终端，执行以下命令，查看待处理的配对请求：bash运行

openclaw pairing list telegram 

步骤 4：白名单免配对配置（可选）

如果你想让指定用户无需配对，直接使用，可配置白名单：

1. 编辑~/.openclaw/openclaw.json配置文件
2. 保存配置，重启网关生效，白名单内的用户无需配对，直接发送消息即可响应。

添加以下配置，替换为你的 Telegram 用户 ID（可通过 @userinfobot 获取）：json

{ "channels": { "telegram": { "dmPolicy": "pairing", "allowFrom": [123456789, 987654321] } } } 

步骤 5：群聊配置

1. 把机器人邀请到你的 Telegram 群组中，给机器人管理员权限（至少需要发送消息、读取消息权限）
2. 保存配置，重启网关生效，群聊中必须 @机器人，才会响应，避免误触发。

编辑配置文件，添加群聊配置：json

{ "channels": { "telegram": { "groups": { "*": { "requireMention": true } } } }, "messages": { "groupChat": { "mentionPatterns": ["@你的机器人用户名"] } } } 

7.3 WhatsApp 接入步骤

1. 终端会生成一个二维码，打开手机 WhatsApp → 设置 → 已关联设备 → 扫描二维码
2. 扫码完成后，终端提示登录成功，重启网关即可生效
3. 首次发送消息，同样需要执行openclaw pairing list whatsapp查看配对码，执行openclaw pairing approve whatsapp <配对码>批准后，才能正常响应
4. 白名单配置与 Telegram 逻辑一致，在配置文件的channels.whatsapp.allowFrom中添加允许的手机号（格式为+8613800138000）

终端执行以下命令，启动登录流程：bash运行

openclaw channels login 

7.4 Discord 接入步骤

1. 访问Discord 开发者平台，登录账号，创建新应用
2. 进入应用 → Bot，点击「Add Bot」，然后点击「Reset Token」，复制 Bot Token 保存好
3. 在 Bot 设置页面，开启「Privileged Gateway Intents」下的所有权限（Presence Intent、Server Members Intent、Message Content Intent）
4. 进入 OAuth2 → URL Generator，勾选bot和applications.commands，然后在 Bot 权限中勾选发送消息、读取消息、管理消息等基础权限，复制生成的 URL，在浏览器中打开，邀请机器人到你的服务器
5. 回到 OpenClaw，执行openclaw configure --section channels.discord，粘贴 Bot Token，重启网关生效
6. 首次私信机器人，同样需要完成配对批准，才能正常响应。

7.5 iMessage 接入（仅 macOS）

1. 执行openclaw configure --section channels.imessage，完成配置
2. 给你的 iMessage 账号发送消息，完成配对批准后，即可正常使用。

先安装 imsg CLI 工具，终端执行：bash运行

brew install keith/formulae/imsg 

第八章 新手必看：先跑通最小闭环

很多新手一上来就配置大量功能，结果出问题找不到原因，正确的做法是先跑通「发指令→真执行→回结果」的最小闭环，验证全链路通畅。

8.1 第一步：确认链路通畅（基础对话测试）

给你的机器人发送以下消息，能稳定收到回复，说明聊天链路、模型调用完全正常：

1. 「你是谁？用 3 句话介绍你自己」
2. 「你当前有哪些核心能力？用 5 条列出来」

如果没收到回复，直接跳转到第十三章故障排查，按步骤排查问题，不要继续往下走。

8.2 第二步：低风险执行任务测试

选择无风险、不会造成系统损坏的任务，验证智能体的执行能力，推荐以下测试指令，按顺序执行：

1. 「告诉我现在的系统时间」
2. 「列出你当前的工作目录里有哪些文件」
3. 「在工作目录里创建一个 test.txt 文件，写入 'OpenClaw 测试成功'」
4. 「读取 test.txt 文件的内容，返回给我」

能完整执行以上步骤，返回正确结果，说明最小闭环完全跑通，你已经可以正常使用 OpenClaw 的所有能力了。

8.3 官方自检三连（必跑）

每次修改配置、出现异常时，先执行以下 3 条命令，可定位 90% 的问题：

bash

运行

# 1. 查看全量状态 openclaw status # 2. 健康检查，验证网关、模型、渠道是否正常 openclaw health # 3. 自动诊断并修复常见问题 openclaw doctor --fix 

8.4 新手最佳实践

1. 先只接一个你明天就会用的能力，比如「清邮件」「整理日程」，跑稳了再扩展其他功能，不要一上来就全量配置
2. 指令编写要具体，明确目标、范围、禁止项，避免歧义导致误操作，比如：
   • ❌ 错误指令：「帮我整理文件」
   • ✅ 正确指令：「帮我整理 Downloads 文件夹里的文件，只处理超过 30 天的文件，移动到 Archive 文件夹，不要删除任何文件，移动前先告诉我文件列表，等我确认后再执行」
3. 高风险操作，要求它先复述执行计划，等你确认后再执行，比如在指令末尾加上「在开始之前，先告诉我你的执行计划，等我确认后再执行」
4. 先给最小权限，验证稳定后，再逐步开放更多工具权限。

第九章 日常基础使用 & 核心能力演示

9.1 基础触发规则

• 私聊场景：直接发送你的需求，无需 @，机器人会直接响应，默认按发送者隔离会话，上下文互不干扰
• 群聊场景：必须按配置 @对应的触发词（比如 @你的机器人名称）+ 需求，才会响应，避免群聊消息误触发

9.2 媒体文件使用

直接在聊天窗口发送图片、音频、文档、压缩包等文件，再补充对应的需求指令即可，支持几乎所有常见格式，示例：

• 发送一张代码截图 + 指令：「帮我识别这张截图里的代码，修复其中的语法错误，解释错误原因，并给出优化后的完整代码」
• 发送一个 PDF 合同 + 指令：「帮我读取这份 PDF 合同，提取核心的付款条款、违约责任、合作期限，整理成清晰的表格」
• 发送一个 Excel 表格 + 指令：「帮我分析这个表格里的销售数据，按月份统计销售额，找出 Top3 的产品，生成数据分析报告」

9.3 高频场景指令示例

9.4 内置工具使用

OpenClaw 内置了 3 个核心工具，无需额外安装即可使用：

1. exec 终端命令工具：可执行系统终端命令，运行脚本，管理进程，是最核心的执行工具
2. browser 浏览器工具：可控制 Chrome/Chromium 浏览器，访问网页、填写表单、抓取数据、截图、自动化操作
3. file 文件管理工具：可读写、创建、删除、移动本地文件，支持几乎所有文件格式的读取与写入

9.5 技能插件安装 & 使用

技能是扩展 OpenClaw 能力的插件，目前有 100 + 预置技能，支持 50 + 第三方服务对接，比如 Gmail、日历、智能家居、音乐平台等。

安装方法

1. Web 界面安装（推荐）：打开仪表板 → 技能市场 → 找到你需要的技能 → 点击「安装」，自动完成安装和基础配置

命令行安装：bash运行

# 查看可用技能列表 openclaw skills list # 安装指定技能 openclaw skills install gmail # 配置技能 openclaw skills config gmail # 更新技能 openclaw skills update gmail 

新手推荐技能

第十章 进阶玩法 & 能力扩展

10.1 多智能体路由与会话隔离

OpenClaw 支持配置多个独立的 Agent，每个 Agent 使用不同的模型、技能、权限、工作目录，按发送者、渠道自动路由，实现场景隔离。

示例配置：编辑~/.openclaw/openclaw.json，添加以下内容

json

{ "agents": { "default": { "model": "moonshot/kimi-k2.5", "skills": ["file-system", "terminal"], "workspace": "~/.openclaw/workspace/default" }, "code-agent": { "model": "anthropic/claude-3-5-sonnet-20241022", "skills": ["git", "code-review", "testing"], "workspace": "~/code", "allowFrom": ["+8613800138000", 123456789] }, "local-agent": { "model": "ollama:llama3", "memorySearch": { "provider": "local" }, "skills": ["browser"], "workspace": "~/.openclaw/workspace/local" } }, "routing": { "bySender": { "+8613800138000": "code-agent", "123456789": "code-agent", "*": "default" }, "byChannel": { "telegram": "local-agent", "whatsapp": "default" } } } 

保存配置，重启网关生效，即可实现：指定用户使用代码专属 Agent，Telegram 渠道使用本地模型 Agent，其他用户使用默认 Agent，上下文、权限、能力完全隔离。

10.2 定时任务自动化配置

OpenClaw 支持配置 Cron 定时任务，实现无人值守自动化执行，比如每天 9 点清邮件、每周五生成数据报告、每天凌晨备份文件等。

配置方法：

1. 编辑~/.openclaw/openclaw.json配置文件，添加cron配置项
2. 保存配置，重启网关生效，定时任务会自动按计划执行。

示例：每天 9 点执行清邮件任务，每周五 18 点生成周报json

{ "cron": { "jobs": [ { "name": "daily-email-cleanup", "schedule": "0 9 * * *", "agent": "default", "message": "帮我清理今天的收件箱，把广告、促销邮件标为已读并归档，整理重要工作邮件的摘要，发送到我的Telegram" }, { "name": "weekly-report", "schedule": "0 18 * * 5", "agent": "default", "message": "帮我读取本周的工作文档、邮件、Git提交记录，生成一份完整的工作周报，突出核心成果和下周计划" } ] } } 

10.3 远程访问安全配置

如果你需要在其他设备访问 OpenClaw，禁止直接暴露公网端口，推荐以下两种安全方案：

方案 1：Tailscale（官方推荐，最简单安全）

1. 在网关设备和访问设备上安装 Tailscale，完成组网
2. 组网内的所有设备，都可以通过 Tailscale 分配的 IP+18789 端口，安全访问 Web 仪表板和网关服务。

终端执行以下命令，配置网关绑定 Tailscale 网络：bash运行

openclaw config set gateway.bind tailnet openclaw gateway restart 

方案 2：SSH 隧道（无需额外软件）

1. 隧道建立后，本地浏览器访问http://127.0.0.1:18789/，即可安全访问远程服务器上的 OpenClaw 仪表板。

在本地访问设备上，执行以下命令，建立 SSH 隧道：bash运行

ssh -N -L 18789:127.0.0.1:18789 你的服务器用户名@服务器IP 

10.4 移动节点配对

OpenClaw 支持配对 iOS 和 Android 移动节点，扩展 Canvas、移动端相机、文件访问等能力，步骤如下：

1. 打开 Web 仪表板，进入「节点管理」菜单
2. 点击「添加移动节点」，生成配对二维码
3. 手机端安装 OpenClaw 移动端应用，打开扫码功能，扫描二维码完成配对
4. 配对完成后，即可在移动端直接管理网关、与智能体对话，调用移动端的相机、文件、Canvas 等能力。

10.5 自定义技能开发入门

你可以自己编写技能插件，扩展 OpenClaw 的能力，甚至让 OpenClaw 帮你生成技能代码：

1. 官方技能开发文档：https://docs.openclaw.ai/tools/skills
2. 基础技能结构：每个技能包含一个index.js入口文件、package.json依赖配置、README.md说明文档
3. 开发完成后，可通过openclaw skills install 本地技能路径安装，也可发布到社区，供其他用户使用。

第十一章 全方面安全加固（越能干活，越要克制）

OpenClaw 拥有你设备的系统权限，一旦配置不当，可能导致数据泄露、系统损坏、API 额度被盗刷，必须做好安全加固。

11.1 最小权限原则 & 沙箱配置详解

OpenClaw 通过三层权限控制：Sandbox 沙箱、Tool Policy 工具策略、Elevated 权限，新手必须先配置沙箱，限制 Agent 的权限范围。

第一步：查看当前生效的权限配置

bash

运行

openclaw sandbox explain 

可查看当前 Agent 的沙箱模式、工作目录权限、工具允许列表、提权状态。

第二步：沙箱模式配置

编辑~/.openclaw/openclaw.json，添加以下配置，推荐新手使用non-main模式：

json

{ "agents": { "defaults": { "sandbox": { "mode": "non-main", "scope": "agent", "workspaceAccess": "rw", "bindMounts": [ { "source": "~/Downloads", "target": "/downloads", "access": "ro" } ] } } } } 

• mode: non-main：主会话在主机运行，其他会话全部在沙箱中运行，平衡便利性与安全性，新手首选
• mode: all：所有会话全部在沙箱中运行，最高安全性
• mode: off：关闭沙箱，Agent 可直接访问主机系统，仅完全信任时使用
• workspaceAccess: ro：只读权限，rw：读写权限，新手先设为ro，验证稳定后再开放rw
• bindMounts：挂载指定目录到沙箱，可设置只读 / 读写权限，避免 Agent 访问无关目录

第三步：工具策略配置（限制可使用的工具）

json

{ "agents": { "defaults": { "tools": { "allow": ["read", "exec"], "deny": ["write", "delete", "edit", "sudo"], "sandbox": { "tools": { "allow": ["read"], "deny": ["write", "delete", "exec"] } } } } } } 

• allow：允许使用的工具，新手先只开放read，逐步添加
• deny：禁止使用的工具，必须禁止sudo、rm -rf等高风险操作
• 权限逐步开放策略：
  1. 第一阶段：只允许文本处理，仅开放read工具，禁用exec
  2. 第二阶段：允许读取和执行，开放read、exec，禁用write、delete
  3. 第三阶段：允许写入指定目录，通过bindMounts限制范围
  4. 最后阶段：根据信任度，逐步开放更多权限

11.2 网络安全加固

启用网关 Token 认证：即使是本地访问，也必须启用 Token 认证，防止本地其他进程误连bash运行

openclaw config set gateway.auth.mode token # 生成强随机Token，替换为你自己的 openclaw config set gateway.auth.token "你的强随机Token" openclaw gateway restart 

防火墙配置：只允许本地访问网关端口，禁止公网入站访问bash运行

# Linux ufw防火墙配置 sudo ufw allow from 127.0.0.1 to any port 18789 sudo ufw deny 18789 sudo ufw reload 

禁止绑定公网地址：必须确保网关只绑定127.0.0.1或tailnet，禁止绑定0.0.0.0bash运行

# 检查当前绑定地址 openclaw status --all | grep "Bind" # 修正为本地回环地址 openclaw config set gateway.bind loopback openclaw gateway restart 

11.3 敏感信息管理规范

1. ❌ 禁止在聊天对话中直接发送 API Key、密码、Token 等敏感信息
2. ❌ 禁止把 API Key、凭证直接写在配置文件的明文里，必须使用环境变量，存放在~/.openclaw/.env文件中
3. ❌ 禁止截图时暴露 Token、API Key、配对码
4. ✅ 定期轮换 API Key，每月检查一次使用情况，发现异常立即轮换，在模型控制台设置使用额度上限
5. ✅ 配置文件、凭证定期备份，加密存储，不要上传到 GitHub、云盘等公开平台

✅ 正确做法：所有敏感信息都通过环境变量配置，~/.openclaw/.env文件权限设为 600，仅当前用户可读写bash运行

chmod 600 ~/.openclaw/openclaw.json chmod 600 ~/.openclaw/.env chmod 700 ~/.openclaw/workspace/ 

11.4 高风险动作二次审批配置

可配置高风险命令执行前必须经过你的手动批准，避免 Agent 误执行危险操作，比如rm -rf、dd、格式化磁盘等命令。

配置方法

bash

运行

# 添加需要审批的危险命令 openclaw approvals allowlist add "rm -rf" openclaw approvals allowlist add "/usr/bin/dd" openclaw approvals allowlist add "mkfs" openclaw approvals allowlist add "sudo" # 查看当前审批配置 openclaw approvals get 

配置完成后，Agent 执行这些命令时，会先向你发送审批请求，你点击确认后，才会执行，避免误操作。

也可以通过 JSON 文件批量导入审批规则：

导入配置：bash运行

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

创建exec-approvals.json文件：json

{ "allowlist": [ "rm -rf", "/usr/bin/dd", "mkfs", "sudo", "shutdown", "reboot" ] } 

11.5 定期安全审计

执行以下命令，定期对 OpenClaw 做深度安全审计，及时发现安全隐患：

bash

运行

# 基础安全审计 openclaw security audit # 深度安全审计，全面检查配置、权限、网络、凭证 openclaw security audit --deep 

审计完成后，会列出所有安全隐患和修复建议，按提示及时修复即可。

第十二章 日常维护 & 版本管理

12.1 日常状态检查清单

12.2 日志管理 & 错误排查

bash

运行

# 实时查看运行日志，排查问题必备 openclaw logs --follow # 实时查看日志，只过滤错误和警告 openclaw logs --follow | grep -i "error\|warning\|unauthorized" # 查看最近100行日志 openclaw logs --limit 100 # 查看最近1小时的日志 openclaw logs --since 3600000 # 清理7天前的旧日志 find /tmp/openclaw -name "openclaw-*.log" -mtime +7 -delete 

12.3 配置备份 & 恢复方案

手动备份

bash

运行

# 备份主配置文件 cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.$(date +%Y%m%d) # 备份环境变量和凭证 cp -r ~/.openclaw/credentials/ ~/.openclaw/backup/credentials-$(date +%Y%m%d) cp ~/.openclaw/.env ~/.openclaw/backup/.env.backup.$(date +%Y%m%d) # 备份整个工作区 tar -czvf ~/openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/ --exclude='*.log' --exclude='sessions/' 

自动备份（定时任务）

1. 给脚本添加执行权限：chmod +x ~/.openclaw/backup.sh

添加定时任务，每天凌晨 2 点自动备份：bash运行

crontab -e # 添加以下内容 0 2 * * * ~/.openclaw/backup.sh >> ~/.openclaw/backup.log 2>&1 

创建备份脚本~/.openclaw/backup.sh：bash运行

#!/bin/bash BACKUP_DIR=~/openclaw-backups mkdir -p $BACKUP_DIR DATE=$(date +%Y%m%d) # 备份配置 cp ~/.openclaw/openclaw.json $BACKUP_DIR/openclaw.json.backup.$DATE cp ~/.openclaw/.env $BACKUP_DIR/.env.backup.$DATE tar -czvf $BACKUP_DIR/openclaw-full-backup-$DATE.tar.gz ~/.openclaw/ --exclude='*.log' --exclude='sessions/' # 保留最近30天的备份 find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete 

恢复方案

bash

运行

# 恢复配置文件 cp ~/openclaw-backups/openclaw.json.backup.20260204 ~/.openclaw/openclaw.json # 恢复完整备份 tar -xzvf ~/openclaw-backups/openclaw-full-backup-20260204.tar.gz -C ~/ # 重启网关生效 openclaw gateway restart 

12.4 版本更新流程（无痛升级）

OpenClaw 更新频繁，建议每月更新一次，获取最新功能和 bug 修复，更新前务必备份配置。

标准更新流程

bash

运行

# 1. 停止网关服务 openclaw gateway stop # 2. 备份配置（必做） cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.before-update # 3. 执行更新（一键脚本安装的用户） curl -fsSL https://openclaw.ai/install.sh | bash # NPM安装的用户执行：npm install -g openclaw@latest # 4. 运行诊断，修复配置兼容问题 openclaw doctor --fix # 5. 重启网关服务 openclaw gateway start # 6. 验证更新成功，查看新版本号 openclaw --version openclaw status 

大版本升级注意事项

1. 大版本更新前，先查看官方更新日志，确认是否有破坏性变更
2. 先在测试环境验证，再更新生产环境
3. 升级后，必须执行openclaw doctor --fix修复配置兼容性问题
4. 若升级后出现异常，可通过备份的配置文件回滚到之前的版本。

12.5 监控告警配置（可选）

适合服务器 7×24 小时部署的用户，配置监控脚本，网关异常时自动重启并告警。

1. 给脚本添加执行权限：chmod +x ~/.openclaw/monitor.sh

添加定时任务，每小时执行一次：bash运行

crontab -e # 添加以下内容 0 * * * * ~/.openclaw/monitor.sh 

创建监控脚本~/.openclaw/monitor.sh：bash运行

#!/bin/bash LOG_FILE=~/.openclaw/monitor.log echo "=== $(date) ===" >> $LOG_FILE # 检查网关状态 if ! openclaw gateway status | grep -q "running"; then echo "⚠️ Gateway 未运行，尝试重启..." >> $LOG_FILE openclaw gateway restart >> $LOG_FILE 2>&1 # 重启后再次检查 sleep 5 if openclaw gateway status | grep -q "running"; then echo "✅ Gateway 重启成功" >> $LOG_FILE else echo "❌ Gateway 重启失败，请手动排查" >> $LOG_FILE # 可在这里添加邮件/企业微信/飞书告警通知 fi fi # 健康检查 if ! openclaw health | grep -q "Model API: ✓ accessible"; then echo "⚠️ 模型API调用异常，请检查API Key和网络" >> $LOG_FILE fi 

12.6 垃圾清理 & 空间优化

bash

运行

# 清理7天前的旧日志 find /tmp/openclaw -name "openclaw-*.log" -mtime +7 -delete # 清理临时文件 rm -rf ~/.openclaw/tmp/* # 清理过期会话缓存（保留最近30天） find ~/.openclaw/agents/*/sessions/ -mtime +30 -delete # 清理npm缓存 npm cache clean --force 

第十三章 80% 新手问题全排查（分场景故障解决）

遇到问题时，先执行openclaw doctor --fix，可自动修复 80% 的常见问题，若无法解决，再按以下场景排查。

场景 1：安装后提示command not found

核心原因：npm 全局安装目录不在系统 PATH 环境变量中排查 & 解决步骤：

1. 若找不到安装路径，重新执行安装命令，查看安装过程中是否有报错，大概率是 Node.js 版本过低，升级到 22 + 版本后重新安装。

若能找到安装路径，将路径添加到系统 PATH 中bash运行

# macOS/Linux/WSL2 export PATH="$(npm prefix -g)/bin:$PATH" # 永久生效 echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc source ~/.zshrc # Windows PowerShell $npmPath = npm prefix -g $env:Path += ";$npmPath" # 永久生效 [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$npmPath", "User") 

先查找 openclaw 的安装位置bash运行

# macOS/Linux/WSL2 which openclaw find /usr -name openclaw -type f 2>/dev/null find ~/.npm -name openclaw -type f 2>/dev/null # Windows PowerShell where.exe openclaw 

场景 2：Gateway 网关启动失败

排查 & 解决步骤：

1. 常见报错 3：Node.js 版本过低执行node -v，确认版本≥22.0.0，低于该版本请升级 Node.js
2. 常见报错 4：网络代理问题海外模型用户需确认代理配置正确，执行curl https://api.anthropic.com/v1/messages --head验证网络连通性
3. 常见报错 5：后台服务启动失败
   • macOS：查看 LaunchAgent 状态launchctl list | grep openclaw，查看系统日志log show --predicate 'process == "openclaw"' --last 5m，重新安装守护进程openclaw configure --section gateway，选择重新安装 daemon
   • Linux/WSL2：查看 systemd 服务状态systemctl --user status openclaw-gateway，确认已启用 systemd，启用 lingeringsudo loginctl enable-linger $USER，避免用户登出后服务停止。

常见报错 2：配置文件 JSON 格式错误bash运行

# 运行诊断，检查配置文件 openclaw doctor # 若提示JSON格式错误，修复配置文件语法，或重置配置 openclaw reset # 选择"Config only"，仅重置配置，保留凭证和会话 

常见报错 1：Error: Port 18789 is already in use（端口被占用）bash运行

# 查看占用端口的进程 # macOS/Linux/WSL2 lsof -i :18789 # Windows PowerShell netstat -ano | findstr :18789 # 解决方法1：杀死占用进程（替换为实际PID） kill -9 12345 # Linux/macOS Stop-Process -Id 12345 -Force # Windows # 解决方法2：更换端口启动 openclaw config set gateway.port 18790 openclaw gateway restart 

前台启动网关，查看详细报错信息bash运行

openclaw gateway run --port 18789 --verbose 

场景 3：发消息给 Bot 完全没反应

排查 & 解决步骤（按顺序执行）：

1. 第四步：确认用户在白名单内检查配置文件中的allowFrom，确认你的手机号 / 用户 ID 已添加到白名单，或配置的免配对规则正确。
2. 第五步：检查网络连通性
   • Telegram/WhatsApp 需确认网络可正常访问对应平台 API，国内用户需配置代理
3. 第六步：确认模型 API 正常执行openclaw health，确认模型 API 可正常调用，若 API 报错，检查 API Key 是否有效、是否有额度、网络是否正常。

查看实时日志，确认消息是否到达网关bash运行

openclaw logs --follow | grep -i "channel\|message" 

第三步：确认配对已批准（90% 新手的问题）bash运行

# 查看待处理的配对请求 openclaw pairing list telegram # 替换为你的渠道 # 若有pending的配对请求，批准配对 openclaw pairing approve telegram <配对码> 

第二步：确认渠道已正常连接bash运行

# 查看渠道状态，探测连通性 openclaw channels status --probe # 若显示disconnected，重新配置渠道Token，重启网关 openclaw configure --section channels.telegram openclaw gateway restart 

第一步：确认网关正常运行bash运行

openclaw gateway status # 若未运行，启动网关 openclaw gateway start 

场景 4：能回复，但一执行就报错

排查 & 解决步骤：

1. 第一步：确认工具权限已开放检查配置文件中的tools.allow，确认对应的工具已在允许列表中，比如执行终端命令需要开放exec工具。
2. 第三步：常见报错：Permission denied（权限不足）
   • 确认 Agent 有对应目录的读写权限，通过bindMounts挂载需要访问的目录
   • 确认系统用户对文件 / 目录有操作权限，不要操作 root 权限的系统目录
   • 确认已安装 Chrome/Chromium 浏览器

第五步：查看详细报错日志bash运行

openclaw logs --follow | grep -i "error\|tool\|exec" 

根据日志中的具体报错，修复对应问题。

第四步：常见报错：浏览器启动失败bash运行

# 验证浏览器安装 google-chrome --version chromium --version # 未安装则执行安装 # macOS brew install --cask google-chrome # Linux/Ubuntu sudo apt-get update && sudo apt-get install chromium-browser 

第二步：确认沙箱权限配置正确bash运行

# 查看当前沙箱权限 openclaw sandbox explain # 若权限不足，修改沙箱配置，开放对应的目录访问权限 

场景 5：模型 API 调用失败

排查 & 解决步骤：

1. 常见报错 1：401 Unauthorized（未授权）
   • 确认 API Key 已正确配置，没有多余的空格、换行
   • 确认 API Key 未过期、未被吊销，在模型控制台验证 Key 有效性
   • 确认使用了正确的 API Key，不要混用 Kimi 和 Kimi Coding 的 Key
2. 常见报错 2：403 Forbidden（禁止访问）
   • 确认 API Key 有对应模型的访问权限
   • 确认没有使用 Claude Pro/Max 订阅密钥，必须使用按量付费的 API Key
   • 确认账户没有欠费、被封禁
3. 常见报错 3：请求超时 / 网络不可达
   • 海外模型用户确认代理配置正确，网络可正常访问 API 端点
   • 国内 Kimi 用户确认 baseUrl 配置为https://api.moonshot.cn/v1，不要用海外地址
4. 常见报错 4：额度不足 / 速率限制
   • 确认账户有足够的 API 额度，在模型控制台查看使用情况
   • 降低调用频率，避免触发速率限制，在模型控制台设置额度上限。

执行 curl 命令，直接测试 API 连通性bash运行

# 测试Kimi API curl https://api.moonshot.cn/v1/chat/completions \ -H "Authorization: Bearer 你的Kimi API Key" \ -H "Content-Type: application/json" \ -d '{"model":"kimi-k2.5","messages":[{"role":"user","content":"hi"}],"max_tokens":10}' 

执行健康检查，查看具体报错信息bash运行

openclaw health 

场景 6：国内网络相关问题

排查 & 解决步骤：

1. 优先使用国内模型（Kimi/MiniMax/ 智谱 GLM），无需代理，网络更稳定
2. WSL2 用户需注意：WSL2 的代理地址要填写 Windows 主机的 IP，不能用 127.0.0.1，同时 Windows 防火墙要放行对应端口。

若终端代理生效，但 OpenClaw 还是无法访问，直接在配置文件中设置代理bash运行

openclaw config set gateway.proxy.url "http://127.0.0.1:7890" openclaw gateway restart 

若使用海外模型，必须配置系统代理，且终端代理生效bash运行

# 确认代理环境变量已设置 env | grep -E "(HTTPS_PROXY|HTTP_PROXY)" # 测试代理是否生效 curl https://api.anthropic.com/v1/messages --head 

场景 7：macOS/Linux 后台服务启动失败

macOS 排查步骤：

1. 常见问题 & 解决：
   • 权限不足：在「系统设置 > 隐私与安全性」中给终端 / OpenClaw 授权完全磁盘访问权限
   • 环境变量未加载：确认~/.openclaw/.env文件存在，API Key 已正确写入
   • 重新安装守护进程：openclaw configure --section gateway，选择重新安装 daemon

查看系统日志，定位报错原因bash运行

openclaw logs --follow log show --predicate 'process == "openclaw"' --last 5m 

查看 LaunchAgent 状态bash运行

launchctl list | grep openclaw 

Linux/WSL2 排查步骤：

1. 常见问题 & 解决：
   • 找不到 openclaw 命令：systemd 服务未加载用户 PATH，编辑服务文件，添加正确的 PATH 环境变量
   • 用户登出后服务停止：启用 lingeringsudo loginctl enable-linger $USER
   • 重新安装守护进程：openclaw configure --section gateway，选择重新安装 daemon

查看 systemd 服务状态bash运行

systemctl --user status openclaw-gateway 

场景 8：紧急恢复方案

若出现配置混乱、无法启动、未知错误，可按以下步骤紧急恢复：

若仍有问题，恢复备份的配置文件，重启网关bash运行

cp ~/.openclaw/openclaw.json.emergency ~/.openclaw/openclaw.json openclaw gateway start 

重新执行初始化配置bash运行

openclaw onboard 

重置配置，保留工作区和凭证bash运行

openclaw reset # 选择"Config only"，仅重置配置 

备份当前配置（必做，避免丢失凭证）bash运行

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.emergency cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.emergency 

停止网关服务bash运行

openclaw gateway stop 

第十四章 常用命令大全（速查手册）

基础管理命令

Gateway 网关命令

配置管理命令

模型管理命令

渠道管理命令

配对管理命令

会话 / 代理管理命令

技能管理命令

诊断 / 日志命令

第十五章 官方资源 & 社区支持

1. 官方网站：https://openclaw.ai/
2. 官方中文文档：https://docs.openclaw.ai/zh-CN
3. 官方 GitHub 仓库：https://github.com/openclaw/openclaw
4. 官方 Discord 社区：discord.com/invite/clawd
5. 中文社区文档：https://www.moltcn.com/
6. 平台特定文档：
   • Windows/WSL2：https://docs.openclaw.ai/platforms/windows
   • macOS：https://docs.openclaw.ai/platforms/macos
   • Linux：https://docs.openclaw.ai/platforms/linux