Appearance
03 · 快速开始指南
⚠️ OpenClaw 迭代很快：界面、版本、命令和模型能力可能随版本变化。遇到与页面描述不一致时，以你当前看到的界面和官方文档（docs.openclaw.ai）为准，不要在未确认的情况下执行高权限或不可逆操作。
本篇你会做出什么
把快速开始写成手把手，是因为见过太多工具教程只让人看懂，却没有让人真正跑起来。
跟完这一篇，你会得到一个能在浏览器里对话的本地 OpenClaw 助手：
- Gateway 正常运行。
- Control UI 可以打开。
- 能发送第一条消息并收到回复。
- 知道怎么检查 Gateway 状态。
- 失败时知道先看哪几个排查点。
先完成下面的 3 步即可。后面的 Control UI 功能介绍可以等跑通后再看。
需要动手
这一节会打开终端、输入命令。卡住时先看 [11 常见问题](/practice/openclaw/guide/11-faq/)，再回来看这里；不确定后果的操作先不做。
5 分钟跑起第一个对话
安装完 OpenClaw 后，只需要 3 步就能开始聊天。别急，我们一步步来，每步都讲清楚。
第一步：运行引导向导
bash
openclaw onboard --install-daemon这条命令做了两件事：
onboard— 启动交互式引导向导--install-daemon— 把 Gateway 注册为系统服务（开机自启）
v2026.6.1 提示：如果你只输入 openclaw，且本机还没有 authored config，新版会进入 classic onboarding。教学里仍建议写完整命令，避免读者分不清“只启动 CLI”和“安装后台服务”的区别。快速开始后的排障优先看 Control UI Activity、transcript、Gateway 日志、插件/Skill Workshop 状态和 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-xxxxxAPI Key 会加密存储在 ~/.openclaw/openclaw.json 中。如果你还没有 Key：
- DeepSeek: platform.deepseek.com
- OpenAI: platform.openai.com
- Anthropic: console.anthropic.com
- Google: 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 的 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-64. 发送第一条消息
在 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 tuiGateway 管理
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-6"
openclaw config unset agents.defaults.modelAgent 命令
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-6 # 设置默认模型会话与系统维护
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-6",
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
- 打开 Telegram，搜索
@BotFather - 发送
/newbot - 按提示输入 Bot 名称（比如
My AI Assistant） - 输入 Bot 用户名（比如
my_ai_assistant_bot，必须以_bot结尾） - 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
- 访问 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
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.comAI 会自动参考这些信息回答客户问题。
调试和日志查看
⏭️ 小白可跳过 — 出问题时再来看
遇到问题时，日志是你最好的朋友。
查看 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 18790API 调用报错
bash
# 检查 API Key 是否有效
openclaw config get agents.defaults.model
# 测试 API 连接
openclaw doctoropenclaw 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 模型配置](/practice/openclaw/guide/04-models/) — 多提供商、故障转移、预算控制 |
| 连接更多消息平台 | [05. 消息平台集成](/practice/openclaw/guide/05-channels/) — 30+ 平台、消息路由 |
| 解锁 AI 超能力 | [06. 技能系统](/practice/openclaw/guide/06-skills/) — 技能生态、自定义技能 |
| AI 记住我的偏好 | [07. 记忆系统](/practice/openclaw/guide/07-memory/) — 长期记忆、每日日志 |
| 运行多个 AI 助手 | [08. 多 Agent 路由](/practice/openclaw/guide/08-multi-agent/) — 多 Agent、消息路由 |
| 容器化部署 | [09. Docker 部署](/practice/openclaw/guide/09-docker/) — Docker Compose 一键部署 |
| 加固安全 | [10. 安全配置](/practice/openclaw/guide/10-security/) — Token、TLS、沙箱隔离 |
| 遇到问题 | [11. 常见问题 FAQ](/practice/openclaw/guide/11-faq/) — 别人踩过的坑 |
---