00. OpenClaw 文档阅读指南文档简介本指南旨在帮助不同背景的读者高效掌握 OpenClaw。无论你是 AI 新手还是资深开发者都可以通过下表快速定位适合自己的学习路径。读者角色核心目标建议阅读路线关键产出AI 新手快速体验 AI 助手完成第一个对话。01 → 02 → 03 → 11成功运行 OpenClaw并能进行基础对话。个人效率用户将 AI 助手接入日常通讯工具如 Telegram并定制其能力。02 → 03 → 04 → 05 → 07 → 06 → 10一个可用的个人手机助手具备基础技能与记忆。团队管理员在团队内安全部署并管理 AI 助手控制成本与权限。02 → 04 → 05 → 08 → 09 → 10 → 11一套可维护的团队机器人部署与安全方案。技能开发者为 OpenClaw 开发自定义技能或工具扩展其能力。01 → 06 → 07 → 08 → 10一个可复用的自定义技能并理解其安全边界。运维人员将 OpenClaw 以 Docker 容器形式部署到服务器并确保其长期稳定运行。02 → 09 → 10 → 05 → 11一套容器化部署、备份及监控方案。本系列文档共 12 篇本篇指南 0111 正文你无需逐篇通读。上表为你提供了基于目标的导航后续章节将详细展开每一条路径的具体步骤与原理。## 文档地图难度分级说明入门— 零基础也能看懂跟着做就行进阶— 需要一点技术基础会用命令行、了解 API 概念高级— 面向有经验的开发者和运维人员全部文档一览序号文档难度一句话说明什么人需要看01项目介绍 入门OpenClaw 是什么、能干什么、跟别的有什么不同所有人02安装部署 入门怎么把 OpenClaw 装到你的电脑上所有人03快速开始 入门5 分钟跑起第一个对话所有人04模型配置 进阶怎么切换 AI 模型、配置 API Key想换模型的人05消息平台 进阶怎么把 AI 接到 WhatsApp、Telegram 等平台想在手机上用的人06技能系统 进阶怎么教 AI 新技能、管理已有技能想定制 AI 能力的人07记忆系统 进阶怎么让 AI 记住你的偏好和历史想让 AI 更懂你的人08多Agent协作 高级怎么创建多个 AI 助手分工协作重度用户、团队使用09Docker部署 高级怎么用 Docker 部署到服务器运维人员、服务器部署10安全配置 高级怎么保护你的 AI 助手不被滥用公网暴露、团队使用11常见问题 入门遇到问题来这里找答案遇到问题的人阅读路线图先判断你要解决什么问题OpenClaw 不是单纯的聊天网页也不是只会跑命令的 CLI。它更像一个可以长期运行的 AI 网关上面接消息平台下面接模型和工具中间有 Agent、技能、记忆、权限和 Gateway。学习时不要一上来追所有功能先判断自己今天要解决哪个问题。如果你只是想和 AI 对话 先看 01、02、03。 如果你想把 AI 接到手机或团队聊天 先看 02、03、05再回头看 10 的安全部分。 如果你想让 AI 长期记住你 先看 03、07再看 06 的技能组合。 如果你想做一个可长期运行的服务器 先看 02、09、10再看 05。 如果你想做多助手分工 先看 06、07、08不要第一天就上生产。这套教程的读法和普通软件文档不同。普通文档按功能排列课程读法应该按任务排列安装、跑通、接平台、加技能、加记忆、上生产、做安全。 路线一小白速通30 分钟上手只想最快跑起来按这个顺序跳过所有标注可跳过的章节01-项目介绍只看前 3 节了解 OpenClaw 是什么 ↓ 02-安装部署跟着快速安装章节操作 ↓ 03-快速开始完整跟着做5 分钟跑起第一个对话 ↓ 搞定你已经有一个能聊天的 AI 助手了 之后遇到问题去看 11-常见问题FAQ。速通路线结束后不要马上接 WhatsApp、Telegram、Slack。先用 Control UI 或 CLI 跑通一个最小对话确认 Gateway、模型和配置都正常。否则平台接入失败时你会分不清是模型问题、Gateway 问题还是平台 Webhook 问题。 路线二日常使用2-3 小时想在手机上用、想让 AI 更聪明在路线一的基础上加日常使用路线建议每次只增加一个变量。比如今天只接 Telegram明天再开记忆后天再加技能。OpenClaw 是长驻型工具配置变化越多排障越难。 路线一完成后 ↓ 04-模型配置选择最适合你的 AI 模型 ↓ 05-消息平台把 AI 接到你的 WhatsApp/Telegram ↓ 06-技能系统只看内置技能和技能管理章节 ↓ 07-记忆系统只看基础配置章节深度定制路线里最容易踩的坑是把技能、工具、记忆、多 Agent 同时打开。更稳的顺序是1. 先让一个 Agent 稳定完成任务。 2. 再把重复任务做成 Skill。 3. 再让 Memory 保存长期偏好。 4. 最后才拆出多个 Agent 分工。️ 路线三深度定制半天到一天想玩转所有功能在路线二的基础上加路线二完成后 ↓ 06-技能系统完整阅读学会创建自定义技能 ↓ 07-记忆系统完整阅读优化记忆策略 ↓ 08-多Agent协作创建专业分工的 AI 团队 路线四生产部署需要运维经验要把 OpenClaw 部署到服务器给团队用路线二完成后 ↓ 09-Docker部署容器化部署到服务器 ↓ 10-安全配置保护你的 AI 助手 ↓ 08-多Agent协作为不同团队成员配置不同 Agent生产路线里安全配置不是最后的装饰而是能否上线的前置条件。只要 Gateway 暴露到公网至少要确认 token、TLS、反向代理头、DM Pairing、平台权限和日志策略。第一周学习计划如果你想把 OpenClaw 学成真正可用的工具可以按下面 5 天推进。第 1 天跑通本地 Gateway目标不是接所有平台而是确认本机能运行。openclaw onboard --install-daemon openclaw gateway--port18789--verboseopenclaw doctor你应该能回答- 配置文件在哪里 - Gateway 是否启动 - 默认端口是多少 - 当前模型提供商是谁 - 失败时去哪看日志第 2 天跑通第一个对话用 Control UI 或 CLI 发送第一条消息。openclaw agent--message用一句话介绍你自己这一天只确认模型、Agent 和 Gateway 的基本链路。不要同时改模型、接平台、开多 Agent。第 3 天接一个低风险消息平台优先选 Telegram 或 Web Chat 这类容易调试的平台。接入时只做三个动作1. 配置 channel。 2. 发一条测试消息。 3. 看 Gateway 日志确认消息从平台进入 OpenClaw。第 4 天加一个技能或一条记忆不要一次装很多技能。先选一个低风险技能观察它如何改变回复。openclaw skills list然后让 AI 记住一个非敏感偏好记住我喜欢简洁的中文回答。第 5 天做一次安全检查检查 Gateway token、配置文件权限、DM Pairing 和日志。openclaw config get openclaw doctor这一天的目标是建立安全基线而不是继续加功能。三个典型学习场景场景一个人手机助手推荐路线01 - 02 - 03 - 04 - 05 - 07重点- 模型稳定。 - 手机平台消息能收发。 - 记忆只保存非敏感偏好。 - DM Pairing 不要关闭。不要急着做- 多 Agent。 - Docker 生产部署。 - 自定义工具写入本机文件。场景二团队内部机器人推荐路线01 - 02 - 03 - 05 - 10 - 06 - 08重点- 先明确谁能和机器人对话。 - 团队频道和私聊策略分开。 - 技能要有 owner。 - 多 Agent 要有路由和权限边界。不要急着做- 让机器人自动执行生产操作。 - 把所有团队知识塞进记忆。 - 让多个 Agent 共用同一套高权限工具。场景三服务器长期运行推荐路线02 - 09 - 10 - 05 - 11重点- Docker volume 和配置备份。 - HTTPS / 反向代理。 - Gateway token。 - 日志和监控。 - 版本升级和回滚。不要急着做- Watchtower 自动更新后不看日志。 - 暴露 18789 到公网但不设认证。 - 把配置目录放在不备份的位置。遇到问题时怎么读文档不要直接在 FAQ 里搜索一个报错词就结束。更稳的排查路线是安装失败 先看 02再看 11 的安装类问题。 能启动但不回复 先看 03 的 Gateway / Control UI再看 04 的模型配置。 平台收不到消息 先看 05 的 channel 生命周期再看 11 的消息平台问题。 AI 不按预期工作 先看 06 的技能再看 07 的记忆。 公网部署不放心 先看 10再回 09 检查 Docker 和反向代理。每次排障都记录四件事1. 当前命令。 2. 当前配置文件路径。 3. Gateway 日志关键行。 4. 你已经排除了什么。这样你在 GitHub Issue、Discord 或团队群里提问时别人能快速判断问题在哪一层。按任务查文档你现在想做什么如果你已经有明确目标可以不按章节顺序读直接从任务入口跳。你想做什么推荐入口你会得到什么先知道 OpenClaw 是什么01 项目介绍Gateway、Channel、Agent、Skill、Memory 的整体心智模型在电脑上装起来02 安装部署Node、CLI、onboard、Gateway、健康检查五分钟内聊第一句03 快速开始第一条对话、Control UI、CLI 消息、日志定位配一个可用模型04 模型配置API Key、本地模型、fallback、成本控制接 Telegram / Discord / Slack05 消息平台平台凭据、Webhook/Polling、Pairing、频道日志让 OpenClaw 会做固定工作06 技能系统Skill 编写、触发、调试、权限边界让 AI 记住你和项目07 记忆系统USER/MEMORY/每日记忆、索引、迁移、遗忘多个助手分工08 多 AgentAgent 工作空间、路由、Sessions 转交、共享目录放到服务器长期跑09 Docker 部署Compose、反代、volume、备份、更新回滚防止误操作和泄露10 安全配置Gateway、DM Pairing、沙箱、提示词注入、事故响应问题卡住了11 FAQ按问题类型快速定位这张表建议你收藏。OpenClaw 涉及模型、消息平台、插件、文件系统和安全边界很多问题看起来像同一个错误实际源头可能完全不同。按任务入口读可以减少无效排查。一个下午的完整学习节奏如果你有 3-4 小时可以按下面节奏完成第一次系统学习。第 0 阶段先建立边界感用 15 分钟读01 项目介绍的“一条消息的旅程”10 安全配置的 Gateway 和 DM Pairing 部分目的不是马上配置安全而是先知道 OpenClaw 不是普通聊天网页。它可以接消息平台、调用工具、写文件、加载记忆所以安全边界从第一天就要考虑。第 1 阶段装起来并确认 Gateway用 45 分钟读02 安装部署的系统要求、CLI 安装、onboard03 快速开始的 Gateway 状态和 Control UI只追求一件事openclaw health或openclaw doctor能给出可理解结果Gateway 能在18789提供服务。不要在这一阶段接三个平台也不要写复杂 Agent。第 2 阶段跑第一条稳定对话用 30 分钟读03 快速开始的第一条消息04 模型配置的 API Key 和模型状态如果第一条消息失败只排查模型。不要同时怀疑 Telegram、Docker、Skill、Memory。第一条稳定对话是整个课程的地基。第 3 阶段接一个低风险入口用 45 分钟读05 消息平台的 Telegram 或 WebChat10 安全配置的 DM Pairing建议第一次选个人私聊或 WebChat不要直接进团队大群。你要先知道消息到达、路由、回复、日志长什么样。第 4 阶段加一个小能力用 45 分钟读06 技能系统的工坊07 记忆系统的记忆整理练习只做一个小能力比如“整理反馈”或“记住写作偏好”。不要第一次就做多 Agent 自动协作。第 5 阶段写一页运行笔记用 20 分钟写# My OpenClaw Runbook ## 启动 - openclaw gateway --port 18789 ## 检查 - openclaw health - openclaw doctor - openclaw channels status ## 当前模型 - provider: - model: ## 当前入口 - WebChat: - Telegram: ## 常见问题 - Gateway 没启动 - 模型 Key 错误 - 平台不回复这页笔记比你想象得重要。OpenClaw 的可用性来自一条链路配置、Gateway、模型、入口、Agent、Skill、Memory。运行笔记会让你下次不用从头猜。读者常见岔路下面这些岔路很常见提前知道会少走很多弯路。岔路一一开始就接最复杂的平台Discord、Slack、飞书、WhatsApp 都有权限、事件订阅、Bot 审核或扫码状态。第一次学习建议先用 WebChat 或 Telegram 私聊。你先证明 Gateway 和模型没问题再接复杂平台。岔路二模型没通就开始改 Agent如果模型 provider 报错改 SOUL.md 没有意义。先运行openclaw models status openclaw models list确认模型能返回再讨论 Agent 的人格、技能和记忆。岔路三把所有偏好都塞进 MEMORY.md记忆不是垃圾桶。长期稳定偏好写USER.md长期项目事实写MEMORY.md当天临时进展写memory/YYYY-MM-DD.md。如果你把每次聊天都写进长期记忆后面回答会越来越混乱。岔路四多 Agent 只是多写几个身份多 Agent 的核心不是“多几个角色”而是入口、工作空间、模型、工具、记忆、权限都能分开。没有路由和边界的多 Agent只是多个名字不同的聊天助手。岔路五Docker 跑起来就算部署完成Docker 只解决运行形态不自动解决备份、反向代理、TLS、日志、升级回滚。长期运行至少要读 09 Docker 部署和 10 安全配置。每章读完应该留下什么读教程不是只留下“我看过了”。每章读完最好留下一个具体产物。章节读完后留下的产物01 项目介绍一张自己的 OpenClaw 架构草图02 安装部署一份安装记录和当前版本03 快速开始第一条成功对话和日志定位方法04 模型配置模型路由笔记和备用模型05 消息平台一个 Channel Runbook06 技能系统一个本地 Skill07 记忆系统整理后的 USER.md / MEMORY.md08 多 Agent一个明确路由的 Agent 分工09 Docker 部署一份 update/backup/restore 操作笔记10 安全配置一份最小安全加固配置11 FAQ自己遇到问题的补充记录这些产物都是读者自己的工作资产。课程的价值不在于看完多少页而在于你能不能把 OpenClaw 变成一个稳定、可维护、可恢复的系统。本系列的学习原则先 Gateway再平台Gateway 是 OpenClaw 的核心。Control UI、消息平台、Agent、技能、记忆都依赖它。平台接入失败时先确认 Gateway 是否正常。先一个 Agent再多 Agent多 Agent 很吸引人但第一天就拆多个 Agent 会让问题变复杂。先让默认 Agent 稳定工作再拆专业分工。先只读再写入任何会写文件、发消息、调用外部系统的能力都先用只读或测试环境验证。先手动再自动Watchtower、cron、自动备份、自动重启都很有用但前提是你已经手动跑通过同样流程。先安全再公网只要公网可访问就必须先看安全配置。Gateway token、TLS、反向代理头、DM Pairing、日志都不是可有可无的细节。贯穿全套课程的练习项目如果你只读每章命令很容易学完就忘。建议用一个小项目贯穿整套课程做一个“个人到团队可迁移的 OpenClaw 助手”。这个项目分四个阶段不要求一天做完。阶段一本地个人助手目标在本机启动 Gateway用 Control UI 或 CLI 完成稳定对话。涉及章节01 项目介绍02 安装部署03 快速开始04 模型配置你会留下- 当前安装方式。 - 当前 OpenClaw 版本。 - 默认模型。 - Gateway 启动命令。 - 第一条成功消息。 - 失败时看哪份日志。这个阶段不要接公网也不要做复杂多 Agent。你只需要证明“本机 - Gateway - 模型 - 回复”这条线通了。阶段二手机入口助手目标把 OpenClaw 接到 Telegram 或其他低摩擦消息平台。涉及章节05 消息平台接入10 安全配置的 DM Pairing你会留下- 一个 Channel Runbook。 - Bot Token 存放位置。 - Pairing 策略。 - inbound / outbound 日志样例。 - 平台失效时的禁用方法。这个阶段的重点不是“平台越多越好”而是你能不能解释消息从哪里来、谁能发、发给哪个 Agent、回复失败时查哪里。阶段三可复用工作能力目标让 OpenClaw 做一个固定工作例如整理反馈、生成会议纪要、分类 issue。涉及章节06 技能系统07 记忆系统你会留下- 一个本地 Skill。 - 一个 examples/ 示例。 - 一份 USER.md 偏好。 - 一份 MEMORY.md 项目事实。 - 一条不写入敏感信息的规则。这个阶段最容易犯的错是把技能、记忆、模型混成一团。Skill 负责流程Memory 负责长期上下文模型负责生成和推理。它们不是同一件事。阶段四团队或服务器形态目标把 OpenClaw 变成能长期运行、能备份、能恢复、能加固的服务。涉及章节08 多 Agent 协作09 Docker 部署10 安全配置11 FAQ你会留下- 一个 Agent 分工草图。 - 一个 Docker Compose 或服务器运行手册。 - 一份备份恢复步骤。 - 一份安全事件处理笔记。 - 一份常见问题补充记录。这个阶段才适合考虑多 Agent、Docker、反向代理、TLS、自动更新和长期日志。前面阶段没跑稳时不要急着上服务器。不同背景的人怎么读完全新手你可能不熟悉命令行、Node、API Key。先不要试图理解所有架构词。你的路线是00 - 01 - 02 - 03 - 11读的时候只做三件事1. 跟着命令安装。 2. 跑通第一条消息。 3. 遇到错误记录原文。暂时跳过- 多 Agent。 - Docker。 - 自定义插件。 - 公网部署。个人效率用户你关心的是手机入口、记忆和固定工作流。你的路线是00 - 02 - 03 - 04 - 05 - 07 - 06 - 10重点- Telegram / WebChat 入口。 - USER.md 里的沟通偏好。 - MEMORY.md 里的长期事实。 - 一个小 Skill。 - Pairing 和 token 安全。暂时不要把 OpenClaw 拉进很多群。先让它成为你的个人助手再考虑团队协作。开源项目维护者你关心社区支持、FAQ、issue 分拣和文档反馈。你的路线是00 - 01 - 03 - 05 - 06 - 08 - 10重点- Discord / Slack 测试频道。 - community 和 tech-support 的边界。 - issue-triage Skill。 - 公开频道不输出敏感信息。 - 技术问题转交和日志追踪。不要让 AI 直接关闭 issue、发布公告或承诺修复时间。先让它整理、解释、引导和生成草稿。团队管理员你关心权限、部署、审计、成本和可维护性。你的路线是00 - 02 - 04 - 05 - 08 - 09 - 10 - 11重点- 默认模型成本。 - 哪些频道可以触发。 - 哪些 Agent 有工具权限。 - Docker volume 和备份。 - Gateway 不直接暴露公网。 - token 轮换和事故处理。团队场景里OpenClaw 不是“装给大家玩”的工具而是一个带入口、权限和数据边界的小系统。插件或技能开发者你关心扩展面、工具、Skill、MCP、插件兼容。你的路线是00 - 01 - 06 - 07 - 08 - 10重点- Skill 的触发和边界。 - Tool 与 Skill 的区别。 - 插件白名单。 - 第三方能力的权限最小化。 - 测试 Agent 和真实 Agent 分开。开发者最容易低估安全边界。只要你的技能会读写文件、调用外部 API 或处理用户消息就必须读安全章节。课程笔记建议建议你在自己的工作空间建一个学习目录mkdir-p~/openclaw-learningcd~/openclaw-learning每章建一份笔记00-reading.md 01-intro.md 02-install.md 03-quickstart.md 04-models.md 05-channels.md 06-skills.md 07-memory.md 08-agents.md 09-docker.md 10-security.md 11-faq.md每份笔记只记录四类内容# Chapter Note ## 我做了什么 ... ## 当前配置 ... ## 遇到的问题 ... ## 下次继续 ...不要把教程全文复制一遍。笔记的价值是记录你自己的环境、选择和问题。提问时怎么描述问题无论你去 GitHub Issue、Discord、微信群还是问 AI描述问题时都尽量提供上下文。模板## 我想做什么 ... ## 我运行的命令 bash ...当前环境OS:Node:OpenClaw:Install method:现象…日志关键行...我已经试过…一个好的问题描述能让别人直接判断问题在哪一层。只说“不能用”“不回复”“报错了”通常会被迫来回追问。 ## 30 天学习路线从个人使用到可维护系统 如果你想系统学而不是只临时查命令可以按 30 天来安排。每天不需要很久关键是每次只推进一个能力。 ### 第 1 周把最小链路跑稳 目标 text 本地 Gateway 能启动默认 Agent 能回复模型配置可解释日志位置清楚。安排天数任务对应章节Day 1读项目介绍画出 Gateway - Agent - Model 的链路01Day 2安装 CLI运行 onboard记录安装方式02Day 3用 Control UI 和 CLI 各发一条消息03Day 4配置默认模型确认 API Key 或本地模型可用04Day 5看一次 Gateway 前台日志标出消息进入和回复发出03Day 6写第一份 Quickstart Runbook03Day 7回顾本周错误把问题补到自己的笔记里11这一周不要接入正式群聊也不要部署到服务器。你的任务是让最小链路稳定。第 2 周接入一个真实入口目标接入一个低风险消息平台知道谁能发消息、消息进了哪个 Agent、失败时看哪份日志。安排天数任务对应章节Day 8选择一个入口WebChat、Telegram 私聊或测试 Discord 频道05Day 9配置 token 或登录状态保持 Pairing/allowlist05 / 10Day 10发第一条平台消息记录 inbound/outbound 日志05Day 11写 Channel Runbook05Day 12测一次平台不回复时的排查路径05 / 11Day 13加一条隐私和敏感信息规则到 SOUL.md10Day 14复盘入口是否适合长期使用05这一周的核心不是“能不能接更多平台”而是能不能维护一个平台。第 3 周让助手有工作能力目标创建一个本地 Skill整理一次记忆让 OpenClaw 不只是聊天。安排天数任务对应章节Day 15选择一个重复工作例如整理反馈或生成纪要06Day 16写最小 SKILL.md06Day 17写一个 examples/ 示例06Day 18测触发词观察日志06Day 19整理 USER.md 和 MEMORY.md07Day 20重建记忆索引测试召回07Day 21删除一条不该保存的记忆演练遗忘流程07这一周要避免两个极端一是只写很长提示词不做 Skill二是把所有聊天都塞进长期记忆。第 4 周走向团队和长期运行目标知道什么时候需要多 Agent什么时候需要 Docker如何处理安全和恢复。安排天数任务对应章节Day 22拆一个多 Agent 场景但先不急着上线08Day 23设计频道到 Agent 的绑定08Day 24写一份 handover 文件模拟 Agent 转交08Day 25阅读 Docker 部署选择 volume 方案09Day 26写备份和恢复笔记09Day 27按安全工坊加固 Gateway、Pairing、SOUL.md10Day 28演练 token 暴露后的处理流程10Day 29用 FAQ 回查自己遇到的问题11Day 30整理最终运行手册0030 天结束时你应该拥有的不是“看过一套文档”的感觉而是一套自己的 OpenClaw 运行资料安装记录、模型路由、Channel Runbook、Skill、记忆文件、Agent 分工、部署和安全笔记。每周复盘问题每周结束时问自己这些问题1. 这一周新增了哪个能力 2. 哪个配置变更最容易影响稳定性 3. 哪条日志最有排查价值 4. 有没有把敏感信息写入文档、日志或记忆 5. 如果明天换一台机器我能不能恢复 6. 如果消息平台突然失效我先看哪里 7. 如果模型费用升高我先查哪个入口这些问题会把你从“会用命令”带到“会维护系统”。OpenClaw 的学习难点不是单条命令而是多层链路同时存在入口、Gateway、模型、Agent、Skill、Memory、安全和部署。课程里的命令怎么读文档里有很多命令。读命令时建议区分三类只读命令 查看版本、状态、日志、配置。适合先运行。 配置命令 修改模型、Channel、Agent、Skill。运行前记录原值。 高影响命令 删除、重置、撤销 token、清理 volume、停服务。运行前确认备份和影响范围。例子openclaw--versionopenclaw channels status openclaw models status这些是只读命令适合排查开头先跑。openclaw configsetagents.defaults.model openai/gpt-5.2-mini这是配置命令运行前最好先记录旧值openclaw config get agents.defaults.model像下面这些就属于高影响动作dockercompose down-vopenclaw resetrm-rf~/.openclaw本教程会尽量把高影响动作写清楚但你自己执行时也要先想这会不会删除配置、记忆、凭证、volume 或会话历史按症状反查路线OpenClaw 的问题常常表面相似。比如“Bot 不回复”可能是 Gateway 没启动、模型 Key 错、平台 token 失效、Pairing 没批准、路由给了错误 Agent也可能只是平台限流。下面这张路线图适合排障时从症状反推。症状一命令行找不到 OpenClaw先读02 安装部署 - Node/npm/PATH/权限先运行node--versionnpm--versionnpmprefix-gecho$PATH不要先做- 改 openclaw.json。 - 重新配置模型。 - 删除 ~/.openclaw。这类问题通常还没进入 OpenClaw 配置层而是在运行时和 shell 层。症状二Gateway 启动失败先读03 快速开始 - Gateway 管理 02 安装部署 - 端口和配置排查先运行openclaw doctorlsof-i:18789||ss-tlnp|grep18789openclaw gateway--port18789--verbose判断端口占用 先确认是不是旧 Gateway。 配置解析失败 回到 openclaw.json 最近修改。 权限失败 检查 ~/.openclaw 的 owner 和 chmod。Gateway 是后面所有入口的基础。Gateway 没稳时不要继续接 Telegram、Discord 或 Slack。症状三Control UI 能打开但 AI 不回复先读04 模型配置 03 快速开始 - 日志和模型链路先运行openclaw models status openclaw config get agents.defaults.model openclaw agent--message请只回复 ok常见原因- API Key 未加载。 - 模型 ID 写错。 - provider 限流。 - 本地模型服务没启动。 - 上下文过长。不要急着改 Agent。Agent 的表达方式会影响回答质量但模型链路断了时改 SOUL.md 没用。症状四Control UI 能聊消息平台不回复先读05 消息平台接入 10 安全配置 - Pairing 和 token先运行通道状态和对应平台日志完整命令清单放在 OC-03 快速开始和 OC-10 安全排障里本阅读指南只提醒排查顺序。排查顺序1. 平台 token 是否有效。 2. Webhook / Polling 是否工作。 3. 私聊是否需要 Pairing。 4. 群聊是否需要 mention。 5. channelId / guildId 是否匹配。 6. 出站发送是否被平台限制。这类问题说明 Gateway 和模型大概率是好的坏在平台入口或出口。症状五AI 答得很怪像忘了规则先读06 技能系统 07 记忆系统 08 多 Agent 协作先看openclaw skills list openclaw memory status再检查- 当前消息进了哪个 Agent。 - SOUL.md 是否具体。 - 是否触发了不相关 Skill。 - MEMORY.md 是否过期或冲突。 - 每日日志是否被误当成长期事实。不要把这类问题都归因于“模型不行”。很多时候是上下文、技能或记忆给了模型错误信号。症状六Docker 更新后数据不见了先读09 Docker 部署 - volume 和恢复 02 安装部署 - 安装方式切换先运行dockercomposepsdockervolumelsdockerinspect openclaw-gateway|grep-A20Mounts重点判断- 有没有挂载 /home/node/.openclaw。 - 旧 volume 是否还在。 - compose 项目名是否变了。 - 是否运行过 docker compose down -v。Docker 容器可以删数据 volume 不能随便删。更新前备份恢复前确认 volume 名称。症状七费用突然升高先读04 模型配置 - 成本控制 05 消息平台 - 群聊费用和滥用控制先查- 哪个入口触发最多。 - 哪个 Agent 使用强模型。 - 是否有自动任务循环。 - 是否有群聊所有消息都进模型。 - 是否有长上下文反复提交。处理顺序1. 暂停高频入口或改为 mention 触发。 2. 高频 Agent 切到低成本模型。 3. 限制长回答和自动摘要。 4. 再分析是否需要强模型。不要一上来把所有模型都换成最便宜的。成本控制要看任务类型不是只看单价。读完后的个人运行档案建议你最终整理一份OPENCLAW-RUNBOOK.md。它不是公开教程而是你自己的运行档案。# OpenClaw Runbook ## 1. Current Setup - Install method: - OpenClaw version: - OS: - Node: - Config path: - Workspace path: ## 2. Start / Stop - Start: - Stop: - Health: - Doctor: ## 3. Model - Default model: - Strong model: - Local model: - Fallback: ## 4. Channels | Platform | Purpose | Agent | Owner | Disable | |---|---|---|---|---| | WebChat | test | main | me | stop Gateway | | Telegram | personal | main | me | disable channel | ## 5. Agents | Agent | Workspace | Model | Skills | Boundary | |---|---|---|---|---| | main | ~/.openclaw/workspace | ... | ... | ... | ## 6. Skills - Installed: - Local: - Disabled: ## 7. Memory - USER.md: - MEMORY.md: - Index command: - Sensitive data rule: ## 8. Backup - What: - Where: - Command: - Last restore test: ## 9. Security - Gateway token: - Pairing: - TLS / proxy: - Sandbox: - Log redaction: ## 10. Known Issues - ...这份档案会让你从“会照着教程操作”变成“知道自己系统是什么样”。OpenClaw 这种长期运行工具最怕所有知识都留在聊天记录里。最后一张速查卡当你忘了下一步该看哪章时用这张卡装不上 看 02。 能装但不会用 看 03。 能聊但回答失败 看 04。 平台不回复 看 05。 想让它固定做一件事 看 06。 想让它记住长期信息 看 07。 想拆多个助手 看 08。 想放服务器 看 09。 担心安全和滥用 看 10。 已经报错了 看 11。如果你只记住一句话先把一条链路跑稳再加下一层能力。OpenClaw 的学习顺序不是“功能越多越好”而是每一层都知道怎么启动、怎么观察、怎么暂停、怎么恢复。版本差异提醒OpenClaw 更新很快你本机命令的细节可能和文档略有差异。遇到这种情况先看当前 CLI 的帮助而不是硬套旧命令openclaw--helpopenclaw channels--helpopenclaw models--helpopenclaw skills--help如果帮助输出和教程不同以当前安装版本为准再把差异记录到自己的 Runbook。教程负责教你理解链路和排查方法具体参数要跟随你正在运行的版本。遇到命令不确定时优先在本机看帮助再回教程找上下文。这样既不会被旧参数卡住也能把“这个命令属于哪一层”想清楚。如果你把本机帮助输出和本教程的差异写进自己的运行档案下一次升级、迁移或求助时会轻松很多。记录差异时也写上日期和版本号避免以后把旧环境经验误当成当前状态。遇到问题怎么办先看 11-常见问题FAQ80% 的问题都有现成答案运行openclaw doctor让系统自动诊断到 GitHub Issues 搜索或提问加入 OpenClaw Discord 社区寻求帮助文档约定本套文档中使用以下标记标记含义入门零基础可读进阶需要一点技术基础高级面向有经验的开发者提示有用的小技巧⚠️注意容易踩的坑危险操作不当可能造成数据丢失或安全问题延伸阅读想深入了解可以看这里⏭️小白可跳过新手不需要看这个章节