03. 快速开始指南
课程信息
⠀
-
作者：老金
-
GitHub：https://github.com/KimYx0207
-
公众号：老金带你玩AI
-
X（Twitter）：老金带你玩AI
-
个人博客：https://aiking.dev
-
难度等级：🟢 入门
-
阅读时间：首次跟练约 10–15 分钟，后续功能按需查；安装与认证时间另计
-
前置知识：已完成安装（02-安装部署指南）
⠀
本篇你将学会： 运行引导向导、启动 Gateway、发送第一条消息、基本的日常操作命令
⠀
这是最重要的一篇！ 跟着做完前 3 步，你就有一个能聊天的 AI 助手了
⠀
已经能在 Control UI 中收到回复，可以直接跳到 今日待办简报。第一次运行时，先完成下面的启动与对话检查。
⠀
本篇你会做出什么
⠀
这次先确认助手能回复，再让它从四条工作记录中整理出今天真正要处理的事项。
⠀
跟完这一篇，你会得到一个能在浏览器里对话的本地 OpenClaw 助手：
⠀
-
Gateway 正常运行。
-
Control UI 可以打开。
-
能发送第一条消息并收到回复，完成一份有明确依据的待办简报。
-
知道怎么检查 Gateway 状态。
-
失败时知道先看哪几个排查点。
⠀
先完成下面的 3 步即可。后面的 Control UI 功能介绍可以等跑通后再看。
⠀
5 分钟跑起第一个对话
⠀
安装完 OpenClaw 后，只需要 3 步就能开始聊天。别急，我们一步步来，每步都讲清楚。
第一步：运行引导向导
⠀
openclaw onboard --install-daemon
⠀
这条命令做了两件事：
-
onboard — 启动交互式引导向导
-
--install-daemon — 把 Gateway 注册为系统服务（开机自启）
⠀
2026-09-13 当前基线（v2026.9.4）：全新安装现在有快速通道——v2026.9.1 起首次安装（含 npx openclaw@latest）会探测本机已有的 Claude Code / Codex 登录和 API key，在线验证后直接打开 web dashboard，完整向导改叫 Custom setup。课堂上要演示完整配置过程，就得明确选 Custom setup，否则学员看到的流程和教程对不上。另外 v2026.9.4 起终端里也能回答结构化提问（键盘选项、自由文本、多问题连续回答），Gateway 连接态和本地 TUI 都支持。
⠀
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（守护进程）：一种在后台默默运行的程序，不需要你手动启动，开机就自动跑起来。
⠀
向导会依次引导你完成以下配置：
⠀
- 选择 AI 模型提供商
⠀
? Select your AI provider:
❯ DeepSeek（具体模型以当前目录为准）
OpenAI（具体模型以当前目录为准）
Anthropic（具体模型以当前目录为准）
Google / Vertex（具体模型以当前目录为准）
Ollama (本地模型，隐私优先)
OpenRouter (一个 Key 用所有模型)
其他...
⠀
新手建议先选你已经有账号和额度的 provider；预算有限或隐私敏感时再选 Ollama 等本地模型。不要背这里的 provider 顺序，真实列表以当前 onboarding / models 输出为准。
⠀
- 输入 API Key
⠀
💡 术语解释：API Key（API 密钥） 是 AI 模型提供商给你的一串"通行证"字符串。有了它，OpenClaw 才能代替你调用 AI 模型。每个提供商的 Key 格式不同，注意保密，不要分享给别人。
⠀
? Enter your OpenAI API Key: sk-proj-xxxxx
⠀
凭据的保存位置取决于所用的认证方式，配置和凭据目录可能包含敏感数据，不能笼统认为 openclaw.json 中的内容会自动加密。备份或排障时按 官方凭据与存储说明 处理，不要把配置原文公开。如果你还没有 Key：
-
DeepSeek: platform.deepseek.com
-
OpenAI: platform.openai.com
-
Anthropic: console.anthropic.com
-
Google: aistudio.google.com
⠀
- 配置 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 之间的通信会被加密，防止被窃听。类似于浏览器地址栏的 🔒 小锁。
⠀
- 可选：连接消息平台
⠀
? 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 的 Q1-Q5。
⠀
第二步：检查 Gateway 状态
⠀
openclaw gateway status
⠀
正常输出：
⠀
Gateway Status: running
PID: 12345
Port: 18789
Uptime: 2m 30s
Memory: 45 MB
Agents: 1 (main)
Channels: 0 connected
⠀
看到 running 就说明网关已经启动了。如果显示 stopped，手动启动：
⠀
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 启动后，运行下面的命令打开 Control UI；它会使用当前配置，避免你记错端口或打开不对应的实例：
⠀
openclaw dashboard
⠀
默认本地地址是 http://127.0.0.1:18789/。如果你修改过端口，以当前配置和命令提示为准。
⠀
直接在输入框里打字，开始和 AI 对话。
⠀
先确认回复：能打开网页只说明界面可访问。发一条消息并收到实际回复后，再做下面的练习；无回复时先查模型认证和 Gateway 状态。
先做一份今天的待办简报
⠀
先做一次手动简报。下面都是虚构记录，不需要接邮箱、日历或外部消息平台。在已经能对话的 Control UI 中发送：
⠀
请只根据下面的记录，整理今天的待办简报。
基准时间：2026-09-14 09:00，Asia/Shanghai。
A｜今天 10:30｜林一｜完成体验课开场稿｜未开始
B｜今天 09:00｜叶青｜检查示例数据｜已完成
C｜时间未定｜许宁｜确认下周演示时间｜待确认
A｜今天 10:30｜林一｜完成体验课开场稿｜未开始
相同编号和内容只保留一条，已完成事项不进入待办。
请分“今天先做”“需要确认”两部分，保留编号、负责人和时间。
没有给出的时间不要补写。这次只回复简报，不创建定时任务、不发送消息。
⠀
应能整理出两件事：
⠀
放在哪里
事项
为什么
今天先做
A：林一在今天 10:30 前完成开场稿
有明确时间且未开始；重复记录合并
需要确认
C：许宁确认下周演示时间，截止时间待确认
记录中没有给出完成时间
⠀
B 已完成，不应再次催办。C 里“下周演示”描述的是要确认的活动，不能自动变成“许宁下周完成这个确认任务”。
⠀
如果结果重复列了 A，或擅自给 C 安排了明天 9 点，就直接指出编号和错误，让它仅修改那一项。随后追加一句“现在 A 已完成，请更新简报”，应只留下 C 的待确认事项。
⠀
最后换成自己的一小段脱敏待办，不再复制整段提示词。先看能否正确区分已完成、未完成和缺信息，再考虑接入更多来源。这个练习参考了社区的 每日简报场景，记录、问题和核对过程由本课程编写。
⠀
有了满意的简报格式后，下一步可以学习 记忆系统，让后续任务沿用必要偏好；需要手机收消息时，再选择 消息平台接入 的对应章节。
跑通后再看：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 正在运行
⠀
openclaw gateway status
# 确认输出包含 "running"
⠀
2. 打开 Control UI
⠀
在浏览器中打开 http://127.0.0.1:18789/。
⠀
3. 检查模型配置
⠀
在 Control UI 的设置中，确认：
-
AI 提供商已选择（比如 OpenAI）
-
API Key 已填写
-
模型已选择（比如 gpt-5.2）
⠀
也可以用命令行检查：
⠀
# 查看当前配置
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 对话：
⠀
# 发送消息并等待回复
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），可以用命令行发送测试消息：
⠀
openclaw message send --to +86138xxxx0000 --message "你好，我是你的 AI 助手！"
CLI 命令速查
⠀
OpenClaw 的命令行工具功能强大，以下是常用命令的完整参考。
⠀
基础命令
⠀
# 查看版本
openclaw --version
# 查看帮助
openclaw --help
# 查看子命令帮助
openclaw gateway --help
# 运行引导向导
openclaw onboard
# 查看系统状态
openclaw gateway status
# 健康检查
openclaw health
# 诊断
openclaw doctor
# 搜索文档
openclaw docs
# 终端 UI
openclaw tui
⠀
Gateway 管理
⠀
openclaw gateway status # 查看 Gateway 状态
openclaw gateway --port 18789 # 启动 Gateway（前台运行）
openclaw gateway --port 18789 --verbose # 启动 Gateway（详细日志）
⠀
配置管理
⠀
# 查看特定配置
openclaw config get agents.defaults.model
# 设置 / 删除配置
openclaw config set agents.defaults.model "anthropic/claude-opus-4-8"
openclaw config unset agents.defaults.model
⠀
Agent 命令
⠀
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 — 群组激活模式
⠀
消息平台管理
⠀
# 频道管理
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 管理
⠀
openclaw agents list # 查看 Agent 列表
openclaw agents add coding # 创建新 Agent
⠀
技能管理
⠀
openclaw skills list # 查看已安装技能
openclaw skills info gog # 查看技能详情
openclaw skills check # 检查技能状态
⠀
记忆管理
⠀
openclaw memory status # 查看记忆状态
openclaw memory index # 索引记忆
openclaw memory search "关键词" # 搜索记忆
⠀
模型管理
⠀
openclaw models list # 查看可用模型
openclaw models status # 查看模型状态
openclaw models set anthropic/claude-opus-4-8 # 设置默认模型
⠀
会话与系统维护
⠀
# 会话管理
openclaw sessions list
openclaw sessions cleanup
# 系统维护
openclaw update --channel stable # 升级（可选 stable|beta|dev）
openclaw health # 健康检查
openclaw doctor # 诊断
配置文件详解
⠀
⏭️ 小白可跳过 — 默认配置已经够用了
⠀
OpenClaw 的所有配置都存储在一个 JSON5 文件中：~/.openclaw/openclaw.json。
⠀
💡 术语解释：JSON5 是 JSON 的增强版，支持注释和尾逗号，写起来更方便。你可以把它当成普通的配置文件来编辑，用任何文本编辑器打开就行。
⠀
配置文件完整结构
⠀
{
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 中的各插件槽位
⠀
环境变量覆盖
⠀
⏭️ 小白可跳过 — 默认配置已经够用了
⠀
配置文件中的值可以用环境变量覆盖，环境变量优先级更高：
⠀
# 设置 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 等敏感信息，务必设置正确的文件权限：
⠀
# 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
⠀
-
打开 Telegram，搜索 @BotFather
-
发送 /newbot
-
按提示输入 Bot 名称（比如 My AI Assistant）
-
输入 Bot 用户名（比如 my_ai_assistant_bot，必须以 _bot 结尾）
-
BotFather 会返回一个 Bot Token，类似 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
⠀
第二步：配置 OpenClaw
⠀
# 添加 Telegram 平台
openclaw channels add telegram
# 或手动设置 Token
openclaw config set channels.telegram.botToken "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
⠀
第三步：设置 AI 人格
⠀
编辑 ~/.openclaw/workspace/SOUL.md，定义你的 AI 助手人格：
⠀
# 我的 AI 助手
你是我的私人 AI 助手，名字叫小龙。
## 性格
- 友好、幽默
- 回答简洁，不啰嗦
- 中文优先
## 能力
- 回答各种问题
- 帮我记录待办事项
- 提醒我重要的事情
- 帮我搜索信息
## 规则
- 不确定的事情要说明
- 重要信息主动记录到记忆文件
- 用口语化的方式回复
⠀
第四步：重启 Gateway 并测试
⠀
# 重启 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
⠀
-
访问 api.slack.com/apps
-
点击 "Create New App" → "From scratch"
-
输入 App 名称（比如 OpenClaw Assistant）
-
选择你的 Slack 工作区
⠀
第二步：配置 Bot 权限
⠀
在 Slack App 设置页面：
⠀
-
进入 "OAuth & Permissions"，在 "Bot Token Scopes" 中添加权限：
chat:write, channels:history, channels:read, groups:history, im:history, app_mentions:read -
进入 "Socket Mode"，启用 Socket Mode，生成 App-Level Token（以 xapp- 开头）
-
进入 "Install App"，安装到工作区，复制 Bot User OAuth Token（以 xoxb- 开头）
⠀
第三步：配置 OpenClaw
⠀
# 设置 Bot Token
openclaw config set channels.slack.botToken "xoxb-xxxxx"
# 设置 App Token
openclaw config set channels.slack.appToken "xapp-xxxxx"
⠀
第四步：定制团队助手人格
⠀
编辑 ~/.openclaw/workspace/SOUL.md：
⠀
# 团队 AI 助手
你是团队的 AI 助手，帮助团队提高工作效率。
## 职责
- 回答团队成员的技术问题
- 帮助整理会议纪要
- 协助项目管理和任务分配
- 提供代码审查建议
## 规则
- 在频道中被 @提及 时才回复
- 回复要专业但不死板
- 涉及敏感信息时提醒注意保密
- 不确定的答案要标注
⠀
第五步：重启并测试
⠀
# 重启 Gateway
openclaw gateway --port 18789 --verbose
openclaw channels status
# 确认 Slack 状态为 connected
⠀
在 Slack 频道中 @提及 Bot：
⠀
@OpenClaw Assistant 帮我总结一下这周的项目进展
⠀
进阶：配置多频道路由
⠀
⏭️ 小白可跳过 — 默认配置已经够用了
⠀
不同频道可以路由到不同的 Agent，在 openclaw.json 的顶层 bindings 中配置（bindings 是顶层配置，不嵌套在 agent 内部）：
⠀
{
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
⠀
# 添加 WhatsApp 平台
openclaw channels add whatsapp
⠀
终端会显示一个二维码，用手机 WhatsApp 扫码配对。扫码后显示 Connected! 即配对成功。
⠀
第三步：定制客服人格
⠀
编辑 ~/.openclaw/workspace/SOUL.md：
⠀
# 客服 AI 助手
你是 [公司名称] 的客服助手。
## 职责
- 回答客户关于产品和服务的问题
- 处理常见的售后问题
- 收集客户反馈
- 无法解决的问题转接人工客服
## 产品信息
- [在这里填写你的产品/服务信息]
- [价格、规格、使用方法等]
## 规则
- 始终保持礼貌和专业
- 不要编造产品信息，不确定就说"我帮您确认一下"
- 涉及退款、投诉等敏感问题，提示客户联系人工客服
- 回复控制在 3-5 句话以内，简洁明了
- 工作时间：9:00-18:00，非工作时间自动回复
⠀
第四步：配置配对审批
⠀
客服场景下，你可能希望自动接受所有客户消息：
⠀
# 注意：生产环境建议保持手动审批
openclaw config set channels.pairing.autoApprove true
⠀
或者保持手动审批，定期检查：
⠀
# 查看待配对的客户
openclaw pairing list
# 批量批准
openclaw pairing approve --all
⠀
第五步：重启并测试
⠀
# 重启 Gateway
openclaw gateway --port 18789 --verbose
# 用另一个 WhatsApp 号码发送测试消息
# "你好，我想了解一下你们的产品"
⠀
进阶：设置自动回复模板
⠀
⏭️ 小白可跳过 — 默认配置已经够用了
⠀
在 ~/.openclaw/workspace/MEMORY.md 中预设常见问答：
⠀
# 常见问答
## 营业时间
周一至周五 9:00-18:00，周末休息。
## 退换货政策
7 天无理由退换，15 天质量问题包换。
## 联系方式
人工客服电话：400-xxx-xxxx
邮箱：[email protected]
⠀
AI 会自动参考这些信息回答客户问题。
调试和日志查看
⠀
⏭️ 小白可跳过 — 出问题时再来看
⠀
遇到问题时，日志是你最好的朋友。
⠀
查看 Gateway 日志（前台运行）
⠀
最直观的调试方式是前台运行 Gateway 并开启 --verbose 模式，所有日志直接输出到终端：
⠀
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
会话压缩
对话太长，正在压缩上下文
⠀
健康检查
⠀
# 运行完整的健康检查
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 启动失败
⠀
# 检查端口是否被占用
lsof -i :18789 # macOS/Linux
netstat -an | findstr 18789 # Windows
# 如果端口被占用，换一个端口
openclaw config set gateway.port 19789 # 不要用 18790-18899，那一段是 Bridge / Browser Control / Canvas / CDP 端口池（见 09 章端口表）
openclaw gateway --port 19789
⠀
API 调用报错
⠀
# 检查 API Key 是否有效
openclaw config get agents.defaults.model
# 测试 API 连接
openclaw doctor
⠀
openclaw doctor 会运行完整的诊断检查，包括 API 连接测试，方便定位问题。
⠀
消息平台断开
⠀
# 查看平台状态
openclaw channels status
# 重新连接
openclaw channels login whatsapp
# 如果反复断开，用前台模式查看详细日志
openclaw gateway --port 18789 --verbose
第一次失败时怎么恢复
⠀
快速开始最重要的不是"一次成功"，而是失败时知道卡在哪一层。OpenClaw 的第一条消息链路可以拆成五段：
⠀
1. Gateway 是否启动。
2. Agent 是否收到消息。
3. 模型提供商是否可用。
4. 工具或技能是否卡住。
5. 回复是否成功发回 UI / CLI / 平台。
⠀
案例一：Gateway 没启动
⠀
现象：
⠀
Control UI 打不开。
CLI 发送消息失败。
浏览器访问 localhost:18789 没响应。
⠀
排查：
⠀
openclaw gateway --port 18789 --verbose
openclaw doctor
⠀
如果端口冲突：
⠀
lsof -i :18789
openclaw gateway --port 19789 --verbose
⠀
记录下来：
⠀
# Gateway Startup Note
Port:
Command:
Error:
Resolution:
⠀
案例二：Gateway 正常，但模型失败
⠀
现象：
⠀
Gateway 有入站日志。
Agent loop started。
随后出现 AUTH_FAILED、401、429、timeout 或 model not found。
⠀
不要去改消息平台。先看模型：
⠀
openclaw models list
openclaw models status
openclaw config get agents.defaults.model
⠀
然后确认：
⠀
- API Key 是否属于当前 provider。
- 模型 ID 是否拼写正确。
- 网络是否能访问 provider。
- 是否触发限流。
⠀
案例三：Control UI 能聊，消息平台不回复
⠀
这说明 Gateway 和模型大概率正常，问题在 Channel。
⠀
openclaw channels status
openclaw gateway --port 18789 --verbose
⠀
看日志里有没有：
⠀
- inbound message received
- pairing pending
- outbound message sent
- channel disconnected
⠀
如果没有 inbound，平台消息没进来；如果有 inbound 但没 outbound，Agent 或模型链路要继续查；如果 outbound 失败，平台 token、权限或限流要查。
快速开始后的三个小练习
⠀
练习一：让 AI 解释当前配置
⠀
openclaw agent --message "请用中文解释当前 OpenClaw 的基本组成：Gateway、Agent、Model、Channel。"
⠀
目标不是看回答多聪明，而是确认模型链路稳定。
⠀
练习二：让 AI 记住一个无敏感偏好
⠀
记住：我偏好中文回答，技术解释请先给结论再给步骤。
⠀
然后新开一轮对话问：
⠀
你记得我的回答偏好吗？
⠀
如果不记得，去看记忆系统章节，不要先怀疑模型。
⠀
练习三：做一次日志复盘
⠀
前台运行 Gateway，发一条消息，然后把日志分段：
⠀
1. Gateway 启动。
2. 消息进入。
3. Agent 开始。
4. 模型请求。
5. 模型返回。
6. 回复发出。
⠀
这比“能聊了”更有价值。你以后接平台、排查延迟、定位模型问题，都靠这条链路。
Quickstart Runbook：交给别人也能复现
⠀
完成快速开始后，建议写一份 runbook。
⠀
# 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 的关键链路在哪里，而不是只知道打开网页聊天。
⠀
任务一：确认版本和配置路径
⠀
openclaw --version
openclaw config get agents.defaults.model
openclaw config get gateway.port
⠀
记录：
⠀
## Version
- OpenClaw:
- Config:
- Gateway port:
- Default model:
⠀
这一步的价值是：以后报错时，你能说清楚当前版本、模型和端口。
⠀
任务二：用三种入口发送消息
⠀
先用 Control UI：
⠀
请用一句话说明你当前连接的是哪个模型。
⠀
再用 CLI：
⠀
openclaw agent --message "请回复：CLI 链路正常。"
⠀
如果你已经接了一个消息平台，再从平台发：
⠀
请回复：消息平台链路正常。
⠀
把结果填到表里：
⠀
入口
是否成功
如果失败，先查哪里
Control UI
Gateway / 模型
CLI
CLI / 模型
Telegram/Discord/Slack
Channel / Pairing / 平台权限
⠀
同一个模型能在 UI 回复，不代表消息平台一定回复。平台入口多了 Channel 和权限层。
⠀
任务三：看一次完整日志
⠀
前台启动：
⠀
openclaw gateway --port 18789 --verbose
⠀
发一条消息，按时间顺序复制关键日志：
⠀
## 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，说明出站平台层有问题。
⠀
任务四：做一个无风险记忆测试
⠀
发送：
⠀
请记住一个无敏感偏好：我喜欢中文回答，技术问题请先给结论。
⠀
新开会话再问：
⠀
我喜欢什么样的技术回答？
⠀
如果它能答出来，说明记忆链路初步可用。如果答不出来，先看 07 记忆系统，不要误以为模型坏了。
⠀
任务五：制造一个可控错误
⠀
选择一个低风险错误来练排查。例如临时查一个不存在的配置：
⠀
openclaw config get not.exists.path
⠀
或者把 Gateway 换到另一个端口启动：
⠀
openclaw gateway --port 28789 --verbose
⠀
观察错误信息长什么样。学习一个系统最快的方法，不只是让它成功，也要看它失败时如何表达。
⠀
从“能聊”到“能用”的三条判断线
⠀
很多人会在第一次回复后误判“我已经搭好了”。OpenClaw 真正可用，需要三条线都通。
⠀
线一：交互线
⠀
用户消息 -> Gateway -> Agent -> 模型 -> 回复
⠀
检查方式：
⠀
openclaw agent --message "请回复 ok"
⠀
线二：运行线
⠀
配置文件 -> 启动命令 -> 日志 -> health -> doctor
⠀
检查方式：
⠀
openclaw health
openclaw doctor
⠀
线三：维护线
⠀
版本记录 -> 配置备份 -> 日志位置 -> 失败恢复
⠀
检查方式不是一个命令，而是一份笔记：
⠀
# Maintenance Note
OpenClaw version:
Start command:
Config path:
Log path:
Backup path:
Rollback method:
⠀
个人本地使用可以轻一些，但只要你接消息平台、上服务器或给团队使用，维护线就不能省。
⠀
快速开始常见误判
⠀
误判一：UI 能聊，所以 Telegram 一定能聊
⠀
UI 能聊只证明 Gateway 和模型正常。Telegram 还需要 Bot Token、Webhook/Polling、Pairing、用户授权。平台不回复时先看：
⠀
openclaw channels status
openclaw channels logs telegram
⠀
误判二：模型答错，所以配置坏了
⠀
模型答错可能是提示不清、SOUL.md 不明确、记忆污染、技能误触发。只有 API Key 错、模型不存在、请求超时才是模型配置问题。
⠀
可以先问一个最小问题：
⠀
openclaw agent --message "请只回复数字 1。"
⠀
如果能回复，模型链路是通的，问题更可能在任务描述或上下文。
⠀
误判三：doctor 有提示，所以不能继续
⠀
doctor 的提示要分严重程度。比如缺某个消息平台凭据，不影响你先用 Control UI；但 Gateway 没认证、配置解析失败、模型 Key 无效，会影响后续体验。读提示时先判断它影响哪条链路。
⠀
误判四：第一次成功后马上开自动化
⠀
cron、Watchtower、自动回复、自动写文件都应该晚一点加。先手动跑通，再自动化。否则自动任务失败时，你不知道是任务本身、模型、平台、权限还是部署问题。
⠀
最小回归脚本：每次改配置后跑一遍
⠀
当你修改模型、Channel、Agent、Skill、Memory 后，建议跑一个最小回归流程。它不复杂，但能快速发现“刚才改坏了什么”。
⠀
# 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"
⠀
如果你已经接入消息平台，再加：
⠀
openclaw channels status
openclaw channels logs telegram
openclaw channels logs discord
⠀
把结果记录成：
⠀
# Smoke Run
Date:
Changed:
| Step | Result | Notes |
|---|---|---|
| version | | |
| config | | |
| health | | |
| doctor | | |
| models | | |
| agent message | | |
| channels | | |
⠀
这不是正式测试框架，只是一个习惯。OpenClaw 的配置项多，改一处影响另一处并不罕见。小回归能避免你第二天才发现平台不回复。
⠀
新手交接：把你的 OpenClaw 交给另一个人试用
⠀
如果你要让朋友、同事或团队成员试用，不要只发一句“你去这个地址聊”。给他一份最小说明。
⠀
# OpenClaw Trial Guide
## 入口
- WebChat:
- Telegram:
- Discord:
## 你可以问
- 总结一段文字。
- 解释一个安装错误。
- 整理一个待办清单。
## 先不要做
- 不要发送 API Key、密码、私钥。
- 不要要求它执行生产命令。
- 不要让它自动发布消息。
## 出问题时告诉我
- 你从哪个入口发的消息。
- 你发了什么。
- 有没有回复。
- 大概时间。
⠀
试用期建议只开一个低风险入口和一个默认 Agent。等你确认模型费用、消息日志、安全边界都稳定，再扩大到更多频道。
⠀
第一条 Skill 前的准备
⠀
快速开始后，很多人想马上写技能。写之前先确认三个前提：
⠀
1. 基础对话稳定。
2. 你知道日志在哪里。
3. 你能区分模型失败和技能失败。
⠀
可以先问：
⠀
openclaw agent --message "请解释 Skill 和 Tool 的区别，不超过 100 字。"
⠀
如果连这个回答都不稳定，不要急着写 Skill。先回到模型和 Gateway 排查。Skill 是在稳定链路上的增强，不是用来修基础链路的。
⠀
第一条消息后的配置快照
⠀
第一次成功对话后，马上保存一份配置快照。以后你改模型、接平台、加技能出问题时，可以回看最初能工作的状态。
⠀
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
⠀
再写一份说明：
⠀
# First Run Snapshot
## Date
...
## What worked
- Control UI:
- CLI:
- Model:
- Gateway:
## What was not configured yet
- Telegram:
- Discord:
- Skills:
- Memory:
- Docker:
## Notes
...
⠀
这个快照不需要提交到公开仓库，因为配置里可能有敏感信息。它是给你本地恢复和对比用的。
⠀
快速开始的四个里程碑
⠀
不要把“快速开始完成”理解成一个点。它有四个里程碑：
⠀
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，把平台不回复误判成模型不行，结果越改越乱。
⠀
快速开始里的安全底线
⠀
快速开始为了降低门槛，会让你先跑起来。但即便是本地测试，也有几条底线：
⠀
- 不把 API Key 粘贴到公开聊天或文档。
- 不把 Gateway 直接开放到公网。
- 不让陌生人私聊 Bot。
- 不让 Agent 执行你不理解的命令。
- 不把完整配置文件发给别人求助。
⠀
如果需要求助，把敏感信息替换掉：
⠀
OPENAI_API_KEY=sk-***
TELEGRAM_BOT_TOKEN=***
⠀
快速开始阶段的目标是建立信心，不是跳过安全。越早养成这些习惯，后面接平台和部署服务器时越稳。
⠀
快速开始后的“不要急”清单
⠀
第一次跑通后，最容易兴奋地继续加功能。但 OpenClaw 是多层系统，加太快会让问题难以定位。
⠀
先不要急着做：
⠀
- 同时接 Telegram、Discord、Slack。
- 同时改模型和 SOUL.md。
- 同时启用多个 Skill。
- 直接加入公开群聊。
- 直接部署公网。
- 让 AI 执行写入或发布动作。
⠀
更好的节奏：
⠀
第一个变量：
只换模型。
第二个变量：
只接一个平台。
第三个变量：
只加一个 Skill。
第四个变量：
只整理一次记忆。
第五个变量：
再考虑多 Agent 或 Docker。
⠀
每加一个变量，都跑一次最小回归脚本。这样如果出错，你知道是谁引入的。
⠀
快速开始后的目录整理
⠀
跑通之后，把几个文件打开看一眼：
⠀
ls -la ~/.openclaw
ls -la ~/.openclaw/workspace
⠀
你会逐渐接触：
⠀
openclaw.json：
配置入口。
SOUL.md：
Agent 的长期行为设定。
USER.md：
用户偏好。
MEMORY.md：
项目或长期事实。
memory/：
每日记录。
logs/：
排错入口。
⠀
第一次不要大改，只加一条无敏感偏好到 USER.md，例如：
⠀
## 沟通偏好
- 技术问题请先给结论，再给步骤。
⠀
然后新开对话测试。这样你能理解“文件变化 -> Agent 行为变化”的关系。
⠀
快速开始交付物
⠀
读完本章后，你应该留下这些东西：
⠀
- 第一条成功消息。
- 一个 Quickstart Runbook。
- 一个 First Run Snapshot。
- 一份最小回归脚本。
- 一个日志关键行样例。
- 一个下一步计划。
⠀
如果你把这些都留好了，后面学习模型、平台、技能、记忆、多 Agent 会顺很多。
⠀
故障日记模板：第一次卡住时这样记
⠀
快速开始阶段最宝贵的材料，是你第一次卡住时的现场。不要只记“失败了”，要把现场记成以后能复盘的格式。
⠀
# OpenClaw Quickstart Issue
## 我想做什么
例如：启动 Gateway 后，在 Control UI 里发送第一条消息。
## 当前环境
- OS:
- Shell:
- Node:
- OpenClaw:
- Install method:
## 我运行的命令
```bash
...
我看到的现象
...
日志关键行
...
我判断卡在哪一层
- CLI / PATH:
- Gateway:
- Model:
- Channel:
- Agent:
- Skill / Memory:
我已经试过
...
最后怎么解决
...
⠀
举个例子：
⠀
OpenClaw Quickstart Issue
我想做什么
启动 Gateway 并打开 Control UI。
当前环境
- OS: WSL2 Ubuntu
- Shell: bash
- Node: 填写 node --version 的完整输出
- OpenClaw: v2026.x
- Install method: npm global
我运行的命令
openclaw gateway --port 18789 --verbose
我看到的现象
Gateway 提示端口被占用，Control UI 打不开。
日志关键行
EADDRINUSE: address already in use 127.0.0.1:18789
我判断卡在哪一层
Gateway 层，不是模型层，也不是消息平台层。
我已经试过
lsof -i :18789
ps aux | grep openclaw
最后怎么解决
发现旧 Gateway 还在运行，停止旧进程后重新启动成功。
⠀
这个模板能训练你按层排查。OpenClaw 的学习速度，很多时候取决于你能不能快速判断“我现在卡在第几层”。
⠀
## 下一步学习建议
⠀
恭喜你，OpenClaw 已经跑起来了！根据你的需求，选择下一步方向：
⠀
我想要...
去哪里
接入更多 AI 模型
04. AI 模型配置 — 多提供商、故障转移、预算控制
连接更多消息平台
05. 消息平台集成 — 30+ 平台、消息路由
解锁 AI 超能力
06. 技能系统 — 技能生态、自定义技能
AI 记住我的偏好
07. 记忆系统 — 长期记忆、每日日志
运行多个 AI 助手
08. 多 Agent 路由 — 多 Agent、消息路由
容器化部署
09. Docker 部署 — Docker Compose 一键部署
加固安全
10. 安全配置 — Token、TLS、沙箱隔离
遇到问题
11. 常见问题 FAQ — 别人踩过的坑
---