OpenClaw 深度使用教程：从环境搭建到高级架构的实战指南

说实话，AI 智能体这块我折腾了不少工具了，云端的、本地的、开源的，大部分要么功能阉割得厉害，要么就是套个壳子啥也干不了。直到我遇到了 OpenClaw，才觉得"嗯，这才是我想要的东西"。

OpenClaw 是 PSPDFKit 创始人 Peter Steinberger 搞的一个开源本地优先 AI 助手。简单来说，它不只是跟你聊天——它能直接帮你干活：读写文件、操控浏览器、收发邮件、跑代码，基本上就是一个住在你电脑里的全栈工程师。

一、OpenClaw 到底是个啥

我先说说它跟普通 AI 工具有啥不一样。

你用 ChatGPT 的时候，它只能给你文字回答，你得自己复制粘贴去执行对吧？云端的 Agent 平台倒是能执行，但都在人家的沙箱里跑，碰不到你的本地环境。

OpenClaw 直接跑在你自己的机器上，文件系统随便读写，浏览器随便开，邮件随便发。而且它能接到 WhatsApp、Telegram、Discord、飞书、钉钉、企业微信、QQ 这些你天天用的聊天工具里。你在群里 @它一下，它就帮你干活了。

技术架构方面，核心就这么几块：

Gateway（网关）：接收各聊天通道的消息，默认监听 18789 端口
Agent Loop：AI 思考-决策-行动的循环引擎
Tool System（工具系统）：通过 Skills 机制提供各种具体能力
Memory System（记忆系统）：基于向量检索的分层记忆架构
Channel System（通道系统）：统一对接 10+ 聊天平台

二、安装：我踩过的坑都在这了

最快的方式：一键脚本

macOS / Linux：

bash

1	`curl -fsSL https://openclaw.ai/install.sh \| bash`

Windows：

powershell

1	`iwr -useb https://openclaw.ai/install.ps1 \| iex`

脚本会自动检测环境、装 Node.js（要求 ≥22）、下载核心包、启动配置向导。

手动安装（我推荐的方式）

说实话一键脚本我第一次用的时候翻车了，可能是网络问题下载超时。后来我直接手动装，反而更顺利：

bash

npm i -g openclaw --registry=https://registry.npmmirror.com
 
# 或者用 pnpm
pnpm add -g openclaw
 
openclaw onboard --install-daemon

--install-daemon 这个参数很重要，它会把 OpenClaw 注册成系统后台服务，开机自启。踩坑提醒：我第一次忘了加这个参数，结果每次重启电脑都要手动启动，折腾了好几天才发现。

源码安装（适合想折腾的人）

bash

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm openclaw onboard --install-daemon
pnpm gateway:watch  # 开发模式，改代码自动重载

初始化配置的关键步骤

装完之后会进一个交互式向导，我说几个关键的：

选模式：直接选 QuickStart 就行，后面随时能改
配大模型：这是最关键的！海外用 GPT-4o 或 Claude 都行，国内就用 Qwen 或 DeepSeek，完全够用
选聊天通道：暂时不需要就跳过，先用内置的 Web UI
端口和 Skills：端口默认 18789 别动，Skills 后面再装也行

装完之后访问 http://127.0.0.1:18789/chat 就能用了。

验证一下：

bash

1	`openclaw doctor # 一键健康检查`
2	`openclaw gateway status # 网关状态`
3	`openclaw status # 整体状态`

三、配置文件：这才是 OpenClaw 的灵魂

OpenClaw 的 workspace 在 ~/.openclaw/workspace/，里面的文件直接决定了 AI 的行为方式。我一开始没在意这些文件，结果 AI 回答得一塌糊涂，后来认真配置了才好用。

code

1	`~/.openclaw/workspace/`
2	`├── AGENTS.md # 工作流程手册（AI 的员工守则）`
3	`├── SOUL.md # AI 的性格和行为风格`
4	`├── USER.md # 你的个人信息和偏好`
5	`├── IDENTITY.md # AI 的身份标识`
6	`├── MEMORY.md # 核心记忆索引`
7	`├── HEARTBEAT.md # 心跳检查清单`
8	`├── BOOT.md # 启动配置`
9	`└── memory/ # 记忆存储目录`
10	`├── projects.md`
11	`├── infra.md`
12	`├── lessons.md`
13	`└── YYYY-MM-DD.md`

你可以这么理解：SOUL.md 是性格档案，USER.md 是客户档案，IDENTITY.md 是工牌，AGENTS.md 是员工手册，MEMORY.md 是笔记本索引。

SOUL.md 示例

markdown

1	`# Soul`
2	`你是一位技术能力极强的全栈工程师助手。`
3
4	`## 沟通风格`
5	`- 回答简洁直接，不废话`
6	`- 优先给出可执行的方案，再解释原理`
7	`- 代码示例必须包含注释`
8
9	`## 技术偏好`
10	`- 后端优先使用 Python 或 Node.js`
11	`- 数据库优先选择 PostgreSQL`
12	`- 部署优先使用 Docker + Nginx`

USER.md 示例

markdown

# User Profile
- 职业：全栈开发者
- 技术栈：Python, TypeScript, React
- 中文交流，代码注释用英文
- 时区：UTC+8
- 当前项目：SaaS 产品，Next.js + Supabase

AGENTS.md：最关键的一个

这个文件定义了 AI 的工作流程和安全边界，不配好这个文件，AI 基本就是个废物。我踩的坑就是一开始觉得这个文件无所谓，结果 AI 动不动就乱删文件、乱发邮件。

markdown

1	`## Session 启动流程`
2	`1. 读取 SOUL.md - 加载性格`
3	`2. 读取 USER.md - 了解用户`
4	`3. 读取 memory/YYYY-MM-DD.md - 加载今天日志`
5	`4. 读取 MEMORY.md - 加载核心记忆`
6
7	`## 安全规范`
8
9	`### 可以自由执行`
10	`- 读取文件、浏览目录、搜索网络`
11
12	`### 必须用户确认`
13	`- 发送邮件、推文`
14	`- 删除或修改重要文件`
15
16	`### 基本原则`
17	`- 用 trash 不用 rm`
18	`- 不确定先问`

四、记忆系统：让 AI 不再"失忆"

这是我最想说的部分。普通 AI 聊天工具聊多了就忘事，OpenClaw 的记忆系统解决了这个问题。

它用的是分层记忆架构：

短期记忆：当前对话历史，受限于模型上下文窗口
日志记忆：Markdown 文件存在 memory/ 目录下，按日期组织
长期记忆：MEMORY.md 存最关键的信息索引

memoryFlush 配置（必做！）

踩坑警告：这个配置不打开，长对话必然失忆。我有一次让 AI 帮我调试一个复杂的 bug，聊了半小时结果它把前面的上下文全忘了，气死我了。

json

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000
        }
      }
    }
  }
}

原理很简单：当上下文快满了（剩余不到 4000 tokens），AI 会先把重要信息写到 memory 文件里，然后再压缩对话。这样就算对话被压缩了，关键信息还在。

softThresholdTokens 设 4000 是最佳平衡点。太小了 AI 来不及写完整信息，太大了又影响对话流畅度。

日志写得好不好，直接决定检索效果

我给你看个对比：

烂日志（基本等于没记）：

markdown

1	`今天上午处理了数据库问题，中午部署了新版本，下午改了nginx配置，最后跑起来了。`

好日志（检索命中率高）：

markdown

1	`【项目：WebApp】Nginx 反向代理配置完成`
2	`- 结果：监听 443 端口，反向代理部署成功`
3	`- 相关文件：/etc/nginx/sites-available/webapp.conf`
4	`- 经验教训：端口冲突导致方案 A 和 B 失败`
5	`- 检索标签：#webapp #nginx #部署 #反向代理`

记住三条原则：一件事一条日志、用结构化格式、必须加标签。

五、Skills 技能系统

Skills 就是给 AI 装插件。每个 Skill 是一个文件夹，里面有个 SKILL.md 描述它能干啥。

安装技能

bash

npm install -g clawhub
clawhub login
clawhub search "web scraping"
clawhub install target-skill
clawhub update --all

国内用户可以用腾讯云镜像：https://skillhub.tencent.com/

自定义 Skill

如果现有的不够用，可以自己开发：

code

1	`~/.openclaw/skills/my-skill/`
2	`├── SKILL.md # 技能描述`
3	`├── index.ts # 实现代码`
4	`└── package.json`

六、接入聊天平台

OpenClaw 最爽的就是能接到你日常用的聊天工具里。

海外：WhatsApp、Telegram、Discord、Slack、LINE、iMessage 国内：QQ、企业微信、飞书、钉钉、微信（通过企业微信间接接）

Telegram 接入

bash

1	`openclaw channels add --channel telegram`
2
3	`# 输入从 @BotFather 拿到的 Bot Token`
4	`openclaw channels status`

飞书接入

bash

1	`openclaw channels add --channel feishu`
2
3	`# 需要 App ID 和 App Secret`

踩坑提醒：不同通道的会话是独立的，但共享同一个 workspace 和记忆系统。所以你在 Telegram 里跟 AI 说的话，它在飞书里也能记住。但这也意味着你得在 AGENTS.md 里做好权限控制，群聊里别让 AI 暴露你的私人信息。

七、高级玩法

子 Agent 协作

主 Agent 可以把任务拆分给子 Agent 并行执行。比如一个去搜资料，一个去写代码，最后主 Agent 汇总结果。处理复杂任务的时候特别好用。

Cron 定时任务

每日晨报：定时搜新闻生成摘要
自动备份：定期检查备份重要文件
服务监控：定时探测服务状态，异常报警

八、性能调优和故障排查

模型选择建议

bash

1	`openclaw config set agents.defaults.model "gpt-4o"`
2
3	`# 聊天中临时切换`
4	`/model gpt-4o-mini`

日常简单任务：GPT-4o-mini 或 DeepSeek，便宜
复杂推理和代码：Claude 3.5 Sonnet 或 GPT-4o
中文场景：Qwen 或 DeepSeek

Token 优化

用 /compact 手动压缩上下文
AGENTS.md 里控制启动加载的文件数量
日志保持精简

故障排查

bash

openclaw doctor         # 一键诊断
openclaw gateway status # 检查网关
openclaw logs           # 看日志
openclaw channels status # 检查通道
openclaw config validate # 校验配置

常见问题：

AI 不回复 → 检查 Gateway 和 API Key
记忆丢失 → 确认 memoryFlush 开了
通道断连 → 重新 login
卡顿 → 换轻量模型

聊天内常用命令

/status — 健康状态
/compact — 压缩上下文
/new — 新会话
/model <名称> — 切换模型
/stop — 停止当前任务
/think — 切换深度思考模式

九、安全加固

OpenClaw 权限很大，安全配置不能马虎。

必须做的：

AGENTS.md 里定义哪些操作需要确认
不要在配置文件里放密码和 API Key
开启操作日志审计
群聊通道禁止访问私人记忆

绝对禁止的：

执行 rm -rf
未经确认就向外部发送数据
在群聊里展示其他通道的对话

安全原则：删文件用 trash 不用 rm，不确定就问，敏感操作二次确认。

十、总结

折腾 OpenClaw 也有一段时间了，说说我的感受：它确实是我用过的最强大的本地 AI 助手，没有之一。但前提是你要花时间把配置文件写好、把记忆系统调好、把安全边界划清楚。

新手建议的学习路径：

安装和基础配置（1-2 小时）
熟悉 workspace 配置文件（2-3 小时）
优化记忆系统（2-3 小时）
接入一个聊天通道（1-2 小时）
装几个实用 Skills（2-3 小时）

延伸资源：

官方文档：https://docs.openclaw.ai/zh-CN
GitHub：https://github.com/openclaw/openclaw
技能仓库：https://clawhub.ai/
系统化教程：yeasy/openclaw_guide

现在就开始动手吧，拥有一个 7x24 小时在线的全栈 AI 工程师，真的很香。

1	`npm i -g openclaw --registry=https://registry.npmmirror.com`
2
3	`# 或者用 pnpm`
4	`pnpm add -g openclaw`
5
6	`openclaw onboard --install-daemon`

1	`git clone https://github.com/openclaw/openclaw.git`
2	`cd openclaw`
3	`pnpm install`
4	`pnpm ui:build`
5	`pnpm build`
6	`pnpm openclaw onboard --install-daemon`
7	`pnpm gateway:watch # 开发模式，改代码自动重载`

1	`# User Profile`
2	`- 职业：全栈开发者`
3	`- 技术栈：Python, TypeScript, React`
4	`- 中文交流，代码注释用英文`
5	`- 时区：UTC+8`
6	`- 当前项目：SaaS 产品，Next.js + Supabase`

1	`{`
2	`"agents": {`
3	`"defaults": {`
4	`"compaction": {`
5	`"reserveTokensFloor": 20000,`
6	`"memoryFlush": {`
7	`"enabled": true,`
8	`"softThresholdTokens": 4000`
9	`}`
10	`}`
11	`}`
12	`}`
13	`}`

1	`【项目：WebApp】Nginx 反向代理配置完成`
2	`- 结果：监听 443 端口，反向代理部署成功`
3	`- 相关文件：/etc/nginx/sites-available/webapp.conf`
4	`- 经验教训：端口冲突导致方案 A 和 B 失败`
5	`- 检索标签：#webapp #nginx #部署 #反向代理`

OpenClaw深度使用教程从环境搭建到高级架构的实战指南

OpenClaw 深度使用教程：从环境搭建到高级架构的实战指南

OpenClaw 是 PSPDFKit 创始人 Peter Steinberger 搞的一个开源本地优先 AI 助手。简单来说，它不只是跟你聊天——它能直接帮你干活：读写文件、操控浏览器、收发邮件、跑代码，基本上就是一个住在你电脑里的全栈工程师。

一、OpenClaw 到底是个啥

二、安装：我踩过的坑都在这了

最快的方式：一键脚本

手动安装（我推荐的方式）

源码安装（适合想折腾的人）

初始化配置的关键步骤

三、配置文件：这才是 OpenClaw 的灵魂

SOUL.md 示例

USER.md 示例

AGENTS.md：最关键的一个

四、记忆系统：让 AI 不再"失忆"

memoryFlush 配置（必做！）

日志写得好不好，直接决定检索效果

记住三条原则：一件事一条日志、用结构化格式、必须加标签。

五、Skills 技能系统

安装技能

推荐安装的 Skills

自定义 Skill

六、接入聊天平台

Telegram 接入

飞书接入

踩坑提醒：不同通道的会话是独立的，但共享同一个 workspace 和记忆系统。所以你在 Telegram 里跟 AI 说的话，它在飞书里也能记住。但这也意味着你得在 AGENTS.md 里做好权限控制，群聊里别让 AI 暴露你的私人信息。

七、高级玩法

子 Agent 协作

Cron 定时任务

八、性能调优和故障排查

模型选择建议

Token 优化

故障排查

聊天内常用命令

九、安全加固

安全原则：删文件用 trash 不用 rm，不确定就问，敏感操作二次确认。

十、总结

1	`npm install -g clawhub`
2	`clawhub login`
3	`clawhub search "web scraping"`
4	`clawhub install target-skill`
5	`clawhub update --all`

1	`openclaw doctor # 一键诊断`
2	`openclaw gateway status # 检查网关`
3	`openclaw logs # 看日志`
4	`openclaw channels status # 检查通道`
5	`openclaw config validate # 校验配置`