# 03. 快速开始指南

> **课程信息**
>
> - **作者**：老金
> - **GitHub**：https://github.com/KimYx0207
> - **公众号**：老金带你玩AI
> - **X（Twitter）**：老金带你玩AI
> - **个人博客**：https://aiking.dev
> - **难度等级**：🟢 入门
> - **阅读时间**：10 分钟
> - **前置知识**：已完成安装（[02-安装部署指南](02-安装部署指南.md)）
>
> **本篇你将学会：** 运行引导向导、启动 Gateway、发送第一条消息、基本的日常操作命令
>
> **这是最重要的一篇！** 跟着做完前 3 步，你就有一个能聊天的 AI 助手了

## 本篇你会做出什么

我把快速开始写成手把手，是因为老金见过太多工具教程只让人看懂，却没有让人真正跑起来。

跟完这一篇，你会得到一个能在浏览器里对话的本地 OpenClaw 助手：

- Gateway 正常运行。
- Control UI 可以打开。
- 能发送第一条消息并收到回复。
- 知道怎么检查 Gateway 状态。
- 失败时知道先看哪几个排查点。

先完成下面的 3 步即可。后面的 Control UI 功能介绍可以等跑通后再看。

## 5 分钟跑起第一个对话

安装完 OpenClaw 后，只需要 3 步就能开始聊天。别急，我们一步步来，每步都讲清楚。

---

### 第一步：运行引导向导

```bash
openclaw onboard --install-daemon
```

这条命令做了两件事：
- `onboard` — 启动交互式引导向导
- `--install-daemon` — 把 Gateway 注册为系统服务（开机自启）

> **v2026.6.8 提示**：如果你只输入 `openclaw`，且本机还没有 authored config，新版会进入 classic onboarding。教学里仍建议写完整命令，避免读者分不清“只启动 CLI”和“安装后台服务”的区别。快速开始后的排障优先看 Control UI Activity、transcript、Gateway 日志、插件/Skill Workshop 状态、agent run recovery 和 `openclaw doctor`，不要只凭聊天窗口是否回复来判断是否安装成功。

> 💡 **术语解释：**
> - **Gateway（网关）**：OpenClaw 的核心后台服务，负责接收你的消息、调用 AI 模型、返回回复。你可以把它理解为"AI 助手的大脑"，它在后台持续运行。
> - **daemon（守护进程）**：一种在后台默默运行的程序，不需要你手动启动，开机就自动跑起来。

向导会依次引导你完成以下配置：

**1. 选择 AI 模型提供商**

```
? Select your AI provider:
  ❯ DeepSeek（具体模型以当前目录为准）
    OpenAI（具体模型以当前目录为准）
    Anthropic（具体模型以当前目录为准）
    Google / Vertex（具体模型以当前目录为准）
    Ollama (本地模型，隐私优先)
    OpenRouter (一个 Key 用所有模型)
    其他...
```

新手建议先选你已经有账号和额度的 provider；预算有限或隐私敏感时再选 Ollama 等本地模型。不要背这里的 provider 顺序，真实列表以当前 onboarding / models 输出为准。

**2. 输入 API Key**

> 💡 **术语解释：** **API Key（API 密钥）** 是 AI 模型提供商给你的一串"通行证"字符串。有了它，OpenClaw 才能代替你调用 AI 模型。每个提供商的 Key 格式不同，注意保密，不要分享给别人。

```
? Enter your OpenAI API Key: sk-proj-xxxxx
```

API Key 会加密存储在 `~/.openclaw/openclaw.json` 中。如果你还没有 Key：
- DeepSeek: [platform.deepseek.com](https://platform.deepseek.com/)
- OpenAI: [platform.openai.com](https://platform.openai.com/)
- Anthropic: [console.anthropic.com](https://console.anthropic.com/)
- Google: [aistudio.google.com](https://aistudio.google.com/)

**3. 配置 Gateway 设置**

```
? Gateway port (default 18789):
? Set Gateway Token for security: (auto-generated)
? Enable TLS? (Y/n): Y
```

直接回车用默认值就行。Gateway Token 会自动生成一个随机字符串，用于保护你的 API 接口。

> 💡 **术语解释：**
> - **Gateway Token**：相当于你家大门的钥匙，只有拿着这个 Token 的请求才能访问你的 Gateway，防止别人未经授权使用你的 AI 服务。
> - **TLS**：一种网络加密协议，开启后你和 Gateway 之间的通信会被加密，防止被窃听。类似于浏览器地址栏的 🔒 小锁。

**4. 可选：连接消息平台**

```
? Connect a messaging platform now? (y/N):
  ❯ Skip for now
    WhatsApp
    Telegram
    Discord
    Slack
    飞书 (Feishu)
```

第一次用建议先跳过，等熟悉了再接入。后面可以随时用 `openclaw channels add` 添加。

向导完成后，你会看到：

```
✓ AI provider configured (OpenAI)
✓ Gateway Token generated
✓ Gateway daemon installed
✓ Gateway started on 127.0.0.1:18789

🦞 OpenClaw is ready! Open http://127.0.0.1:18789/ to start chatting.
```

> ✅ **检查点：** 如果你看到了 `🦞 OpenClaw is ready!` 的输出，说明一切正常。如果没有，去看 [11-常见问题FAQ](11-常见问题FAQ.md) 的 Q1-Q5。

### 第二步：检查 Gateway 状态

```bash
openclaw gateway status
```

正常输出：

```
Gateway Status: running
  PID:     12345
  Port:    18789
  Uptime:  2m 30s
  Memory:  45 MB
  Agents:  1 (main)
  Channels: 0 connected
```

看到 `running` 就说明网关已经启动了。如果显示 `stopped`，手动启动：

```bash
openclaw gateway --port 18789
```

> ✅ **检查点：** 运行 `openclaw gateway status` 后，看到 `Gateway Status: running` 就对了。如果是 `stopped` 或 `error`，参考下面的状态表格处理。

常见状态说明：

| 状态 | 含义 | 处理方式 |
|------|------|----------|
| `running` | 正常运行 | 无需操作 |
| `stopped` | 已停止 | `openclaw gateway --port 18789` |
| `error` | 启动失败 | 查看日志 `openclaw gateway --port 18789 --verbose` |
| `starting` | 正在启动 | 等待几秒后重新检查 |

### 第三步：打开 Control UI

> 💡 **术语解释：** **Control UI** 是 OpenClaw 自带的网页管理界面，在浏览器里打开就能用，不需要额外安装任何东西。你可以在这里和 AI 聊天、管理设置、查看状态。

Gateway 启动后，在浏览器中打开 `http://127.0.0.1:18789/`，这就是你的 AI 助手 Control UI。

如果浏览器没有自动打开，手动在浏览器地址栏输入 `http://127.0.0.1:18789/` 即可。

直接在输入框里打字，开始和 AI 对话。

> ✅ **检查点：** 浏览器打开后能看到一个聊天界面，输入框可以打字，说明前 3 步全部完成！你已经有一个能聊天的 AI 助手了。🎉

---

## 跑通后再看：Control UI 功能介绍

> 💡 **术语解释：**
> - **Agent（智能体）**：你的 AI 助手实例。一个 Agent 就是一个独立的 AI 角色，有自己的人格设定、记忆和工作空间。你可以创建多个 Agent 来处理不同任务。
> - **技能（Skill）**：Agent 的"超能力"插件。比如查天气、搜网页、操作文件等，每个技能让 AI 多会一样本事。

打开 `http://127.0.0.1:18789/` 后，你会看到一个简洁的 Web 界面。下面逐一介绍每个功能区域。

### 聊天界面（主页面）

这是你和 AI 对话的地方，占据了面板的主要区域。

功能特性：
- **实时流式输出** — AI 的回复逐字显示，不用等全部生成完
- **Markdown 渲染** — 代码块、表格、列表都会正确渲染
- **多轮对话** — 上下文自动保持，AI 记得你之前说了什么
- **文件上传** — 拖拽文件到输入框，AI 可以分析文件内容
- **语音输入** — 点击麦克风图标，语音转文字发送

快捷键：

| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息 |
| `Shift + Enter` | 换行（不发送） |
| `Ctrl + L` | 清空当前对话 |
| `Ctrl + K` | 打开命令面板 |
| `Ctrl + /` | 显示快捷键列表 |

### 设置面板

点击左下角的齿轮图标进入设置，包含以下配置项：

**模型设置** — 切换模型提供商、调整温度/Token 参数、配置故障转移

**平台连接** — 查看已连接平台状态、添加/移除连接、配置消息路由

**技能管理** — 查看已安装技能、启用/禁用、安装新技能

**安全设置** — Gateway Token 管理、配对审批、沙箱隔离配置

> 💡 **术语解释：** **沙箱（Sandbox）** 是一种安全隔离机制，让 AI 在一个受限的环境中执行操作，防止它误操作你的系统文件。类似于给 AI 划了一个"安全活动区"。

### 会话管理

点击左侧边栏的会话列表图标，可以查看所有对话历史、全文搜索、导出为 Markdown/JSON、删除旧对话、给对话打标签分类。

v2026.5.22 后，Control UI 的 chat session picker 更适合处理长历史：优先用搜索定位旧会话；结果很多时用 Load More 分页继续加载，不要靠浏览器滚动硬翻。排查“找不到会话”时，先确认当前 Agent、工作区和搜索关键词，再判断是否真丢失。

### 系统状态

点击左下角的状态指示灯，查看 Gateway 运行状态（CPU、内存、运行时间）、已连接平台状态、模型使用统计（API 调用次数、Token 消耗、费用估算）、Agent 列表。

---

## 第一个对话的完整流程

从配置到发送第一条消息，完整走一遍。

### 1. 确认 Gateway 正在运行

```bash
openclaw gateway status
# 确认输出包含 "running"
```

### 2. 打开 Control UI

在浏览器中打开 `http://127.0.0.1:18789/`。

### 3. 检查模型配置


在 Control UI 的设置中，确认：
- AI 提供商已选择（比如 OpenAI）
- API Key 已填写
- 模型已选择（比如 `gpt-5.2`）

也可以用命令行检查：

```bash
# 查看当前配置
openclaw config get agents.defaults.model

# 输出示例
# agents.defaults.model: anthropic/claude-opus-4-8
```

### 4. 发送第一条消息


在 Control UI 的输入框中输入：

```
你好！请做一下自我介绍。
```

AI 会流式回复，类似这样：

```
你好！我是你的 AI 助手，运行在 OpenClaw 框架上。

我可以帮你：
- 回答问题和进行对话
- 管理日程和待办事项
- 处理文件和文档
- 连接各种消息平台
- 执行自动化任务

有什么我可以帮你的吗？
```

> ✅ **检查点：** 如果 AI 回复了你的消息，OpenClaw 已经完全跑通。如果没有回复或报错，检查 API Key 是否正确：运行 `openclaw doctor` 进行诊断。

### 5. 试试工具调用


AI 不只是聊天，它还能执行操作。试试这些：

```
今天天气怎么样？
```

如果安装了 `weather` 技能，AI 会调用天气 API 返回实时天气。

```
帮我在工作空间创建一个 todo.md 文件，列出今天要做的事情。
```

AI 会使用文件工具在 `~/.openclaw/workspace/` 下创建文件。

### 6. 通过命令行发送消息

除了 Control UI，你也可以用命令行和 AI 对话：

```bash
# 发送消息并等待回复
openclaw agent --message "帮我写一个 Python 的 Hello World"

# 使用高级思考模式
openclaw agent --message "帮我写一个快速排序" --thinking high
```

在聊天界面中，你可以使用斜杠命令控制会话：

```
/status          — 查看会话状态
/new 或 /reset   — 重置会话
/compact         — 压缩会话上下文
/think high      — 设置思考级别（off|minimal|low|medium|high|xhigh）
/verbose on      — 开启详细输出
/usage tokens    — 显示 Token 使用量（off|tokens|full）
```

### 7. 发送测试消息到消息平台

如果你已经配置了消息平台（比如 WhatsApp），可以用命令行发送测试消息：

```bash
openclaw message send --to +86138xxxx0000 --message "你好，我是你的 AI 助手！"
```

---

## CLI 命令速查

OpenClaw 的命令行工具功能强大，以下是常用命令的完整参考。

### 基础命令

```bash
# 查看版本
openclaw --version

# 查看帮助
openclaw --help

# 查看子命令帮助
openclaw gateway --help

# 运行引导向导
openclaw onboard

# 查看系统状态
openclaw gateway status

# 健康检查
openclaw health

# 诊断
openclaw doctor

# 搜索文档
openclaw docs

# 终端 UI
openclaw tui
```

### Gateway 管理

```bash
openclaw gateway status                  # 查看 Gateway 状态
openclaw gateway --port 18789            # 启动 Gateway（前台运行）
openclaw gateway --port 18789 --verbose  # 启动 Gateway（详细日志）
```

### 配置管理

```bash
# 查看特定配置
openclaw config get agents.defaults.model

# 设置 / 删除配置
openclaw config set agents.defaults.model "anthropic/claude-opus-4-8"
openclaw config unset agents.defaults.model
```

### Agent 命令

```bash
openclaw agent --message "你好"                          # 发送单条消息
openclaw agent --message "帮我写代码" --thinking high    # 使用高级思考模式
```

### 聊天命令（会话内斜杠命令）

```
/status                  — 查看会话状态
/new 或 /reset           — 重置会话
/compact                 — 压缩会话上下文
/think <level>           — 设置思考级别（off|minimal|low|medium|high|xhigh）
/verbose on|off          — 详细输出开关
/usage off|tokens|full   — 使用量显示
/restart                 — 重启 Gateway
/activation mention|always — 群组激活模式
```

### 消息平台管理

```bash
# 频道管理
openclaw channels list
openclaw channels status
openclaw channels add telegram
openclaw channels remove telegram
openclaw channels login telegram
openclaw channels logout telegram

# 发送消息
openclaw message send --to +86138xxxx0000 --message "测试消息"
```

### Agent 管理

```bash
openclaw agents list              # 查看 Agent 列表
openclaw agents add coding        # 创建新 Agent
```

### 技能管理

```bash
openclaw skills list                              # 查看已安装技能
openclaw skills info gog                           # 查看技能详情
openclaw skills check                              # 检查技能状态
```

### 记忆管理

```bash
openclaw memory status                   # 查看记忆状态
openclaw memory index                    # 索引记忆
openclaw memory search "关键词"          # 搜索记忆
```

### 模型管理

```bash
openclaw models list                     # 查看可用模型
openclaw models status                   # 查看模型状态
openclaw models set anthropic/claude-opus-4-8  # 设置默认模型
```

### 会话与系统维护

```bash
# 会话管理
openclaw sessions list
openclaw sessions cleanup

# 系统维护
openclaw update --channel stable         # 升级（可选 stable|beta|dev）
openclaw health                          # 健康检查
openclaw doctor                          # 诊断
```

---

## 配置文件详解

> ⏭️ **小白可跳过** — 默认配置已经够用了

OpenClaw 的所有配置都存储在一个 JSON5 文件中：`~/.openclaw/openclaw.json`。

> 💡 **术语解释：** **JSON5** 是 JSON 的增强版，支持注释和尾逗号，写起来更方便。你可以把它当成普通的配置文件来编辑，用任何文本编辑器打开就行。

### 配置文件完整结构

```json5
{
  gateway: {
    bind: "127.0.0.1",
    port: 18789,
    auth: {
      token: "auto-generated-random-token",
    },
  },
  channels: {
    telegram: {
      botToken: "123456:ABCDEF",
    },
  },
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-8",
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: { enabled: true, softThresholdTokens: 4000 },
      },
      sandbox: { mode: "off" },
    },
    list: [
      { id: "main", workspace: "~/.openclaw/workspace" },
    ],
  },
  plugins: {
    slots: { memory: "memory-core" },
  },
}
```

### 各配置块说明

| 配置块 | 用途 | 关键字段 |
|--------|------|----------|
| `gateway` | 网关服务设置 | `bind`, `port`, `auth.token` |
| `channels` | 消息平台配置 | 各平台的连接信息（如 `telegram.botToken`） |
| `agents.defaults` | Agent 默认配置 | `model`, `compaction`, `sandbox` |
| `agents.list` | Agent 列表 | `id`, `workspace` |
| `plugins` | 插件配置 | `slots` 中的各插件槽位 |

### 环境变量覆盖

> ⏭️ **小白可跳过** — 默认配置已经够用了

配置文件中的值可以用环境变量覆盖，环境变量优先级更高：

```bash
# 设置 OpenClaw 主目录（默认 ~/.openclaw）
export OPENCLAW_HOME=/path/to/your/home

# 设置状态目录
export OPENCLAW_STATE_DIR=/path/to/state

# 设置配置文件路径
export OPENCLAW_CONFIG_PATH=/path/to/openclaw.json

# AI 提供商 Key（推荐用环境变量，比写在配置文件里更安全）
export OPENAI_API_KEY="sk-proj-xxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export GEMINI_API_KEY="AIzaSy-xxxxx"

# Gateway Token
export OPENCLAW_GATEWAY_TOKEN="your-strong-random-token"
```

### 目录结构

安装完成后，OpenClaw 的文件结构：

```
~/.openclaw/
├── openclaw.json          # 主配置文件
├── workspace/             # 工作空间（AI 的文件操作区域）
│   ├── MEMORY.md          # 长期记忆
│   ├── memory/            # 每日记忆日志
│   │   └── 2026-02-25.md
│   ├── SOUL.md            # AI 人格设定
│   ├── AGENTS.md          # Agent 配置
│   ├── USER.md            # 用户信息
│   └── skills/            # 工作空间级技能
├── agents/                # 多 Agent 配置
│   └── main/
│       ├── agent/
│       │   └── auth-profiles.json
│       └── sessions/      # 会话存储
├── skills/                # 共享技能目录
└── extensions/            # 扩展插件
```

### 配置文件权限

> ⏭️ **小白可跳过** — 默认配置已经够用了

配置文件中包含 API Key 等敏感信息，务必设置正确的文件权限：

```bash
# Linux / macOS
chmod 600 ~/.openclaw/openclaw.json

# 验证权限
ls -la ~/.openclaw/openclaw.json
# -rw------- 1 user user 1234 Feb 25 10:00 openclaw.json
```

---

## 多种使用场景的快速上手

下面通过三个真实场景，手把手教你从零配置到跑通。

### 场景 1：个人 AI 助手（接入 Telegram）

适合个人用户，把 AI 助手接入 Telegram，随时随地通过手机和 AI 对话。

**第一步：创建 Telegram Bot**

1. 打开 Telegram，搜索 `@BotFather`
2. 发送 `/newbot`
3. 按提示输入 Bot 名称（比如 `My AI Assistant`）
4. 输入 Bot 用户名（比如 `my_ai_assistant_bot`，必须以 `_bot` 结尾）
5. BotFather 会返回一个 Bot Token，类似 `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`

**第二步：配置 OpenClaw**

```bash
# 添加 Telegram 平台
openclaw channels add telegram

# 或手动设置 Token
openclaw config set channels.telegram.botToken "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
```

**第三步：设置 AI 人格**

编辑 `~/.openclaw/workspace/SOUL.md`，定义你的 AI 助手人格：

```markdown
# 我的 AI 助手

你是我的私人 AI 助手，名字叫小龙。

## 性格
- 友好、幽默
- 回答简洁，不啰嗦
- 中文优先

## 能力
- 回答各种问题
- 帮我记录待办事项
- 提醒我重要的事情
- 帮我搜索信息

## 规则
- 不确定的事情要说明
- 重要信息主动记录到记忆文件
- 用口语化的方式回复
```

**第四步：重启 Gateway 并测试**

```bash
# 重启 Gateway（使用 /restart 聊天命令，或停止后重新启动）
openclaw gateway --port 18789 --verbose

# 检查 Telegram 连接状态
openclaw channels status
```

现在打开 Telegram，找到你的 Bot，发送一条消息：

```
你好，小龙！
```

AI 会通过 Bot 回复你。从此你可以在手机上随时和 AI 对话。

> ✅ **检查点：** 在 Telegram 中给你的 Bot 发消息后收到了 AI 回复？恭喜，Telegram 接入成功！如果没有回复，运行 `openclaw channels status` 检查连接状态。

**进阶配置：群组使用**

> ⏭️ **小白可跳过** — 默认配置已经够用了

把 Bot 拉进 Telegram 群组，通过 @提及 激活：

```
@my_ai_assistant_bot 帮我总结一下今天群里讨论的内容
```

### 场景 2：团队协作助手（接入 Slack）

适合小团队，把 AI 助手接入 Slack 工作区，帮团队处理日常事务。

**第一步：创建 Slack App**

1. 访问 [api.slack.com/apps](https://api.slack.com/apps)
2. 点击 "Create New App" → "From scratch"
3. 输入 App 名称（比如 `OpenClaw Assistant`）
4. 选择你的 Slack 工作区

**第二步：配置 Bot 权限**

在 Slack App 设置页面：

1. 进入 "OAuth & Permissions"，在 "Bot Token Scopes" 中添加权限：
   `chat:write`, `channels:history`, `channels:read`, `groups:history`, `im:history`, `app_mentions:read`

2. 进入 "Socket Mode"，启用 Socket Mode，生成 App-Level Token（以 `xapp-` 开头）

3. 进入 "Install App"，安装到工作区，复制 Bot User OAuth Token（以 `xoxb-` 开头）

**第三步：配置 OpenClaw**

```bash
# 设置 Bot Token
openclaw config set channels.slack.botToken "xoxb-xxxxx"

# 设置 App Token
openclaw config set channels.slack.appToken "xapp-xxxxx"
```

**第四步：定制团队助手人格**

编辑 `~/.openclaw/workspace/SOUL.md`：

```markdown
# 团队 AI 助手

你是团队的 AI 助手，帮助团队提高工作效率。

## 职责
- 回答团队成员的技术问题
- 帮助整理会议纪要
- 协助项目管理和任务分配
- 提供代码审查建议

## 规则
- 在频道中被 @提及 时才回复
- 回复要专业但不死板
- 涉及敏感信息时提醒注意保密
- 不确定的答案要标注
```

**第五步：重启并测试**

```bash
# 重启 Gateway
openclaw gateway --port 18789 --verbose
openclaw channels status
# 确认 Slack 状态为 connected
```

在 Slack 频道中 @提及 Bot：

```
@OpenClaw Assistant 帮我总结一下这周的项目进展
```

**进阶：配置多频道路由**

> ⏭️ **小白可跳过** — 默认配置已经够用了

不同频道可以路由到不同的 Agent，在 `openclaw.json` 的顶层 `bindings` 中配置（bindings 是顶层配置，不嵌套在 agent 内部）：

```json5
{
  agents: {
    list: [
      { id: "coding", workspace: "~/.openclaw/workspace-coding" },
    ],
  },
  bindings: [
    { agent: "coding", channel: "slack", channelId: "C0123456789" },
  ],
}
```

这样 `#dev` 频道的消息会路由到专门的编程 Agent。

### 场景 3：客服机器人（接入 WhatsApp）

适合小型企业，用 WhatsApp 做自动客服。

**第一步：准备专用手机号**

WhatsApp 集成基于 Baileys（WhatsApp Web 协议），建议：
- 使用专门的手机号，不要用个人主号
- 确保手机号已注册 WhatsApp
- 手机保持开机联网

**第二步：配置 WhatsApp**

```bash
# 添加 WhatsApp 平台
openclaw channels add whatsapp
```

终端会显示一个二维码，用手机 WhatsApp 扫码配对。扫码后显示 `Connected!` 即配对成功。

**第三步：定制客服人格**

编辑 `~/.openclaw/workspace/SOUL.md`：

```markdown
# 客服 AI 助手

你是 [公司名称] 的客服助手。

## 职责
- 回答客户关于产品和服务的问题
- 处理常见的售后问题
- 收集客户反馈
- 无法解决的问题转接人工客服

## 产品信息
- [在这里填写你的产品/服务信息]
- [价格、规格、使用方法等]

## 规则
- 始终保持礼貌和专业
- 不要编造产品信息，不确定就说"我帮您确认一下"
- 涉及退款、投诉等敏感问题，提示客户联系人工客服
- 回复控制在 3-5 句话以内，简洁明了
- 工作时间：9:00-18:00，非工作时间自动回复
```

**第四步：配置配对审批**

客服场景下，你可能希望自动接受所有客户消息：

```bash
# 注意：生产环境建议保持手动审批
openclaw config set channels.pairing.autoApprove true
```

或者保持手动审批，定期检查：

```bash
# 查看待配对的客户
openclaw pairing list

# 批量批准
openclaw pairing approve --all
```

**第五步：重启并测试**

```bash
# 重启 Gateway
openclaw gateway --port 18789 --verbose

# 用另一个 WhatsApp 号码发送测试消息
# "你好，我想了解一下你们的产品"
```

**进阶：设置自动回复模板**

> ⏭️ **小白可跳过** — 默认配置已经够用了

在 `~/.openclaw/workspace/MEMORY.md` 中预设常见问答：

```markdown
# 常见问答

## 营业时间
周一至周五 9:00-18:00，周末休息。

## 退换货政策
7 天无理由退换，15 天质量问题包换。

## 联系方式
人工客服电话：400-xxx-xxxx
邮箱：support@example.com
```

AI 会自动参考这些信息回答客户问题。

---

## 调试和日志查看

> ⏭️ **小白可跳过** — 出问题时再来看

遇到问题时，日志是你最好的朋友。

### 查看 Gateway 日志（前台运行）

最直观的调试方式是前台运行 Gateway 并开启 `--verbose` 模式，所有日志直接输出到终端：

```bash
openclaw gateway --port 18789 --verbose
```

前台运行时，你能看到每条消息的完整处理流程：

```
[2026-02-25 10:30:15] INFO  Gateway started on 127.0.0.1:18789
[2026-02-25 10:30:20] INFO  Telegram connected (bot: @my_ai_bot)
[2026-02-25 10:31:05] INFO  Message received from telegram:user123
[2026-02-25 10:31:05] INFO  Agent loop started (agent: main, session: abc123)
[2026-02-25 10:31:06] INFO  Model request: openai/gpt-5.2 (tokens: 1250)
[2026-02-25 10:31:08] INFO  Model response: 350 tokens, 2.1s
[2026-02-25 10:31:08] INFO  Reply sent to telegram:user123
```

### 常见日志关键词

| 关键词 | 含义 | 排查方向 |
|--------|------|----------|
| `ERROR` | 错误 | 需要立即处理 |
| `WARN` | 警告 | 可能有问题，关注一下 |
| `AUTH_FAILED` | 认证失败 | 检查 API Key 或 Token |
| `RATE_LIMITED` | 被限流 | API 调用太频繁，等一会儿 |
| `TIMEOUT` | 超时 | 网络问题或模型响应慢 |
| `DISCONNECTED` | 断开连接 | 平台连接中断，尝试重连 |
| `COMPACTION` | 会话压缩 | 对话太长，正在压缩上下文 |

### 健康检查

```bash
# 运行完整的健康检查
openclaw health
```

输出示例：

```
OpenClaw Health Check
=====================
Gateway:     ✓ running (pid: 12345, uptime: 2h 30m)
Memory:      ✓ 45 MB (limit: 512 MB)
Providers:   ✓ openai (connected, latency: 230ms)
Channels:    ✓ telegram (connected)
             ✗ whatsapp (disconnected - session expired)
Issues: 1 - WhatsApp disconnected: run 'openclaw channels login whatsapp'
```

### 常见问题快速排查

**Gateway 启动失败**

```bash
# 检查端口是否被占用
lsof -i :18789        # macOS/Linux
netstat -an | findstr 18789  # Windows

# 如果端口被占用，换一个端口
openclaw config set gateway.port 18790
openclaw gateway --port 18790
```

**API 调用报错**

```bash
# 检查 API Key 是否有效
openclaw config get agents.defaults.model

# 测试 API 连接
openclaw doctor
```

`openclaw doctor` 会运行完整的诊断检查，包括 API 连接测试，方便定位问题。

**消息平台断开**

```bash
# 查看平台状态
openclaw channels status

# 重新连接
openclaw channels login whatsapp

# 如果反复断开，用前台模式查看详细日志
openclaw gateway --port 18789 --verbose
```

---

## 第一次失败时怎么恢复

快速开始最重要的不是"一次成功"，而是失败时知道卡在哪一层。OpenClaw 的第一条消息链路可以拆成五段：

```text
1. Gateway 是否启动。
2. Agent 是否收到消息。
3. 模型提供商是否可用。
4. 工具或技能是否卡住。
5. 回复是否成功发回 UI / CLI / 平台。
```

### 案例一：Gateway 没启动

现象：

```text
Control UI 打不开。
CLI 发送消息失败。
浏览器访问 localhost:18789 没响应。
```

排查：

```bash
openclaw gateway --port 18789 --verbose
openclaw doctor
```

如果端口冲突：

```bash
lsof -i :18789
openclaw gateway --port 18790 --verbose
```

记录下来：

```md
# Gateway Startup Note

Port:
Command:
Error:
Resolution:
```

### 案例二：Gateway 正常，但模型失败

现象：

```text
Gateway 有入站日志。
Agent loop started。
随后出现 AUTH_FAILED、401、429、timeout 或 model not found。
```

不要去改消息平台。先看模型：

```bash
openclaw models list
openclaw models status
openclaw config get agents.defaults.model
```

然后确认：

```text
- API Key 是否属于当前 provider。
- 模型 ID 是否拼写正确。
- 网络是否能访问 provider。
- 是否触发限流。
```

### 案例三：Control UI 能聊，消息平台不回复

这说明 Gateway 和模型大概率正常，问题在 Channel。

```bash
openclaw channels status
openclaw gateway --port 18789 --verbose
```

看日志里有没有：

```text
- inbound message received
- pairing pending
- outbound message sent
- channel disconnected
```

如果没有 inbound，平台消息没进来；如果有 inbound 但没 outbound，Agent 或模型链路要继续查；如果 outbound 失败，平台 token、权限或限流要查。

---

## 快速开始后的三个小练习

### 练习一：让 AI 解释当前配置

```bash
openclaw agent --message "请用中文解释当前 OpenClaw 的基本组成：Gateway、Agent、Model、Channel。"
```

目标不是看回答多聪明，而是确认模型链路稳定。

### 练习二：让 AI 记住一个无敏感偏好

```text
记住：我偏好中文回答，技术解释请先给结论再给步骤。
```

然后新开一轮对话问：

```text
你记得我的回答偏好吗？
```

如果不记得，去看记忆系统章节，不要先怀疑模型。

### 练习三：做一次日志复盘

前台运行 Gateway，发一条消息，然后把日志分段：

```text
1. Gateway 启动。
2. 消息进入。
3. Agent 开始。
4. 模型请求。
5. 模型返回。
6. 回复发出。
```

这比“能聊了”更有价值。你以后接平台、排查延迟、定位模型问题，都靠这条链路。

---

## Quickstart Runbook：交给别人也能复现

完成快速开始后，建议写一份 runbook。

```md
# OpenClaw Quickstart Runbook

## Environment

- OS:
- Shell:
- Node:
- OpenClaw:

## Gateway

- Port:
- Start command:
- Health command:

## Model

- Provider:
- Default model:
- Test command:

## First Message

- UI / CLI / Channel:
- Test input:
- Expected output:

## Logs

- Where to watch:
- Common error:

## Next Step

- Platform:
- Skill:
- Memory:
- Security:
```

这份 runbook 能让你的“第一次跑通”变成团队可以复用的经验，而不是只留在你电脑里。

---

## 第一小时任务：从能聊到能排错

快速开始不应该只停在“能回复一句话”。下面这组任务适合第一次跑通后的 60 分钟。做完以后，你会知道 OpenClaw 的关键链路在哪里，而不是只知道打开网页聊天。

### 任务一：确认版本和配置路径

```bash
openclaw --version
openclaw config get agents.defaults.model
openclaw config get gateway.port
```

记录：

```md
## Version

- OpenClaw:
- Config:
- Gateway port:
- Default model:
```

这一步的价值是：以后报错时，你能说清楚当前版本、模型和端口。

### 任务二：用三种入口发送消息

先用 Control UI：

```text
请用一句话说明你当前连接的是哪个模型。
```

再用 CLI：

```bash
openclaw agent --message "请回复：CLI 链路正常。"
```

如果你已经接了一个消息平台，再从平台发：

```text
请回复：消息平台链路正常。
```

把结果填到表里：

| 入口 | 是否成功 | 如果失败，先查哪里 |
|---|---|---|
| Control UI |  | Gateway / 模型 |
| CLI |  | CLI / 模型 |
| Telegram/Discord/Slack |  | Channel / Pairing / 平台权限 |

同一个模型能在 UI 回复，不代表消息平台一定回复。平台入口多了 Channel 和权限层。

### 任务三：看一次完整日志

前台启动：

```bash
openclaw gateway --port 18789 --verbose
```

发一条消息，按时间顺序复制关键日志：

```md
## Gateway Log Trace

1. Gateway started:
2. Message received:
3. Agent selected:
4. Model request:
5. Model response:
6. Reply sent:
```

如果某一步没有出现，就从那一步往前查。比如没有 `Message received`，说明平台消息没进来；有 `Message received` 但没有模型请求，说明路由、Agent 或安全策略可能卡住；有模型返回但没有 `Reply sent`，说明出站平台层有问题。

### 任务四：做一个无风险记忆测试

发送：

```text
请记住一个无敏感偏好：我喜欢中文回答，技术问题请先给结论。
```

新开会话再问：

```text
我喜欢什么样的技术回答？
```

如果它能答出来，说明记忆链路初步可用。如果答不出来，先看 07 记忆系统，不要误以为模型坏了。

### 任务五：制造一个可控错误

选择一个低风险错误来练排查。例如临时查一个不存在的配置：

```bash
openclaw config get not.exists.path
```

或者把 Gateway 换到另一个端口启动：

```bash
openclaw gateway --port 28789 --verbose
```

观察错误信息长什么样。学习一个系统最快的方法，不只是让它成功，也要看它失败时如何表达。

## 从“能聊”到“能用”的三条判断线

很多人会在第一次回复后误判“我已经搭好了”。OpenClaw 真正可用，需要三条线都通。

### 线一：交互线

```text
用户消息 -> Gateway -> Agent -> 模型 -> 回复
```

检查方式：

```bash
openclaw agent --message "请回复 ok"
```

### 线二：运行线

```text
配置文件 -> 启动命令 -> 日志 -> health -> doctor
```

检查方式：

```bash
openclaw health
openclaw doctor
```

### 线三：维护线

```text
版本记录 -> 配置备份 -> 日志位置 -> 失败恢复
```

检查方式不是一个命令，而是一份笔记：

```md
# Maintenance Note

OpenClaw version:
Start command:
Config path:
Log path:
Backup path:
Rollback method:
```

个人本地使用可以轻一些，但只要你接消息平台、上服务器或给团队使用，维护线就不能省。

## 快速开始常见误判

### 误判一：UI 能聊，所以 Telegram 一定能聊

UI 能聊只证明 Gateway 和模型正常。Telegram 还需要 Bot Token、Webhook/Polling、Pairing、用户授权。平台不回复时先看：

```bash
openclaw channels status
openclaw channels logs telegram
```

### 误判二：模型答错，所以配置坏了

模型答错可能是提示不清、SOUL.md 不明确、记忆污染、技能误触发。只有 API Key 错、模型不存在、请求超时才是模型配置问题。

可以先问一个最小问题：

```bash
openclaw agent --message "请只回复数字 1。"
```

如果能回复，模型链路是通的，问题更可能在任务描述或上下文。

### 误判三：`doctor` 有提示，所以不能继续

`doctor` 的提示要分严重程度。比如缺某个消息平台凭据，不影响你先用 Control UI；但 Gateway 没认证、配置解析失败、模型 Key 无效，会影响后续体验。读提示时先判断它影响哪条链路。

### 误判四：第一次成功后马上开自动化

cron、Watchtower、自动回复、自动写文件都应该晚一点加。先手动跑通，再自动化。否则自动任务失败时，你不知道是任务本身、模型、平台、权限还是部署问题。

## 最小回归脚本：每次改配置后跑一遍

当你修改模型、Channel、Agent、Skill、Memory 后，建议跑一个最小回归流程。它不复杂，但能快速发现“刚才改坏了什么”。

```bash
# 1. CLI 是否可用
openclaw --version

# 2. 配置是否能读
openclaw config get agents.defaults.model

# 3. 系统健康
openclaw health

# 4. 诊断
openclaw doctor

# 5. 模型状态
openclaw models status

# 6. 发送一条最小消息
openclaw agent --message "请只回复：ok"
```

如果你已经接入消息平台，再加：

```bash
openclaw channels status
openclaw channels logs telegram
openclaw channels logs discord
```

把结果记录成：

```md
# Smoke Run

Date:
Changed:

| Step | Result | Notes |
|---|---|---|
| version |  |  |
| config |  |  |
| health |  |  |
| doctor |  |  |
| models |  |  |
| agent message |  |  |
| channels |  |  |
```

这不是正式测试框架，只是一个习惯。OpenClaw 的配置项多，改一处影响另一处并不罕见。小回归能避免你第二天才发现平台不回复。

## 新手交接：把你的 OpenClaw 交给另一个人试用

如果你要让朋友、同事或团队成员试用，不要只发一句“你去这个地址聊”。给他一份最小说明。

```md
# OpenClaw Trial Guide

## 入口

- WebChat:
- Telegram:
- Discord:

## 你可以问

- 总结一段文字。
- 解释一个安装错误。
- 整理一个待办清单。

## 先不要做

- 不要发送 API Key、密码、私钥。
- 不要要求它执行生产命令。
- 不要让它自动发布消息。

## 出问题时告诉我

- 你从哪个入口发的消息。
- 你发了什么。
- 有没有回复。
- 大概时间。
```

试用期建议只开一个低风险入口和一个默认 Agent。等你确认模型费用、消息日志、安全边界都稳定，再扩大到更多频道。

## 第一条 Skill 前的准备

快速开始后，很多人想马上写技能。写之前先确认三个前提：

```text
1. 基础对话稳定。
2. 你知道日志在哪里。
3. 你能区分模型失败和技能失败。
```

可以先问：

```bash
openclaw agent --message "请解释 Skill 和 Tool 的区别，不超过 100 字。"
```

如果连这个回答都不稳定，不要急着写 Skill。先回到模型和 Gateway 排查。Skill 是在稳定链路上的增强，不是用来修基础链路的。

## 第一条消息后的配置快照

第一次成功对话后，马上保存一份配置快照。以后你改模型、接平台、加技能出问题时，可以回看最初能工作的状态。

```bash
mkdir -p ~/openclaw-snapshots/first-run
openclaw --version > ~/openclaw-snapshots/first-run/version.txt
openclaw config get agents.defaults.model > ~/openclaw-snapshots/first-run/default-model.txt
openclaw health > ~/openclaw-snapshots/first-run/health.txt
openclaw doctor > ~/openclaw-snapshots/first-run/doctor.txt
cp ~/.openclaw/openclaw.json ~/openclaw-snapshots/first-run/openclaw.json
```

再写一份说明：

```md
# First Run Snapshot

## Date

...

## What worked

- Control UI:
- CLI:
- Model:
- Gateway:

## What was not configured yet

- Telegram:
- Discord:
- Skills:
- Memory:
- Docker:

## Notes

...
```

这个快照不需要提交到公开仓库，因为配置里可能有敏感信息。它是给你本地恢复和对比用的。

## 快速开始的四个里程碑

不要把“快速开始完成”理解成一个点。它有四个里程碑：

```text
M1：CLI 可用
能运行 `openclaw --version`。

M2：Gateway 可用
能访问 Control UI 或 health。

M3：模型可用
能通过 UI 或 CLI 得到模型回复。

M4：入口可用
如果接了平台，平台消息能进出。
```

排查时先确认自己卡在哪个里程碑。

| 卡住位置 | 不要先做 | 应该先查 |
|---|---|---|
| M1 | 改模型 | Node、npm、PATH |
| M2 | 接 Telegram | 端口、配置、Gateway 日志 |
| M3 | 写 Skill | API Key、模型 ID、provider 网络 |
| M4 | 换模型 | channel status、Pairing、Webhook |

这张表能帮你避免“乱动”。很多新手把 M4 的问题当成 M3，把平台不回复误判成模型不行，结果越改越乱。

## 快速开始里的安全底线

快速开始为了降低门槛，会让你先跑起来。但即便是本地测试，也有几条底线：

```text
- 不把 API Key 粘贴到公开聊天或文档。
- 不把 Gateway 直接开放到公网。
- 不让陌生人私聊 Bot。
- 不让 Agent 执行你不理解的命令。
- 不把完整配置文件发给别人求助。
```

如果需要求助，把敏感信息替换掉：

```text
OPENAI_API_KEY=sk-***
TELEGRAM_BOT_TOKEN=***
```

快速开始阶段的目标是建立信心，不是跳过安全。越早养成这些习惯，后面接平台和部署服务器时越稳。

## 快速开始后的“不要急”清单

第一次跑通后，最容易兴奋地继续加功能。但 OpenClaw 是多层系统，加太快会让问题难以定位。

先不要急着做：

```text
- 同时接 Telegram、Discord、Slack。
- 同时改模型和 SOUL.md。
- 同时启用多个 Skill。
- 直接加入公开群聊。
- 直接部署公网。
- 让 AI 执行写入或发布动作。
```

更好的节奏：

```text
第一个变量：
只换模型。

第二个变量：
只接一个平台。

第三个变量：
只加一个 Skill。

第四个变量：
只整理一次记忆。

第五个变量：
再考虑多 Agent 或 Docker。
```

每加一个变量，都跑一次最小回归脚本。这样如果出错，你知道是谁引入的。

## 快速开始后的目录整理

跑通之后，把几个文件打开看一眼：

```bash
ls -la ~/.openclaw
ls -la ~/.openclaw/workspace
```

你会逐渐接触：

```text
openclaw.json：
配置入口。

SOUL.md：
Agent 的长期行为设定。

USER.md：
用户偏好。

MEMORY.md：
项目或长期事实。

memory/：
每日记录。

logs/：
排错入口。
```

第一次不要大改，只加一条无敏感偏好到 `USER.md`，例如：

```markdown
## 沟通偏好

- 技术问题请先给结论，再给步骤。
```

然后新开对话测试。这样你能理解“文件变化 -> Agent 行为变化”的关系。

## 快速开始交付物

读完本章后，你应该留下这些东西：

```text
- 第一条成功消息。
- 一个 Quickstart Runbook。
- 一个 First Run Snapshot。
- 一份最小回归脚本。
- 一个日志关键行样例。
- 一个下一步计划。
```

如果你把这些都留好了，后面学习模型、平台、技能、记忆、多 Agent 会顺很多。

## 故障日记模板：第一次卡住时这样记

快速开始阶段最宝贵的材料，是你第一次卡住时的现场。不要只记“失败了”，要把现场记成以后能复盘的格式。

```md
# OpenClaw Quickstart Issue

## 我想做什么

例如：启动 Gateway 后，在 Control UI 里发送第一条消息。

## 当前环境

- OS:
- Shell:
- Node:
- OpenClaw:
- Install method:

## 我运行的命令

```bash
...
```

## 我看到的现象

...

## 日志关键行

```text
...
```

## 我判断卡在哪一层

- CLI / PATH:
- Gateway:
- Model:
- Channel:
- Agent:
- Skill / Memory:

## 我已经试过

...

## 最后怎么解决

...
```

举个例子：

```md
# OpenClaw Quickstart Issue

## 我想做什么

启动 Gateway 并打开 Control UI。

## 当前环境

- OS: WSL2 Ubuntu
- Shell: bash
- Node: v24.x
- OpenClaw: v2026.x
- Install method: npm global

## 我运行的命令

```bash
openclaw gateway --port 18789 --verbose
```

## 我看到的现象

Gateway 提示端口被占用，Control UI 打不开。

## 日志关键行

```text
EADDRINUSE: address already in use 127.0.0.1:18789
```

## 我判断卡在哪一层

Gateway 层，不是模型层，也不是消息平台层。

## 我已经试过

```bash
lsof -i :18789
ps aux | grep openclaw
```

## 最后怎么解决

发现旧 Gateway 还在运行，停止旧进程后重新启动成功。
```

这个模板能训练你按层排查。OpenClaw 的学习速度，很多时候取决于你能不能快速判断“我现在卡在第几层”。

## 下一步学习建议

恭喜你，OpenClaw 已经跑起来了！根据你的需求，选择下一步方向：

| 我想要... | 去哪里 |
|-----------|--------|
| 接入更多 AI 模型 | [04. AI 模型配置](04-模型配置指南.md) — 多提供商、故障转移、预算控制 |
| 连接更多消息平台 | [05. 消息平台集成](05-消息平台接入指南.md) — 30+ 平台、消息路由 |
| 解锁 AI 超能力 | [06. 技能系统](06-技能系统指南.md) — 技能生态、自定义技能 |
| AI 记住我的偏好 | [07. 记忆系统](07-记忆系统指南.md) — 长期记忆、每日日志 |
| 运行多个 AI 助手 | [08. 多 Agent 路由](08-多Agent协作指南.md) — 多 Agent、消息路由 |
| 容器化部署 | [09. Docker 部署](09-Docker部署指南.md) — Docker Compose 一键部署 |
| 加固安全 | [10. 安全配置](10-安全配置指南.md) — Token、TLS、沙箱隔离 |
| 遇到问题 | [11. 常见问题 FAQ](11-常见问题FAQ.md) — 别人踩过的坑 |

---