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

本文为OpenClaw 2026最新优化版保姆级教程，从架构原理、环境准备、多方式安装、初始化配置展开，详解国内大模型接入、多聊天渠道配对、网关管理与Web界面使用，覆盖基础功能、进阶玩法，强化安全加固、日常维护与全场景故障排查，含常用命令速查，新手20分钟可跑通最小闭环，助力高效使用这款开源自托管AI智能体。

hahaleung

156人浏览 · 2026-03-04 19:22:07

hahaleung · 2026-03-04 19:22:07 发布

本教程基于官方最新文档、社区博客实战指南优化编写，覆盖从架构理解、环境准备、安装配置、渠道接入到日常使用、安全加固、故障排查的全流程，重点补充国内用户适配方案、新手避坑指南、全场景问题排查，新手跟着步骤走，20 分钟即可跑通最小可用闭环。

前置快速通关路径（20 分钟极速体验）

如果你只想最快跑通核心流程，直接按以下 4 步操作，无需提前阅读全文，后续可回头补全细节：

一键安装：macOS/Linux/WSL2 终端执行 curl -fsSL https://openclaw.ai/install.sh | bash；Windows 管理员 PowerShell 执行 iwr -useb https://openclaw.ai/install.ps1 | iex
初始化配置：执行 openclaw onboard --install-daemon，跟着向导选「本地模式」、配置 AI 模型 API Key、选择 Telegram 渠道、安装后台守护进程
安全配对：给 Telegram 机器人发第一条消息，终端执行 openclaw pairing list telegram 查看配对码，执行 openclaw pairing approve telegram <配对码> 完成授权
测试验证：给机器人发送「你是谁，用 3 句话介绍自己」，收到回复即跑通闭环，可开始正常使用。

第一章先搞懂 OpenClaw：核心定位 & 架构原理

1.1 核心定位

OpenClaw 是一款开源自托管的 AI 个人智能体，区别于只能给建议的对话式 AI，它的核心能力是「发一句话，就帮你在本机 / 服务器上真实执行任务」。

入口：微信、Telegram、WhatsApp、Discord 等你常用的聊天软件
大脑：支持 Claude、GPT、Kimi、智谱 GLM 等云端 API，也支持 Ollama 本地大模型
双手：可执行终端命令、读写文件、控制浏览器、管理邮件日历、运行脚本等操作
记忆：跨会话保存上下文与配置，越用越贴合你的使用习惯

1.2 核心架构全景（新手必看，少走 90% 弯路）

一次完整的指令执行，会经过以下核心组件，理解每个组件的作用，出问题可快速定位故障点：

plaintext

你常用的聊天App（Telegram/WhatsApp等）【消息入口Channels】
            ↓（消息流入/流出）
Gateway网关【唯一总机，管理所有连接、认证、消息路由】
            ↓（RPC调用）
Agent智能体运行时【理解指令、调用模型、执行工具、维护会话上下文】
            ↓（工具调用）
内置工具/技能插件【浏览器/终端/文件管理/邮件/日历等扩展能力】
            ↓（模型调用）
AI大模型提供商【Claude/GPT/Kimi/本地模型】

关键名词解释

表格

名词	核心作用	新手通俗理解
Gateway	唯一常驻后台进程，管理所有聊天渠道、消息路由、认证授权，默认端口 18789	相当于总机，所有消息都要经过它中转
Agent	智能体运行时，负责对话逻辑、工具调用、上下文维护，可配置多个独立 Agent	相当于接线员 + 执行者，负责理解需求并干活
Channels	消息入口渠道，即你用来发指令的聊天软件（Telegram/WhatsApp 等）	你给智能体打电话的手机
Session	会话上下文容器，跨消息保存对话历史，默认按发送者隔离	你和接线员的通话记录
Workspace	Agent 的工作目录，存放生成的文件、脚本、配置模板	执行者的办公文件夹
Pairing	安全配对机制，陌生用户发消息需你手动批准，防止机器人被滥用	来电防火墙，只接你批准的号码
Skills	技能插件，扩展 OpenClaw 的能力，比如邮件管理、智能家居控制	给执行者新增的专业技能

1.3 新手使用的正确心态

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

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

2.1 系统与硬性要求

表格

系统	推荐配置	注意事项
macOS	macOS 14+，内存≥4GB，磁盘≥5GB	需安装 Xcode Command Line Tools（源码构建时）
Windows	强烈推荐 WSL2（Ubuntu 22.04+），原生 Windows 支持有限	原生 Windows 工具兼容性差，大概率会出现未知问题
Linux	Ubuntu/Debian/Fedora/Arch 等主流发行版，内置 systemd，内存≥4GB	适合 7×24 小时服务器部署

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 用户必看）

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

powershell

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

重启电脑，再次以管理员身份打开 PowerShell，设置 WSL2 为默认版本
powershell
```
wsl --set-default-version 2
```
打开 Microsoft Store，搜索「Ubuntu 22.04 LTS」，点击安装，安装完成后启动 Ubuntu，设置用户名和密码
开启 systemd（后台服务必备），在 Ubuntu 终端执行
bash

运行
```
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF
```
关闭 PowerShell，执行wsl --shutdown，重新打开 Ubuntu 终端，执行systemctl --user status验证 systemd 正常运行
按上文 Node.js 安装步骤，在 Ubuntu 终端内安装 Node.js 22 + 版本

2.3 AI 模型 API Key 准备

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

海外模型：Anthropic Claude（推荐）、OpenAI GPT 系列，需前往对应官网控制台创建按量付费 API Key（禁止使用 Claude Pro/Max 订阅密钥，违反服务条款）
国内模型：Moonshot Kimi、MiniMax、智谱 GLM，国内网络可直连，无需代理，下文有完整接入教程
本地模型：提前安装 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 新手安装避坑指南

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

访问Moonshot 开放平台，注册并登录账号
进入控制台 → API Keys，点击「创建 API Key」，设置名称后，复制完整的 Key（格式为sk-xxx）
重要提醒：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 模型列表

表格

模型 ID	名称	思考能力	上下文窗口	适用场景
moonshot/kimi-k2.5	Kimi K2.5	❌	256K	通用场景，新手首选
moonshot/kimi-k2-turbo-preview	Kimi K2 Turbo	❌	256K	快速响应，低成本场景
moonshot/kimi-k2-thinking	Kimi K2 Thinking	✅	256K	复杂推理、代码开发场景
moonshot/kimi-k2-thinking-turbo	Kimi K2 Thinking Turbo	✅	256K	快速推理场景

模型切换方法

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

5.2 其他国内模型配置

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

5.3 本地 Ollama 模型接入教程

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

提前安装 Ollama，执行ollama run 模型名称（比如llama3），确保本地模型正常运行

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

json

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

保存配置，执行openclaw gateway restart重启网关，执行openclaw health验证模型连通性。

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

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

6.1 网关的运行方式

表格

运行方式	命令	适用场景
前台运行（调试用）	`openclaw gateway run --port 18789 --verbose`	排查问题时使用，可实时看到日志，按 Ctrl+C 停止
后台启动（常驻运行）	`openclaw gateway start`	日常使用，关闭终端也能运行，需先安装守护进程
停止网关	`openclaw gateway stop`	停止后台运行的网关
重启网关	`openclaw gateway restart`	修改配置后，必须重启网关才能生效
查看网关状态	`openclaw gateway status`	查看网关是否正常运行、PID、端口等信息

6.2 网关启动后的必做验证

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

bash

运行

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

6.3 Web 控制界面使用

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

本地默认访问地址：http://127.0.0.1:18789/
快速打开命令：终端执行openclaw dashboard，会自动打开浏览器并跳转到仪表板
核心功能模块：
- 聊天面板：直接在浏览器中与智能体对话，测试所有能力
- 渠道管理：可视化添加、配置、管理所有聊天渠道，无需敲命令
- 会话管理：查看、隔离、重置不同用户的会话上下文
- 配置管理：可视化修改所有配置项，自动校验格式，避免手动编辑 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 渠道接入前置说明

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

7.2 Telegram Bot 从零接入全流程

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

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

打开 Telegram，搜索@BotFather（带官方蓝标认证），点击进入
发送/newbot命令，跟着提示设置机器人名称、用户名（用户名必须以bot结尾）
创建完成后，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：安全配对（最关键，否则发消息没反应）

打开 Telegram，搜索你创建的机器人用户名，点击进入，发送第一条消息（比如「你好」）
机器人会自动回复一个 8 位配对码，不会响应其他内容
回到终端，执行以下命令，查看待处理的配对请求：
bash

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

运行
```
openclaw pairing approve telegram <你的配对码>
```
终端提示✓ Pairing approved，即配对完成，回到 Telegram，重新发送消息，机器人就会正常响应了。

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

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

编辑~/.openclaw/openclaw.json配置文件

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

json

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

保存配置，重启网关生效，白名单内的用户无需配对，直接发送消息即可响应。

步骤 5：群聊配置

把机器人邀请到你的 Telegram 群组中，给机器人管理员权限（至少需要发送消息、读取消息权限）

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

json

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

保存配置，重启网关生效，群聊中必须 @机器人，才会响应，避免误触发。

7.3 WhatsApp 接入步骤

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

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

7.4 Discord 接入步骤

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

7.5 iMessage 接入（仅 macOS）

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

运行
```
brew install keith/formulae/imsg
```
执行openclaw configure --section channels.imessage，完成配置
给你的 iMessage 账号发送消息，完成配对批准后，即可正常使用。

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

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

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

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

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

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

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

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

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

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

8.3 官方自检三连（必跑）

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

bash

运行

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

8.4 新手最佳实践

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

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

9.1 基础触发规则

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

9.2 媒体文件使用

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

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

9.3 高频场景指令示例

表格

场景	指令示例
系统操作	帮我列出当前电脑桌面的所有文件，按文件大小排序，标注每个文件的修改时间
代码开发	帮我写一个 Python 爬虫，抓取某网站的公开文章标题、发布时间、链接，保存到 Excel 文件，要求加入异常处理，避免被反爬
代码优化	帮我优化这段 PostgreSQL 查询语句，分析执行计划，添加合适的索引，把查询耗时从 8s 降到 100ms 以内
浏览器自动化	帮我打开 Chrome 浏览器，访问某购物网站，筛选价格 100-300 元的商品，按销量排序，截图前 10 个商品的信息，保存到工作目录
邮件管理	帮我读取今天的收件箱，把促销类、广告类邮件标为已读并归档，把工作相关的重要邮件整理成摘要，按优先级排序
运维部署	帮我写一个 K8s 部署配置文件，完成 3 个微服务的部署、ingress 配置、健康检查，注释每一项的作用
文档处理	帮我润色这份工作总结，优化语言逻辑，突出工作成果和数据亮点，适配正式的年终汇报场景，控制在 3000 字以内
安全审计	帮我对这段代码做安全审计，找出 SQL 注入、XSS 等安全漏洞，给出修复方案和完整的修复代码

9.4 内置工具使用

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

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

9.5 技能插件安装 & 使用

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

安装方法

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

命令行安装：

bash

运行

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

新手推荐技能

表格

技能名称	核心作用
gmail	邮件管理，读取、发送、归档、筛选邮件
calendar	日历管理，创建、查看、修改日程，设置提醒
web-search	网页搜索，支持 Brave Search，获取实时网络信息
github	GitHub 管理，查看 Issue、提交 PR、管理仓库
home-assistant	智能家居控制，对接 Home Assistant

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

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 点清邮件、每周五生成数据报告、每天凌晨备份文件等。

配置方法：

编辑~/.openclaw/openclaw.json配置文件，添加cron配置项

示例：每天 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（官方推荐，最简单安全）

在网关设备和访问设备上安装 Tailscale，完成组网
终端执行以下命令，配置网关绑定 Tailscale 网络：
bash

运行
```
openclaw config set gateway.bind tailnet
openclaw gateway restart
```
组网内的所有设备，都可以通过 Tailscale 分配的 IP+18789 端口，安全访问 Web 仪表板和网关服务。

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

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

运行
```
ssh -N -L 18789:127.0.0.1:18789 你的服务器用户名@服务器IP
```
隧道建立后，本地浏览器访问http://127.0.0.1:18789/，即可安全访问远程服务器上的 OpenClaw 仪表板。

10.4 移动节点配对

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

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

10.5 自定义技能开发入门

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

官方技能开发文档：https://docs.openclaw.ai/tools/skills
基础技能结构：每个技能包含一个index.js入口文件、package.json依赖配置、README.md说明文档
开发完成后，可通过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 网络安全加固

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

bash

运行

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

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

bash

运行

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

11.3 敏感信息管理规范

❌ 禁止在聊天对话中直接发送 API Key、密码、Token 等敏感信息
❌ 禁止把 API Key、凭证直接写在配置文件的明文里，必须使用环境变量，存放在~/.openclaw/.env文件中
❌ 禁止截图时暴露 Token、API Key、配对码
✅ 正确做法：所有敏感信息都通过环境变量配置，~/.openclaw/.env文件权限设为 600，仅当前用户可读写
bash

运行
```
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/.env
chmod 700 ~/.openclaw/workspace/
```
✅ 定期轮换 API Key，每月检查一次使用情况，发现异常立即轮换，在模型控制台设置使用额度上限
✅ 配置文件、凭证定期备份，加密存储，不要上传到 GitHub、云盘等公开平台

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 文件批量导入审批规则：

创建exec-approvals.json文件：

json

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

导入配置：

bash

运行

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

11.5 定期安全审计

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

bash

运行

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

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

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

12.1 日常状态检查清单

表格

检查频率	检查命令	检查目的
每日	`openclaw status` `openclaw health`	确认网关、模型、渠道正常运行
每周	`openclaw status --all` `openclaw doctor`	全面检查系统状态，自动修复常见问题
每周	`openclaw logs --limit 500	grep -i error`	查看错误日志，及时发现潜在问题
每月	`openclaw security audit --deep`	安全审计，修复安全隐患
每月	检查模型 API 使用额度	避免额度超额，及时发现异常调用

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/'

自动备份（定时任务）

创建备份脚本~/.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

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

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

bash

运行

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

恢复方案

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

大版本升级注意事项

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

12.5 监控告警配置（可选）

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

创建监控脚本~/.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

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

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

bash

运行

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

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 环境变量中排查 & 解决步骤：

先查找 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

若能找到安装路径，将路径添加到系统 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")

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

场景 2：Gateway 网关启动失败

排查 & 解决步骤：

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

运行
```
openclaw gateway run --port 18789 --verbose
```

常见报错 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

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

bash

运行

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

常见报错 3：Node.js 版本过低执行node -v，确认版本≥22.0.0，低于该版本请升级 Node.js
常见报错 4：网络代理问题海外模型用户需确认代理配置正确，执行curl https://api.anthropic.com/v1/messages --head验证网络连通性
常见报错 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，避免用户登出后服务停止。

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

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

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

bash

运行

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

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

bash

运行

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

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

bash

运行

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

第四步：确认用户在白名单内检查配置文件中的allowFrom，确认你的手机号 / 用户 ID 已添加到白名单，或配置的免配对规则正确。
第五步：检查网络连通性
- Telegram/WhatsApp 需确认网络可正常访问对应平台 API，国内用户需配置代理
- 查看实时日志，确认消息是否到达网关
  bash
  
  运行
```
openclaw logs --follow | grep -i "channel\|message"
```
第六步：确认模型 API 正常执行openclaw health，确认模型 API 可正常调用，若 API 报错，检查 API Key 是否有效、是否有额度、网络是否正常。

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

排查 & 解决步骤：

第一步：确认工具权限已开放检查配置文件中的tools.allow，确认对应的工具已在允许列表中，比如执行终端命令需要开放exec工具。

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

bash

运行

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

第三步：常见报错：Permission denied（权限不足）
- 确认 Agent 有对应目录的读写权限，通过bindMounts挂载需要访问的目录
- 确认系统用户对文件 / 目录有操作权限，不要操作 root 权限的系统目录

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

确认已安装 Chrome/Chromium 浏览器

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 logs --follow | grep -i "error\|tool\|exec"
```
根据日志中的具体报错，修复对应问题。

场景 5：模型 API 调用失败

排查 & 解决步骤：

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

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

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

排查 & 解决步骤：

优先使用国内模型（Kimi/MiniMax/ 智谱 GLM），无需代理，网络更稳定

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

bash

运行

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

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

运行
```
openclaw config set gateway.proxy.url "http://127.0.0.1:7890"
openclaw gateway restart
```
WSL2 用户需注意：WSL2 的代理地址要填写 Windows 主机的 IP，不能用 127.0.0.1，同时 Windows 防火墙要放行对应端口。

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

macOS 排查步骤：

查看 LaunchAgent 状态
bash

运行
```
launchctl list | grep openclaw
```

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

bash

运行

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

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

Linux/WSL2 排查步骤：

查看 systemd 服务状态

bash

运行

systemctl --user status openclaw-gateway

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

场景 8：紧急恢复方案

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

停止网关服务
bash

运行
```
openclaw gateway stop
```

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

bash

运行

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

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

bash

运行

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

重新执行初始化配置
bash

运行
```
openclaw onboard
```

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

bash

运行

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

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

基础管理命令

表格

命令	核心作用
`openclaw --version`	查看当前版本号
`openclaw --help`	查看帮助文档，所有命令用法
`openclaw status`	查看核心状态概览
`openclaw status --all`	查看全量详细状态，调试必备
`openclaw health`	健康检查，验证网关、模型、渠道
`openclaw doctor`	自动诊断常见问题
`openclaw doctor --fix`	自动诊断并修复常见问题
`openclaw dashboard`	自动打开 Web 仪表板
`openclaw update`	更新 OpenClaw 到最新版本

Gateway 网关命令

表格

命令	核心作用
`openclaw gateway start`	后台启动网关服务
`openclaw gateway stop`	停止后台网关服务
`openclaw gateway restart`	重启网关服务（修改配置后必执行）
`openclaw gateway status`	查看网关运行状态、PID、端口
`openclaw gateway run --verbose`	前台运行网关，实时输出日志，调试必备
`openclaw gateway install`	安装网关后台守护进程
`openclaw gateway uninstall`	卸载网关后台守护进程

配置管理命令

表格

命令	核心作用
`openclaw configure`	进入交互式配置界面，修改所有配置
`openclaw configure --section xxx`	配置指定模块，比如 channels.telegram
`openclaw config get`	查看完整的配置文件
`openclaw config get xxx`	查看指定配置项，比如 gateway.port
`openclaw config set xxx yyy`	设置指定配置项的值
`openclaw config unset xxx`	删除指定配置项
`openclaw reset`	重置配置，可选择仅重置配置或全量重置

模型管理命令

表格

命令	核心作用
`openclaw models list`	查看所有可用的模型列表
`openclaw models status`	查看当前默认模型的状态
`openclaw models scan`	扫描可用的模型，包括本地 Ollama 模型
`openclaw models set 模型ID`	设置默认模型
`openclaw models probe 模型ID`	测试指定模型的连通性

渠道管理命令

表格

命令	核心作用
`openclaw channels login`	渠道登录，主要用于 WhatsApp 扫码登录
`openclaw channels logout`	退出渠道登录
`openclaw channels list`	查看所有已配置的渠道列表
`openclaw channels status`	查看所有渠道的运行状态
`openclaw channels status --probe`	探测所有渠道的连通性

配对管理命令

表格

命令	核心作用
`openclaw pairing list 渠道名`	查看指定渠道的待处理配对请求
`openclaw pairing approve 渠道名配对码`	批准指定配对请求
`openclaw pairing deny 渠道名配对码`	拒绝指定配对请求
`openclaw pairing list --all`	查看所有渠道的配对请求

会话 / 代理管理命令

表格

命令	核心作用
`openclaw agents list`	查看所有已配置的 Agent 列表
`openclaw agents add 代理名 --workspace 路径`	添加新的 Agent
`openclaw agents status 代理名`	查看指定 Agent 的状态
`openclaw agent --agent 代理名 --message "xxx"`	给指定 Agent 发送测试消息
`openclaw sessions list`	查看所有活跃会话
`openclaw sessions history 会话ID`	查看指定会话的历史记录
`openclaw sessions reset 会话ID`	重置指定会话的上下文

技能管理命令

表格

命令	核心作用
`openclaw skills list`	查看所有已安装的技能列表
`openclaw skills install 技能名`	安装指定技能
`openclaw skills uninstall 技能名`	卸载指定技能
`openclaw skills config 技能名`	配置指定技能
`openclaw skills update 技能名`	更新指定技能到最新版本
`openclaw skills update --all`	更新所有已安装的技能

诊断 / 日志命令

表格

命令	核心作用
`openclaw logs --follow`	实时查看运行日志，排查问题必备
`openclaw logs --limit 100`	查看最近 100 行日志
`openclaw logs --since 3600000`	查看最近 1 小时的日志
`openclaw security audit`	基础安全审计
`openclaw security audit --deep`	深度安全审计
`openclaw sandbox explain`	查看当前沙箱权限配置
`openclaw approvals get`	查看高风险命令审批配置

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

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

2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

How Does GG3M Think Tank Influence Global Military, International Politics & International Strategy?

2048 AI社区

2026实测｜3款优质PPT工具排名推荐，AI赋能高效出稿，小白也能轻松拿捏专业感

2048 AI社区

甩个Excel进去就能出报表？企业AI数据查询（NL2SQL）的正确打开方式

2048 AI社区

所有评论(0)

查看更多评论

hahaleung

@hahaleung

已为社区贡献1条内容

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

hahaleung

前置快速通关路径（20 分钟极速体验）

第一章 先搞懂 OpenClaw：核心定位 & 架构原理

1.1 核心定位

1.2 核心架构全景（新手必看，少走 90% 弯路）

关键名词解释

1.3 新手使用的正确心态

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

2.1 系统与硬性要求

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

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

可选依赖

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

2.3 AI 模型 API Key 准备

2.4 国内用户网络环境准备

2.5 30 秒环境自检

第三章 OpenClaw 全方式安装教程

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

macOS / Linux / WSL2

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

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

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

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

1. 验证安装成功

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

3.5 新手安装避坑指南

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

4.1 启动配置向导

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

步骤 1：选择配置模式

步骤 2：处理现有配置

步骤 3：选择 Gateway 运行模式

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

步骤 5：Workspace 工作目录配置

步骤 6：Gateway 网关配置

步骤 7：聊天渠道配置

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

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

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

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

4.4 后续配置修改

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

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

步骤 1：获取 Kimi API Key

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

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

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

可用 Kimi 模型列表

模型切换方法

5.2 其他国内模型配置

5.3 本地 Ollama 模型接入教程

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

6.1 网关的运行方式

6.2 网关启动后的必做验证

6.3 Web 控制界面使用

6.4 网关常见配置修改

1. 修改端口

2. 修改绑定地址

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

7.1 渠道接入前置说明

7.2 Telegram Bot 从零接入全流程

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

步骤 2：接入 OpenClaw

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

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

步骤 5：群聊配置

7.3 WhatsApp 接入步骤

7.4 Discord 接入步骤

7.5 iMessage 接入（仅 macOS）

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

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

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

8.3 官方自检三连（必跑）

8.4 新手最佳实践

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

9.1 基础触发规则

9.2 媒体文件使用

9.3 高频场景指令示例

9.4 内置工具使用

第一章先搞懂 OpenClaw：核心定位 & 架构原理

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

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

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

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

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

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

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

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

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

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

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

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

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