03. 快速开始指南

课程信息
难度等级：🟢 入门
阅读时间：10 分钟
前置知识：已完成安装（02-安装部署指南）
本篇你将学会： 运行引导向导、启动 Gateway、发送第一条消息、基本的日常操作命令
这是最重要的一篇！ 跟着做完前 3 步，你就有一个能聊天的 AI 助手了

本篇你会做出什么

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

Gateway 正常运行。

Control UI 可以打开。

能发送第一条消息并收到回复。

知道怎么检查 Gateway 状态。

失败时知道先看哪几个排查点。

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

5 分钟跑起第一个对话

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

第一步：运行引导向导

这条命令做了两件事：

onboard — 启动交互式引导向导

--install-daemon — 把 Gateway 注册为系统服务（开机自启）

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

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

1. 选择 AI 模型提供商

? Select your AI provider:
  ❯ DeepSeek (V4 Flash — 引导默认, V4 Pro)
    OpenAI (GPT-5.2, GPT-5.2-mini)
    Anthropic (Claude Opus 4.6, Sonnet 4.6)
    Google (Gemini 3.1)
    Ollama (本地模型，隐私优先)
    OpenRouter (一个 Key 用所有模型)
    其他...

新手建议选 DeepSeek（引导向导默认）或 OpenAI，生态最成熟。预算有限选 Ollama（免费本地模型）。

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

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 状态

正常输出：

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

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

✅ 检查点： 运行 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、删除旧对话、给对话打标签分类。

系统状态

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

第一个对话的完整流程

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

1. 确认 Gateway 正在运行

2. 打开 Control UI

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

3. 检查模型配置

在 Control UI 的设置中，确认：

AI 提供商已选择（比如 OpenAI）

API Key 已填写

模型已选择（比如 gpt-5.2）

也可以用命令行检查：

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 对话：

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

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

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

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

CLI 命令速查

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

基础命令

Gateway 管理

配置管理

Agent 命令

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

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

消息平台管理

Agent 管理

技能管理

记忆管理

模型管理

会话与系统维护

配置文件详解

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

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-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` 中的各插件槽位

环境变量覆盖

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

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

目录结构

安装完成后，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 等敏感信息，务必设置正确的文件权限：

多种使用场景的快速上手

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

场景 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

第三步：设置 AI 人格

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

第四步：重启 Gateway 并测试

现在打开 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

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

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

第五步：重启并测试

在 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 扫码配对。扫码后显示 Connected! 即配对成功。

第三步：定制客服人格

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

第四步：配置配对审批

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

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

第五步：重启并测试

进阶：设置自动回复模板

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

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

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

调试和日志查看

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

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

查看 Gateway 日志（前台运行）

最直观的调试方式是前台运行 Gateway 并开启 --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 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 启动失败

API 调用报错

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

消息平台断开

下一步学习建议

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

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

03-快速开始指南

03. 快速开始指南#

本篇你会做出什么#

5 分钟跑起第一个对话#

第一步：运行引导向导#

第二步：检查 Gateway 状态#

第三步：打开 Control UI#

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

聊天界面（主页面）#

设置面板#

会话管理#

系统状态#

第一个对话的完整流程#

1. 确认 Gateway 正在运行#

2. 打开 Control UI#

3. 检查模型配置#

4. 发送第一条消息#

5. 试试工具调用#

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

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

CLI 命令速查#

基础命令#

Gateway 管理#

配置管理#

Agent 命令#

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

消息平台管理#

Agent 管理#

技能管理#

记忆管理#

模型管理#

会话与系统维护#

配置文件详解#

配置文件完整结构#

各配置块说明#

环境变量覆盖#

目录结构#

配置文件权限#

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

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

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

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

调试和日志查看#

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

常见日志关键词#

健康检查#

常见问题快速排查#

下一步学习建议#

03. 快速开始指南

本篇你会做出什么

5 分钟跑起第一个对话

第一步：运行引导向导

第二步：检查 Gateway 状态

第三步：打开 Control UI

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

聊天界面（主页面）

设置面板

会话管理

系统状态

第一个对话的完整流程

1. 确认 Gateway 正在运行

2. 打开 Control UI

3. 检查模型配置

4. 发送第一条消息

5. 试试工具调用

6. 通过命令行发送消息

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

CLI 命令速查

基础命令

Gateway 管理

配置管理

Agent 命令

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

消息平台管理

Agent 管理

技能管理

记忆管理

模型管理

会话与系统维护

配置文件详解

配置文件完整结构

各配置块说明

环境变量覆盖

目录结构

配置文件权限

多种使用场景的快速上手

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

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

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

调试和日志查看

查看 Gateway 日志（前台运行）

常见日志关键词

健康检查

常见问题快速排查

下一步学习建议