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)
本地默认访问：http://127.0.0.1:18789（远程 HTTPS 另行配置）
以上展示需要确认的设置，实际向导文案以安装版本为准。默认本地入口使用 loopback HTTP；远程访问按安全章配置 SSH 隧道、Tailscale 或 HTTPS。Gateway Token 保护 Gateway 访问，不能代替传输加密。
💡 术语解释：
-
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 状态
onboard --install-daemon 会安装并启动后台 Gateway。下面先检查这一个实例，排障用 openclaw logs --follow 看日志。后台实例已运行时，不要再对同一 profile 执行前台 openclaw gateway。确实要切到前台调试，先 openclaw gateway stop，结束调试后再 openclaw gateway start。
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 状态。
运行中补充要求，或停止当前任务
v2026.9.7 的 Control UI 中，有可发送的草稿时，原来的 Stop 位置会换成 Send、Queue 或 Steer。要停止当前运行，先把仍想保留的草稿复制到安全位置，再清空输入框，Stop 就会回来；活动中的语音听写也会影响按钮。不要因为看不到 Stop 就直接关闭页面或重发原任务。
需要补充同一个任务时，先看当前会话提供的是 Queue 还是 Steer：Queue 留作后续回合，Steer 指导当前工作，但不打断正在执行的工具。先用只生成文字的任务试一次，比如发送“把最终答案改为三条建议”，再核对最终输出是否采用了它。Incognito 与云 worker 回合当前不能使用这一 steer 路线。共享回合也仍使用原发起人的权限、审批和提供商账户，不因另一个人发补充就取得新权限。
停止后检查活动记录与最终状态；停止请求不是撤销已经完成的文件改动或外部操作。消息平台的发送取消边界见第 5 章，复杂子任务的停止与清理见第 8 章。
先做一份今天的待办简报
先做一次手动简报。下面都是虚构记录，不需要接邮箱、日历或外部消息平台。在已经能对话的 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 / Cmd + F
搜索当前对话记录
Ctrl + K
打开命令面板
设置中的输入偏好
查看和调整发送快捷键；以当前界面为准
上传、相机拍照和语音听写都先形成草稿，先核对文字、文件和收件会话，再发送；相机的本地预览本身不会发给 Agent，实时 Talk 则是另一条语音路线。更新页面前若有文件草稿，先预览并复制或下载需要的内容，明确丢弃后再刷新；手动重载可能丢失未保存草稿。共享会话显示 Typing · not sent 时，队友可能看到暂时的未发送文字预览，它不是模型上下文或已保存的消息，但也不等于只有你可见。浏览器导出当前会话可输入不带路径的 /export 或 /export-session 下载 Markdown，其他客户端的 HTML/工作区导出按各自规则处理。
手机与原生入口
不想接 Bot 时，也可以用官方 Android 或 iPhone 客户端连接同一个 Gateway。Android 从官方 Google Play 链接安装；侧载只选择官方 release 同时提供签名 APK 和校验文件的版本，不是每版都有。iPhone 从官方 App Store 链接安装。先按Android 配对步骤或iOS 连接步骤填写可达的 Gateway 地址，在 Gateway 端核对并批准你自己设备的请求，再选同一 Agent 发一次测试消息。它们是伴随客户端，手机不替你运行 Gateway；相机、屏幕和语音权限按实际需要分别开启。已有 Bot 路线仍可继续使用。
设置面板
点击左下角的齿轮图标进入设置，包含以下配置项：
模型设置 — 切换模型提供商、调整温度/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 --agent main --message "帮我写一个 Python 的 Hello World"
# 使用高级思考模式
openclaw agent --agent main --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 --channel whatsapp --target +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 --agent main --message "你好" # 发送单条消息
openclaw agent --agent main --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 --channel telegram --token "<BotFather-token>"
openclaw channels remove --channel telegram
# login/logout 只适用于支持交互式登录的频道，例如 WhatsApp
openclaw channels login --channel whatsapp
openclaw channels logout --channel whatsapp
# 发送消息
openclaw message send --channel whatsapp --target +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 的增强版，支持注释和尾逗号，写起来更方便。你可以把它当成普通的配置文件来编辑，用任何文本编辑器打开就行。
配置文件结构示例
下面用一份示例展示主要配置块，token、Bot token 和模型名都是示例值。先完成 onboarding，再对照自己的配置修改，不要整份覆盖真实认证与通道设置。运行本机 Gateway 时需保留初始化写入的 gateway.mode: "local"。
{
gateway: {
bind: "loopback",
port: 18789,
auth: {
token: "auto-generated-random-token",
},
},
channels: {
telegram: {
botToken: "123456:ABCDEF",
},
},
agents: {
defaults: {
model: "anthropic/claude-opus-4-8",
compaction: {
memoryFlush: { enabled: true, softThresholdTokens: 4000 },
},
sandbox: { mode: "off" },
},
"entries": {
"main": { workspace: "~/.openclaw/workspace" },
},
},
plugins: {
slots: { memory: "memory-core" },
},
}
各配置块说明
配置块
用途
关键字段
gateway
网关服务设置
bind, port, auth.token
channels
消息平台配置
各平台的连接信息（如 telegram.botToken）
agents.defaults
Agent 默认配置
model, compaction, sandbox
agents.entries
以 Agent ID 为键的配置对象
default, 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/
│ │ └── openclaw-agent.sqlite # 模型认证与活跃会话状态
│ └── 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: {
"entries": {
"coding": { workspace: "~/.openclaw/workspace-coding" },
},
},
bindings: [
{
"agentId": "coding",
"match": {
"channel": "slack",
"peer": {
"kind": "channel",
"id": "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，非工作时间自动回复
第四步：配置配对审批
先保留 WhatsApp 私聊的配对模式，用另一个测试号码发消息，再批准终端列出的那一个配对码：
openclaw config set channels.whatsapp.dmPolicy pairing
openclaw pairing list --channel whatsapp
openclaw pairing approve whatsapp <code>
<code> 替换成你核对过身份的实际配对码。没有 channels.pairing.autoApprove 或 pairing approve --all 这组配置和参数。正式客服若要接受所有陌生人，应另行配置 channels.whatsapp.dmPolicy: "open" 和 allowFrom: ["*"]，同时评估费用、滥用和数据权限；这个跟练先保持配对。
第五步：重启并测试
# 重启 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 --channel 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 --channel 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 --agent main --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 --agent main --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 --agent main --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 --channel telegram
误判二：模型答错，所以配置坏了
模型答错可能是提示不清、SOUL.md 不明确、记忆污染、技能误触发。只有 API Key 错、模型不存在、请求超时才是模型配置问题。
可以先问一个最小问题：
openclaw agent --agent main --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 --agent main --message "请只回复：ok"
如果你已经接入消息平台，再加：
openclaw channels status
openclaw channels logs --channel telegram
openclaw channels logs --channel 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 --agent main --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 — 别人踩过的坑
---