awesome-openclaw-tutorial Documentation

Technical Documentation: xianyu110/awesome-openclaw-tutorial

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

🦞 Awesome OpenClaw Tutorial

🦞 一本书玩转OpenClaw：超级个体实战指南

从零开始打造你的AI工作助手：最全面的中文教程，涵盖安装、配置、实战案例和避坑指南

🔥 2026 年 10 月 · 作者正在更新的新项目

OpenClaw 教程继续保留在下方 👇。这里先列出作者近期正在维护的新仓库，内容方向相近，欢迎顺手看看、点个 Star。

预览	项目	一句话介绍	Stars
	awesome-gpt-6-astra · 在线站	GPT-6 Astra 社区案例合集：游戏、3D、网页、Computer Use 等可玩 Demo，每条附作者与原帖
	awesome-gpt-image2.5 · 画廊	ChatGPT Images 2.5（Flare · Sunburst · Sketch）好玩用法画廊，可直接抄的 prompt 与评测
	awesome-minimax-h3-prompts · 在线浏览	MiniMax H3（海螺 3.0）视频提示词精选，每条配生成片段与作者署名
	awesome-gptimage2 · 在线站	GPT Image 2 中文提示词实战手册：电商、海报、产品图等可复制的商业场景 prompt
	gpt-codex · 教程站	写给小白的 OpenAI Codex 中文教程：从 0 到 1 把 Codex 真正用起来
	awesome-codex-tutorial · 在线版	Codex 中文教程库：入门教程、系列图文教程、实战案例库与速查资料
	awesome-claudcode-tutorial · 在线阅读	最全面的 Claude Code 中文教程，从零基础到企业级应用

🦞 以下为 OpenClaw 中文教程原有内容，持续保留并按版本校对。

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

🔄 2026-09-10 更新说明：本仓库当前按 OpenClaw v2026.9.3（稳定版，2026-09-08 发布） 校对；第 1/2/5/7/8/10~15 章已同步到 2026.9 主线。跨版本请先读 updates/2026-09-10-v2026.9.3.md，升级后执行 openclaw doctor --fix。

📌 本教程与 OpenClaw 最新版差异说明

为了避免你把旧章节当成最新版官方教程，先看这 4 点：

当前教程基线：本仓库目前按 v2026.9.3 稳定版校对；如果 GitHub Releases 或 npm 出现更高版本，请以官方 Release Notes 和官方文档为准
已优先更新的章节：README、更新说明与第 1/2/5/7/8/10~15 章已按 2026.9 主线修订（含 2026.8 Breaking 迁移提示）
仍含历史内容的章节：第 3/4/6/9 章及部分 tutorials/ 一键部署文仍可能含旧截图/旧渠道步骤，适合作为思路参考，不建议直接复制执行
当前应优先使用的官方主线：openclaw onboard、openclaw models auth login --provider openai|…、openclaw doctor --fix、openclaw infer ...、openclaw skills …、Task Flow、Webhooks、/usage

类型	本教程当前状态	阅读建议
版本基线	已对齐 `v2026.9.3`	新手优先按这个版本跑通
运行时	Node 24.16+ 或 26.1+（推荐 26）	先升 Node 再升 OpenClaw
跨版本迁移	强调 `openclaw doctor --fix`	处理 `openai/*` 路由、OpenProse 清理、会话 SQLite
安装/配置主线	已补 2026.9 入口	优先看第 `2` 章和第 `11` 章
媒体/创意能力	保留 `infer` / 媒体生成 / `ComfyUI` 主线	优先看第 `10` 章和第 `14` 章
旧 Skill 生态	明确标为历史参考	用 `openclaw skills`，不要默认 `clawhub install …`

⚠️ 一句话判断：如果你看到 openai-codex/*、codex/*、/prose、local-anthropic、bananapro-image-gen、整串 clawhub install ...，请先把它理解为“历史参考或需迁移项”，不要默认当成 2026.9 官方推荐步骤。

🚀 30秒快速选择：哪种部署方式适合你？

你的情况	推荐方案	为什么	开始时间
完全小白，想最快体验	飞书妙搭 ⭐	免费 + 1分钟完成 + 每日100万Tokens	→ 立即开始
有服务器，想可视化管理	宝塔面板	免费插件 + 面板管理 + 一键安装	→ 3分钟搞定
企业级，需要高安全性	JVSClaw	14天免费 + 6核12GB + 端到端加密	→ 需邀请码
想用浏览器操控	Kimi Claw	Kimi K2.5 + 浏览器控制	→ 200元/月
量化交易/多IM	腾讯 WorkBuddy	桌面端Agent + 多IM支持	→ 送5000积分
macOS原生体验	QClaw	腾讯官方桌面客户端 + 全量公测	→ 免费
Agent生态丰富	扣子 OpenClaw	1800+Skills	→ 99元/月起

📖 查看完整一键部署教程 →

📊 教程导航（按学习路径）

🎯 零基础入门（必读）

📖 第1章：认识OpenClaw - 5分钟了解核心价值
🚀 第2章：快速部署 - 选择适合你的部署方式
💬 第3章：快速上手 - 发送第一条消息

🔥 核心功能（实战）

📁 第4章：文件管理 - 效率提升81%
🧠 第5章：知识库 - 第二大脑系统 + Active Memory / Dreaming 补充
📅 第6章：日程管理 - AI自动创建日程
⚙️ 第7章：自动化 - 定时任务 + Task Flow / Webhooks 更新

💎 进阶技能（提升）

🔌 第8章：Skills扩展 - 1800+技能
🤖 第9章：多平台集成 - 飞书/企微/钉钉/QQ/微信
🔗 第10章：API 与外部能力集成 - infer / webhooks / 媒体工作流
⚙️ 第11章：高级配置 - 模型 / 记忆 / 审批 / 性能

🎯 实战案例（直接套用）

👔 第12章：个人效率实战 - 知识工作 / 编程 / 创作 / 学习 / 个人运营
🔗 第13章：高级自动化 - cron / tasks / Task Flow / hooks / standing orders
🎨 第14章：创意应用 - 图片 / 视频 / 音乐 / TTS / ComfyUI
🚀 第15章：一人公司实战 - 选题 / 交付 / 分发 / 复盘

📚 附录工具（速查）

🆘 遇到问题？快速解决

🔧 常见问题速查（点击展开）

安装配置问题

使用问题

AI变"哑巴"了？ → 切换到 full profile
Gateway启动失败？ → 检查认证配置

成本优化

API费用太高？
如何省钱？ - 使用国产模型节省95%

找不到答案？

📖 完整FAQ
💬 提交问题

🚨 重要版本提示

⚠️ 2026.3.7版本：Gateway认证要求（Breaking Change）

Gateway认证现在必须显式设置 gateway.auth.mode（token 或 password）

快速修复：

bash

openclaw config set gateway.auth.mode token
openclaw config set gateway.auth.token "your-secret-token"
openclaw gateway restart

🔧 2026.3.2版本：AI变"哑巴"了？

症状：只能聊天不能干活（文件管理、命令执行失效）
原因：默认profile改为 messaging（纯聊天模式）
修复：切换到 full profile

bash

openclaw config set tools.profile full
openclaw gateway restart

5种Profile说明：

Profile	功能说明
`messaging`	只能发布消息、管理会话
`default`	默认工具集（不含命令执行）
`coding`	编程相关工具
`full`	完整工具集，包含命令执行（推荐）
`all`	所有工具全开

🆕 v2026.3.12 重大更新（2026年3月）

建议所有用户升级，包含大量安全修复

新功能

Control UI 全面重设计：模块化 Dashboard，含概览/聊天/配置/Agent/Session 视图，支持命令面板、移动端底部 Tab、slash 命令、消息导出和消息置顶
/fast 快速模式开关：支持切换 OpenAI / Anthropic 的 fast tier，更省钱更快
Kubernetes 支持：新增 K8s 安装路径（支持 Kind 和 raw manifests）
sessions_yield 工具：Agent 可立即结束当前轮次并携带后续载荷，流程控制更灵活
Slack Block Kit：Slack 频道消息支持 Block Kit 富文本格式

重要安全修复（建议立即升级）

修复跨站 WebSocket 劫持路径
修复 workspace plugin 隐式自动加载（防止恶意代码执行）
修复 /config、/debug 权限绕过
修复共享 token 范围自我提权
多处 exec 审批绕过修复

🆕 v2026.3.13 更新（2026年3月中旬）

新功能

Chrome DevTools MCP attach 模式：可直接连接已登录的 Chrome 浏览器进行自动化操作，无需重新登录
Ollama 一键安装引导：支持 Local 和 Cloud+Local 混合模式，本地模型更好用
多模态记忆索引：图片/音频内容可用 Gemini Embedding 进行语义检索
Docker 时区支持：新增 OPENCLAW_TZ 环境变量
iOS 首次运行引导页：新用户体验大幅提升

Bug 修复

修复工具密集型运行时 Dashboard UI 卡死/重渲染风暴
修复 Windows 下 gateway 重启时弹出控制台黑窗口
修复 setup code 可被重放攻击的安全漏洞
插件 SDK 去重，修复约 2 倍内存膨胀问题

🆕 v2026.9.3 稳定版更新（2026年9月8日）

当前基线

稳定版：v2026.9.3
推荐运行时：Node 26（或 Node 24.16+）；不再支持 Node 22
校验方式：npm view openclaw version 应返回 2026.9.3
完整跳变说明：updates/2026-09-10-v2026.9.3.md

从 2026.6.8 跳到 2026.9.3，教学上最关键的变化

OpenClaw 2.0（2026.8.1）：会话/转录迁入 SQLite；Control UI / onboarding 大改；升级前务必备份
OpenAI 路由迁移：codex/*、openai-codex/* → openai/*（openclaw doctor --fix）
OpenProse 移除：内置插件与 /prose 下线；清配置用 Doctor，需要时再装上游 Agent Skill
Skills / Workshop：优先 openclaw skills；Workshop 按 Agent 持久化；clawhub install … 降为历史参考
更新恢复（2026.9.x）：更新可预演、失败恢复更干净；关注 openclaw update status
仍沿用的 2026.6 主线：Active Memory / Memory Wiki、infer、Task Flow / Webhooks、媒体生成、/usage

升级命令：

bash

# 先确认 Node
node -v   # 需要 24.16+ 或 26.1+

openclaw update --tag 2026.9.3 --yes
openclaw update repair
openclaw doctor --fix
openclaw --version  # 确认版本为 2026.9.3

⚠️ 新手建议：目标是“按教程稳定跑通”就用 v2026.9.3。若 openclaw update 失败，可用 npm install [email protected] --allow-scripts=openclaw 兜底。升级后先跑 openclaw doctor --fix、openclaw models status --probe 和 openclaw channels status。

📎 历史基线：v2026.6.8（2026年6月16日）

以下内容保留为历史对照，不再作为当前推荐基线。

当时推荐运行时多为 Node 24 / 兼容 Node 22.19+
确立了 Active Memory、Dreaming、Memory Wiki、Task Flow、Webhooks、openclaw infer、内建媒体与 /usage footer 等主线
若你的笔记/脚本仍写着 openai-codex/* 或整串 clawhub install …，请按上文迁移到 2026.9 主线

📖 纸质书：《OpenClaw超级个体实操手册》

⚠️ 当前说明：开源教程的第 1/2/5/7/8/10~15 章已按 v2026.9.3 主线修订；纸质书仍然是更系统的重写版，适合需要完整、稳定、逐条验证内容的读者。

纸质书已全面修正，现已上市！

清华大学出版社出版《OpenClaw超级个体实操手册》，在开源教程基础上做了全面重写+逐条验证：

🔍 144条CLI命令对照官方文档逐条核对（教程中约60%已删除或修正）
✅ 9套配置模板全部在v2026.3.7+实际跑通
🛡️ 新增安全防护指南 + 国产Claw全景指南
📦 7份随书附赠电子资料

🛒 购买链接：京东专属链接（¥42，原价¥59.8）

📦 本地一键部署安装包：https://tryopenclaw.asia/

📖 关于本教程

🎯 教程特色

超级个体定位 - 一个人+OpenClaw=无限可能，效率提升10倍
云端部署优先 - 降低技术门槛，手机随时使用
国产模型为主 - 成本低、速度快、中文友好
实战案例丰富 - 70+完整工作流，可直接应用
中国本土化 - 企业微信/钉钉/飞书深度集成
完整资源导航 - 官方资源、社区资源、学习路径

📊 教程规模

✅ 15章节正文：约267,000字
✅ 15个附录：约141,000字
✅ 总字数：408,000字
✅ 70+实战案例：可直接应用
✅ 完整配图：50+张配置截图

🎯 适合人群

🚀 超级个体：想要一个人顶一个团队，实现个人价值最大化
🔰 完全新手：从零开始，手把手教你安装配置
💼 知识工作者：学习如何用OpenClaw提升10倍个人效率
👨‍💻 开发者：深入了解Skills开发和API集成
✍️ 内容创作者：探索自动化工作流和高级应用

📚 完整教程目录

第一部分：零基础入门（3章节）

第二部分：核心功能（4章节）

第三部分：进阶技能（4章节）

第四部分：实战案例（4章节）

🔗 官方资源

OpenClaw官方网站：https://openclaw.ai
OpenClaw官方文档：https://docs.openclaw.ai
GitHub仓库：https://github.com/openclaw/openclaw
ClawHub技能广场：https://clawhub.ai
Awesome Skills合集：https://github.com/VoltAgent/awesome-openclaw-skills

💡 实战案例精选

📦 配置示例（开箱即用）

🎬 实战场景

📊 成本对比

方案	月费用	适用场景
飞书妙搭	免费	新手推荐（限时）
云端部署	20-50元	无Mac/24小时运行
本地部署	0元	有Mac电脑
API费用（DeepSeek）	5-30元	日常使用
API费用（Kimi）	10-50元	长文档处理

💡 省钱技巧：使用国产大模型（DeepSeek、Kimi）节省**50%-70%**成本

🤝 贡献指南

欢迎贡献你的经验和案例！

Fork本仓库
创建你的分支 (git checkout -b feature/AmazingFeature)
提交你的修改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
提交Pull Request

📮 联系方式

社交媒体

GitHub: @xianyu110
CSDN专栏: OpenClaw从入门到精通
B站: @MaynorAI
YouTube: @buguniao537
X (Twitter): @Nikitka_aktikiN

项目链接

Clawbot项目: 700+ Stars
两万人AI社区主理人

📈 项目进度

✅ v1.12（2026-09-10）：同步 OpenClaw v2026.9.3，覆盖 README / 安装升级 / 模型路由迁移 / Doctor / 关键章节基线，并新增 updates/2026-09-10-v2026.9.3.md
✅ v1.11（2026-06-18）：同步 OpenClaw v2026.6.8 稳定版，更新安装升级命令、版本基线、模型/渠道/usage/search 说明
✅ v1.10（2026-04-16）：第 10~15 章按 OpenClaw v2026.4.14 稳定版主线重写，并同步 README / 章节入口 / 纸书推荐文案
✅ v1.9（2026-04-04）：同步橙皮书 v1.3~v1.4 更新——新增微信ClawBot、腾讯全家桶、浏览器渠道、GLM-5-Turbo、安全漏洞统计
✅ v1.6（2026-03-18）：新增一键部署教程（8个平台）
🔄 后续：继续清理第 3/4/6/9 章与 tutorials/ 中的旧截图、旧渠道步骤

📄 许可证

本项目采用 GPL-3.0 License

⚠️ 重要声明：禁止倒卖

❌ 严禁倒卖：禁止将本教程打包后进行商业售卖
❌ 严禁闭源商用：任何基于本项目的衍生作品必须同样开源
✅ 允许学习：欢迎个人学习和使用
✅ 允许分享：欢迎分享给更多需要的人
✅ 允许修改：可以修改并分享，但必须保持开源

Overview (`examples/README.md`)

OpenClaw 示例文件

这个目录包含了 OpenClaw 的各种配置文件、自动化脚本和 Skills 开发示例。

📁 目录结构

text

examples/
├── configs/              # 配置文件示例
│   ├── basic-config.json           # 基础配置（新手入门）
│   ├── multi-model-config.json     # 多模型配置
│   ├── multi-agent-config.json     # 多Agent配置
│   └── feishu-config.json          # 飞书Bot配置
├── automation/           # 自动化脚本
│   ├── daily-report.sh             # 每日AI日报生成
│   ├── backup-config.sh            # 配置备份
│   ├── batch-process-files.sh      # 批量文件处理
│   └── website-monitor.sh          # 网站内容监控
└── skills/               # Skills开发示例
    ├── custom-skill-template.js    # 自定义Skill模板
    └── weather-skill-example.js    # 天气查询示例

📋 配置文件说明

basic-config.json

最简单的配置，适合新手入门：

Token认证
单个Agent
基础配置

使用方法：

bash

cp examples/configs/basic-config.json ~/.openclaw/openclaw.json
# 编辑配置文件，填入你的token和API密钥

multi-model-config.json

多模型配置，不同场景使用不同模型：

DeepSeek：日常使用，成本低
Kimi：长文档处理
GPT-4：复杂推理任务

使用方法：

bash

cp examples/configs/multi-model-config.json ~/.openclaw/openclaw.json
# 根据需要修改模型配置

multi-agent-config.json

多Agent配置，专业分工：

工作助手：处理工作相关事务
个人助手：日常对话和娱乐
代码助手：编程相关任务
内容助手：内容创作

使用方法：

bash

cp examples/configs/multi-agent-config.json ~/.openclaw/openclaw.json
# 根据需求调整各Agent的配置

feishu-config.json

飞书Bot完整配置：

飞书应用配置
认证设置
Agent配置

使用方法：

bash

cp examples/configs/feishu-config.json ~/.openclaw/openclaw.json
# 填入你的飞书应用信息

🤖 自动化脚本说明

daily-report.sh

每天自动生成AI行业日报并发送到指定平台。

使用方法：

bash

# 1. 赋予执行权限
chmod +x examples/automation/daily-report.sh

# 2. 编辑脚本，配置你的API和通知方式
vim examples/automation/daily-report.sh

# 3. 添加到crontab（每天早上9点执行）
crontab -e
# 添加以下行：
0 9 * * * /path/to/examples/automation/daily-report.sh

backup-config.sh

自动备份OpenClaw配置文件。

使用方法：

bash

# 1. 赋予执行权限
chmod +x examples/automation/backup-config.sh

# 2. 手动执行备份
./examples/automation/backup-config.sh

# 3. 添加到crontab（每天凌晨2点备份）
crontab -e
# 添加以下行：
0 2 * * * /path/to/examples/automation/backup-config.sh

batch-process-files.sh

批量处理文件的脚本模板。

使用方法：

bash

# 1. 赋予执行权限
chmod +x examples/automation/batch-process-files.sh

# 2. 根据需求修改脚本中的处理逻辑
vim examples/automation/batch-process-files.sh

# 3. 执行脚本
./examples/automation/batch-process-files.sh ./input ./output

website-monitor.sh

监控网站内容变化，发现变化时发送通知。

使用方法：

bash

# 1. 赋予执行权限
chmod +x examples/automation/website-monitor.sh

# 2. 执行监控
./examples/automation/website-monitor.sh "https://example.com" "关键词" feishu

# 3. 添加到crontab（每小时检查一次）
crontab -e
# 添加以下行：
0 * * * * /path/to/examples/automation/website-monitor.sh "https://example.com" "关键词" feishu

🔧 Skills开发说明

custom-skill-template.js

完整的Skill开发模板，包含所有生命周期钩子和最佳实践。

使用方法：

bash

# 1. 复制模板
cp examples/skills/custom-skill-template.js ~/.openclaw/skills/my-skill.js

# 2. 编辑模板，实现你的功能
vim ~/.openclaw/skills/my-skill.js

# 3. 在 openclaw.json 中注册Skill
{
  "skills": {
    "my-skill": {
      "enabled": true,
      "path": "~/.openclaw/skills/my-skill.js"
    }
  }
}

weather-skill-example.js

实用的天气查询Skill示例，展示如何：

解析用户意图
调用外部API
格式化响应
错误处理

使用方法：

bash

# 1. 复制示例
cp examples/skills/weather-skill-example.js ~/.openclaw/skills/weather-query.js

# 2. 配置API密钥（可选）
vim ~/.openclaw/openclaw.json
# 添加：
{
  "skills": {
    "weather-query": {
      "apiKey": "your-weather-api-key"
    }
  }
}

# 3. 重启OpenClaw
openclaw gateway restart

⚠️ 注意事项

配置文件安全：
- 不要将包含API密钥的配置文件提交到Git
- 使用环境变量存储敏感信息
- 定期轮换密钥
脚本权限：
- 执行前务必检查脚本内容
- 只运行可信来源的脚本
- 使用chmod +x赋予执行权限
Skill开发：
- 遵循OpenClaw Skill规范
- 添加完整的错误处理
- 编写清晰的文档
自动化任务：
- 测试脚本后再添加到crontab
- 确保脚本有正确的日志记录
- 定期检查执行日志

📚 更多资源

💡 贡献

欢迎提交你的示例和配置！请参考贡献指南。

Overview (`scripts/README.md`)

CSDN 自动发文工具

基于 Selenium 的 CSDN 自动发文工具，支持单篇和批量发布。

📋 功能特性

✅ 自动登录: 扫码登录，安全可靠
✅ 自动填写: 标题、正文、分类、标签
✅ Markdown 支持: 自动切换到 Markdown 编辑模式
✅ 批量发布: 一键发布所有 15 篇文章
✅ 人工确认: 填写完成后人工检查再发布

🔧 环境要求

Python 3.7+
Chrome 浏览器
ChromeDriver（与 Chrome 版本匹配）

📦 安装步骤

1. 安装 Python 依赖

bash

cd scripts
pip install -r requirements.txt

2. 安装 ChromeDriver

方法 A: 自动安装（推荐）

bash

pip install webdriver-manager

脚本会自动下载匹配的 ChromeDriver。

方法 B: 手动安装

检查 Chrome 版本: chrome://version/
下载对应版本: https://chromedriver.chromium.org/
将 ChromeDriver 放到 PATH 中

🚀 使用方法

方式 1: 单篇发布

bash

cd scripts
python csdn_auto_publisher.py ../csdn_articles/01-introduction_csdn.md

方式 2: 批量发布（推荐）

bash

cd scripts
python batch_publish_csdn.py

📝 使用流程

1. 启动脚本

bash

python batch_publish_csdn.py

2. 扫码登录

脚本会自动打开 Chrome 浏览器
显示 CSDN 登录二维码
使用 CSDN App 扫码登录
登录成功后脚本自动继续

3. 自动填写文章

脚本会自动：

打开文章编辑页面
切换到 Markdown 模式
填写标题和正文
选择分类
添加标签

4. 人工确认发布

检查文章内容是否正确
手动点击"发布"按钮
按回车继续下一篇

⚙️ 配置选项

修改分类和标签

编辑 batch_publish_csdn.py:

python

publisher.publish_article(
    title=title,
    content=content,
    category="OpenClaw从入门到精通",  # 修改分类
    tags=["OpenClaw", "AI助手", "人工智能", "Agent"]  # 修改标签
)

无头模式（后台运行）

编辑 csdn_auto_publisher.py:

python

publisher = CSDNAutoPublisher(headless=True)  # 改为 True

⚠️ 注意: 无头模式下无法扫码登录，建议先在有头模式下登录，保存 cookies 后再使用无头模式。

📂 文章列表

脚本会自动读取 csdn_articles/ 目录下的所有文章：

01-introduction_csdn.md - OpenClaw 是什么？
02-installation_csdn.md - 安装教程
03-quick-start_csdn.md - 快速上手
04-file-management_csdn.md - 本地文件管理
05-knowledge-management_csdn.md - 个人知识库
06-schedule-management_csdn.md - 日程管理
07-automation-workflow_csdn.md - 自动化工作流
08-skills-extension_csdn.md - Skills 扩展
09-multi-platform-integration_csdn.md - 多平台集成
10-api-integration_csdn.md - API 服务集成
11-advanced-configuration_csdn.md - 高级配置
12-personal-productivity_csdn.md - 效率提升实战
13-advanced-automation_csdn.md - 高级自动化工作流
14-creative-applications_csdn.md - 创意应用探索
15-solo-entrepreneur-cases_csdn.md - 超级个体实战

❓ 常见问题

Q1: ChromeDriver 版本不匹配

错误: This version of ChromeDriver only supports Chrome version XX

解决:

bash

pip install --upgrade webdriver-manager

或手动下载匹配版本的 ChromeDriver。

Q2: 登录超时

错误: ✗ 登录超时，请重试

解决:

确保网络连接正常
快速扫码（二维码有效期 2 分钟）
修改等待时间（代码中的 WebDriverWait 参数）

Q3: 找不到元素

错误: NoSuchElementException

解决:

等待页面加载完成
检查 CSDN 页面结构是否更新
使用浏览器开发者工具检查元素选择器

Q4: 内容未同步

现象: 填写后内容显示为空

解决:

增加等待时间（修改 time.sleep(3)）
检查是否成功切换到 Markdown 模式
手动复制粘贴内容作为备选方案

🎯 发布建议

发布时间

工作日: 9:00-10:00 或 20:00-21:00
周末: 10:00-11:00
避免: 深夜 23:00-7:00

发布频率

每天发布 2-3 篇
避免一次性发布全部（可能被限流）
建议分 5-7 天发布完

互动运营

发布后及时回复评论
在文末添加"点赞、收藏、关注"引导
分享到朋友圈、微信群

🔐 安全说明

Cookie 和登录信息仅保存在本地浏览器
不会上传任何账号密码
建议使用专用账号进行自动化操作

📊 进阶功能

保存 Cookies 避免重复登录

修改脚本保存 cookies 到文件：

python

import json

# 保存 cookies
with open("cookies.json", "w") as f:
    json.dump(driver.get_cookies(), f)

# 加载 cookies
with open("cookies.json", "r") as f:
    cookies = json.load(f)
    for cookie in cookies:
        driver.add_cookie(cookie)

定时发布

使用 cron 或任务计划程序定时运行脚本：

bash

# 每天上午 9 点运行
0 9 * * * cd /path/to/scripts && python batch_publish_csdn.py

📞 技术支持

遇到问题请在 GitHub 提交 Issue：
https://github.com/xianyu110/awesome-openclaw-tutorial/issues

📄 许可证

GPL-3.0 License

Overview (`.claude/.skills/bananapro-image-gen/README.md`)

Banana Pro Image Generation Skill

使用 Gemini 3 Pro Image 生成图片的 AI Skill，支持白板图、Logo设计、社交媒体配图等多种场景。

✨ 特性

🎨 文生图：根据文字描述生成各种风格的图片
📝 白板图：生成手写风格的概念图、流程图
🖼️ Logo设计：创建简约现代的Logo和图标
📱 社交媒体配图：生成适合各平台的配图
🌏 中文支持：完美支持中文提示词
⚡ 快速响应：10-30秒生成
💰 成本低廉：$0.04-0.16/张

🚀 快速开始

安装

bash

# 通过 npx（推荐）
npx skills add xianyu110/awesome-openclaw-tutorial@bananapro-image-gen

# 或手动克隆
git clone https://github.com/xianyu110/awesome-openclaw-tutorial.git
cd .claude/.skills/bananapro-image-gen
pip install -r requirements.txt

配置

bash

# 设置 API Key
export NEXTAI_API_KEY="your-api-key-here"

使用

bash

# 生成图片
python scripts/generate_image.py \
  --prompt "画一只可爱的橙色猫咪" \
  --filename "cat.png"

# 生成白板图
python scripts/generate_image.py \
  --prompt "生成一张白板图片，展示OpenClaw核心架构，手写字体风格" \
  --filename "whiteboard.png"

# 生成高清Logo
python scripts/generate_image.py \
  --prompt "设计一个AI助手Logo，蓝色渐变，现代简约" \
  --filename "logo.png" \
  --resolution 2K

📖 使用场景

1. 教程配图

bash

python scripts/generate_image.py \
  --prompt "生成一张白板图片，手写字体风格，总结OpenClaw核心要点" \
  --filename "tutorial.png"

2. Logo设计

bash

python scripts/generate_image.py \
  --prompt "设计一个超级个体Logo，蓝色和橙色，现代科技感" \
  --filename "logo.png" \
  --resolution 2K

3. 社交媒体配图

bash

python scripts/generate_image.py \
  --prompt "生成小红书配图，主题是AI效率提升，9:16竖版" \
  --filename "social.png" \
  --resolution 2K

📝 提示词技巧

白板图模板

text

生成一张白板图片，手写字体风格，内容包含：
- 标题：[主题]
- 要点1：[内容]
- 要点2：[内容]
使用箭头、框图等手绘元素

Logo设计模板

text

设计一个[主题]Logo，要求：
- 形状：[圆形/方形]
- 颜色：[主色调]
- 风格：[现代/简约]
- 用途：[社交媒体/网站]

🛠️ 参数说明

参数	说明	默认值
`--prompt`	图片描述（必需）	-
`--filename`	输出文件名	自动生成
`--resolution`	分辨率（1K/2K/4K）	1K
`--api-key`	API密钥	环境变量

💰 成本参考

1K 分辨率：~$0.04/张
2K 分辨率：~$0.08/张
4K 分辨率：~$0.16/张

📚 文档

完整文档 - 详细的使用指南和示例
教程 - OpenClaw 超级个体实战指南

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 详见 LICENSE

👤 作者

GitHub: @xianyu110
项目: OpenClaw 超级个体实战指南

⭐ 如果觉得有用，请给个 Star 支持一下！

Overview (`.claude/.skills/bananapro-image-gen/release/bananapro-image-gen/README.md`)

Nano Banana Image Generation - 快速开始

使用 Chat Completions 格式生成图片的 OpenClaw Skill。

🚀 快速开始（3步）

第1步：测试生成

bash

cd skills/bananapro-image-gen

# 生成一张图片
python scripts/generate_image.py \
  --prompt "画一只可爱的橙色猫咪" \
  --filename "cat.png"

第2步：查看结果

bash

# macOS
open cat.png

# Linux
xdg-open cat.png

第3步：生成白板图

bash

python scripts/generate_image.py \
  --prompt "生成一张白板图片，手写字体风格，内容是OpenClaw核心概念" \
  --filename "whiteboard.png"

📋 常用命令

基础生成

bash

python scripts/generate_image.py -p "画只猫" -f "cat.png"

指定分辨率

bash

python scripts/generate_image.py -p "画只猫" -f "cat.png" -r 2K

指定模型

bash

python scripts/generate_image.py -p "画只猫" -m "gpt-4o-image" -f "cat.png"

🎨 实用示例

1. 社交媒体配图

bash

python scripts/generate_image.py \
  -p "科技感的社交媒体封面，AI助手主题，蓝色渐变" \
  -f "social_cover.png" \
  -r 2K

2. Logo 设计

bash

python scripts/generate_image.py \
  -p "极简AI机器人Logo，蓝白配色，线条简洁" \
  -f "logo.png"

3. 概念白板图

bash

python scripts/generate_image.py \
  -p "白板图，手写字体，OpenClaw vs ChatGPT对比表格" \
  -f "comparison.png"

4. 流程图

bash

python scripts/generate_image.py \
  -p "流程图，手绘风格，展示OpenClaw工作流程，包含5个步骤" \
  -f "workflow.png"

⚙️ 配置说明

默认配置（无需设置）

脚本已内置 API 配置，可直接使用。

自定义配置（可选）

bash

# 设置环境变量
export NEXTAI_API_KEY="your-api-key"

# 或使用命令行参数
python scripts/generate_image.py -p "画只猫" -k "your-api-key"

📊 参数说明

参数	说明	示例
`-p`	图片描述（必需）	"画只猫"
`-f`	输出文件名	"cat.png"
`-m`	模型名称	"gpt-4o-image"
`-r`	分辨率	"1K", "2K", "4K"
`-k`	API Key	"sk-xxx"

🐛 常见问题

问题1：生成失败

解决方案：

检查网络连接
确认 API Key 有效
简化提示词重试

问题2：图片质量不理想

解决方案：

使用更详细的提示词
指定风格和细节
尝试不同的模型

问题3：生成速度慢

说明：

正常情况 10-30 秒
复杂图片可能需要 1-2 分钟
请耐心等待

📚 更多信息

完整文档：SKILL.md
提示词技巧：查看 SKILL.md 中的"提示词技巧"章节
实战案例：查看 SKILL.md 中的"实战案例"章节

💡 提示词技巧

白板图模板

text

生成一张白板图片，手写字体风格，内容包含：
- 标题：[主题]
- 要点1：[内容]
- 要点2：[内容]
使用箭头和框图

对比表格模板

text

生成对比表格图片，清晰易读：
- 标题：[A vs B]
- 对比维度：[维度1、维度2]
- 对比结果

🎯 下一步

✅ 阅读完整文档：SKILL.md
✅ 尝试不同的提示词
✅ 生成自己的图片
✅ 集成到 OpenClaw 工作流

📞 需要帮助？

GitHub Issues: 提交问题
完整教程：OpenClaw 超级个体实战指南

Api Key Config Guide (`docs/api-key-config-guide.md`)

OpenClaw API Key 配置完整指南

📋 配置方式概览

OpenClaw 支持多种 API Key 配置方式，每种方式都有其适用场景和优先级。

配置方式对比

方式	优先级	适用场景	持久化	难度
环境变量	⭐⭐⭐⭐⭐ 最高	临时测试、Docker、CI/CD	❌	⭐ 简单
Agent 专属配置	⭐⭐⭐⭐ 高	多 Agent 不同 Key	✅	⭐⭐ 中等
全局配置	⭐⭐⭐ 中	所有 Agent 共享	✅	⭐ 简单
配置向导	⭐⭐ 低	首次安装	✅	⭐ 简单

🔄 配置优先级

优先级顺序（从高到低）

text

1. 环境变量（最高优先级）
   ↓
2. Agent 专属配置
   ↓
3. 全局配置
   ↓
4. 配置向导
   ↓
5. 默认值（最低优先级）

优先级示例

假设你同时配置了：

bash

# 1. 环境变量
export ANTHROPIC_API_KEY="sk-ant-env"

# 2. Agent 配置
openclaw config set models.providers.anthropic.apiKey "sk-ant-agent" --agent tech-dev

# 3. 全局配置
openclaw config set models.providers.anthropic.apiKey "sk-ant-global"
```text
**实际使用**: `sk-ant-env`（环境变量优先级最高）

---

## 🎯 方式一：环境变量（推荐：临时测试）

### 适用场景

- ✅ 临时测试不同的 API Key
- ✅ Docker 容器部署
- ✅ CI/CD 自动化
- ✅ 不想写入配置文件
- ✅ 需要最高优先级

### 配置方法

#### 临时设置（当前会话）

```bash
# Anthropic
export ANTHROPIC_API_KEY="sk-ant-xxx"

# OpenAI
export OPENAI_API_KEY="sk-xxx"

# Google
export GOOGLE_API_KEY="xxx"

# DeepSeek
export DEEPSEEK_API_KEY="sk-xxx"

# Moonshot
export MOONSHOT_API_KEY="sk-xxx"
```text
#### 永久设置（写入 Shell 配置）

**macOS/Linux (zsh)**:
```bash
# 添加到 ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-ant-xxx"' >> ~/.zshrc
source ~/.zshrc
```text
**macOS/Linux (bash)**:
```bash
# 添加到 ~/.bashrc
echo 'export ANTHROPIC_API_KEY="sk-ant-xxx"' >> ~/.bashrc
source ~/.bashrc
```text
**Windows (PowerShell)**:
```powershell
# 临时设置
$env:ANTHROPIC_API_KEY="sk-ant-xxx"

# 永久设置（用户级）
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-xxx", "User")
```text
### 验证配置

```bash
# 查看环境变量
echo $ANTHROPIC_API_KEY

# 测试连接
openclaw models list
```text
### 优点和缺点

**优点**:
- ✅ 最高优先级，覆盖所有其他配置
- ✅ 灵活，易于切换
- ✅ 适合 Docker 和 CI/CD
- ✅ 不写入配置文件，更安全

**缺点**:
- ❌ 临时设置重启后失效
- ❌ 不适合多 Agent 场景
- ❌ 需要在每个终端会话中设置

---

## 🎯 方式二：Agent 专属配置（推荐：多 Agent）

### 适用场景

- ✅ 多个 Agent 使用不同的 API Key
- ✅ 需要隔离配置
- ✅ 长期使用
- ✅ 需要持久化

### 配置方法

#### 使用命令行

```bash
# 为特定 Agent 配置
openclaw config set models.providers.anthropic.apiKey "sk-ant-xxx" --agent tech-dev

# 为另一个 Agent 配置不同的 Key
openclaw config set models.providers.openai.apiKey "sk-yyy" --agent content-writer

# 验证配置
openclaw config get models.providers.anthropic.apiKey --agent tech-dev
```text
#### 直接编辑配置文件

**配置文件位置**: `~/.openclaw/agents/<agentId>/openclaw.json`

```bash
# 编辑配置文件
nano ~/.openclaw/agents/tech-dev/openclaw.json
```text
**配置内容**:
```json
{
  "models": {
    "default": "anthropic/claude-sonnet-4-5",
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxx",
        "baseUrl": "https://api.anthropic.com"
      }
    }
  }
}
```text
### 验证配置

```bash
# 查看 Agent 配置
openclaw config get --agent tech-dev

# 测试连接
openclaw agent --message --agent tech-dev "Hello"
```text
### 优点和缺点

**优点**:
- ✅ 每个 Agent 独立配置
- ✅ 配置隔离，互不影响
- ✅ 持久化存储
- ✅ 适合多 Agent 场景

**缺点**:
- ❌ 需要为每个 Agent 单独配置
- ❌ 管理成本较高
- ❌ 被环境变量覆盖

---

## 🎯 方式三：全局配置（推荐：单 Agent）

### 适用场景

- ✅ 所有 Agent 共享同一个 API Key
- ✅ 单 Agent 使用
- ✅ 长期使用
- ✅ 需要持久化

### 配置方法

#### 方法1：交互式命令（推荐新手）

```bash
# 运行交互式命令
openclaw models auth add

# 按提示操作：
# 1. 选择 provider（如 anthropic）
# 2. 输入 API Key
# 3. 确认保存
```text
#### 方法2：配置命令

```bash
# 直接设置
openclaw config set models.providers.anthropic.apiKey "sk-ant-xxx"

# 设置默认 model
openclaw config set models.default "anthropic/claude-sonnet-4-5"

# 验证配置
openclaw config get models.providers.anthropic.apiKey
```text
#### 方法3：直接编辑配置文件

**配置文件位置**: `~/.openclaw/openclaw.json`

```bash
# 编辑配置文件
nano ~/.openclaw/openclaw.json
```text
**配置内容**:
```json
{
  "models": {
    "default": "anthropic/claude-sonnet-4-5",
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxx"
      },
      "openai": {
        "apiKey": "sk-yyy"
      }
    }
  }
}
```text
### 验证配置

```bash
# 查看全局配置
openclaw config get

# 测试连接
openclaw models list
```text
### 优点和缺点

**优点**:
- ✅ 配置一次，全局生效
- ✅ 持久化存储
- ✅ 适合大多数场景
- ✅ 管理简单

**缺点**:
- ❌ 无法区分不同 Agent
- ❌ 被环境变量和 Agent 配置覆盖

---

## 🎯 方式四：配置向导（推荐：首次安装）

### 适用场景

- ✅ 首次安装 OpenClaw
- ✅ 不熟悉命令行
- ✅ 需要交互式引导

### 配置方法

```bash
# 运行配置向导
openclaw onboard

# 按提示操作：
# 1. 选择 provider
# 2. 输入 API Key
# 3. 选择默认 model
# 4. 完成配置
```text
### 验证配置

```bash
# 查看配置
openclaw config get

# 测试连接
openclaw channels status
```text
### 优点和缺点

**优点**:
- ✅ 交互式，不易出错
- ✅ 适合新手
- ✅ 一次性完成所有配置

**缺点**:
- ❌ 只能配置一次
- ❌ 修改配置需要其他方式
- ❌ 优先级最低

---

## 🔍 配置验证

### 检查配置是否生效

```bash
# 1. 查看配置
openclaw config get models.providers.anthropic.apiKey

# 2. 查看环境变量
echo $ANTHROPIC_API_KEY

# 3. 测试 API 连接
openclaw models list

# 4. 查看 Gateway 状态
openclaw channels status

# 5. 发送测试消息
openclaw agent --message "Hello, test API Key"
```text
### 查看生效的配置

```bash
# 查看当前使用的 model
openclaw config get models.default

# 查看所有 provider 配置
openclaw config get models.providers

# 以 JSON 格式输出
openclaw config get --json
```text
---

## 🔧 配置故障排查

### 问题1：配置后不生效

**症状**: 设置了 API Key，但仍然提示未配置

**排查步骤**:

1. **检查配置优先级**
   ```bash
   # 检查环境变量（最高优先级）
   echo $ANTHROPIC_API_KEY
   
   # 检查 Agent 配置
   openclaw config get models.providers.anthropic.apiKey --agent tech-dev
   
   # 检查全局配置
   openclaw config get models.providers.anthropic.apiKey

重启 Gateway
bash
```
openclaw gateway restart
```
查看日志
bash
```
openclaw logs --tail 50
```

验证 API Key 格式

bash

# Anthropic: sk-ant-xxx
# OpenAI: sk-xxx
# Google: xxx

问题2：多个 Agent 使用不同的 API Key

场景: 需要为不同的 Agent 配置不同的 API Key

解决方案:

bash

# 方案1：使用 Agent 专属配置
openclaw config set models.providers.anthropic.apiKey "sk-ant-xxx" --agent tech-dev
openclaw config set models.providers.openai.apiKey "sk-yyy" --agent content-writer

# 方案2：使用环境变量（临时切换）
export ANTHROPIC_API_KEY="sk-ant-xxx"
openclaw agent --message --agent tech-dev "Hello"

export ANTHROPIC_API_KEY="sk-ant-yyy"
openclaw agent --message --agent content-writer "Hello"
```text
---

### 问题3：如何切换 provider

**场景**: 需要在不同的 AI provider 之间切换

**解决方案**:

```bash
# 查看当前 provider
openclaw config get models.default

# 切换到 Anthropic
openclaw config set models.default "anthropic/claude-sonnet-4-5"

# 切换到 OpenAI
openclaw config set models.default "openai/gpt-4"

# 切换到 Google
openclaw config set models.default "google/gemini-pro"

# 验证
openclaw models list
```text
---

### 问题4：API Key 泄露了怎么办

**应急措施**:

1. **立即撤销旧 Key**
   - 登录 provider 控制台
   - 撤销泄露的 API Key

2. **生成新 Key**
   - 在 provider 控制台生成新 Key

3. **更新配置**
   ```bash
   # 更新全局配置
   openclaw config set models.providers.anthropic.apiKey "sk-ant-new"
   
   # 或更新环境变量
   export ANTHROPIC_API_KEY="sk-ant-new"

清理旧配置

bash

# 检查所有配置文件
grep -r "sk-ant-old" ~/.openclaw/

# 删除旧 Key
openclaw config unset models.providers.anthropic.apiKey

📋 配置最佳实践

🔐 安全建议

API Key 安全管理

不要硬编码 API Key
- ❌ 不要写在代码中
- ❌ 不要提交到 Git
- ✅ 使用环境变量或配置文件

使用 .gitignore

bash

# .gitignore
.openclaw/openclaw.json
.openclaw/agents/*/openclaw.json
.openclaw/credentials/
.env

定期轮换 API Key
- 每 3-6 个月更换一次
- 发现泄露立即更换
使用最小权限原则
- 只授予必要的权限
- 不同用途使用不同的 Key
监控 API 使用情况
- 定期检查 API 调用量
- 发现异常立即处理

📚 相关文档

配置文件结构完整指南 - 配置文件详细说明
第2章：安装配置 - 基础配置教程
第11章：高级配置 - 模型、记忆、审批与性能

💡 常见问题 FAQ

Q1: 我应该使用哪种配置方式？

A: 根据你的场景选择：

新手：使用配置向导或全局配置
多 Agent：使用 Agent 专属配置
临时测试：使用环境变量
Docker 部署：使用环境变量

Q2: 配置优先级是怎样的？

A: 环境变量 > Agent 配置 > 全局配置 > 配置向导 > 默认值

Q3: 如何查看当前使用的 API Key？

bash

openclaw config get models.providers.anthropic.apiKey
```text
### Q4: 配置后不生效怎么办？

**A**: 
1. 检查配置优先级
2. 重启 Gateway
3. 查看日志
4. 验证 API Key 格式

### Q5: 如何为不同的 Agent 配置不同的 API Key？

**A**: 
```bash
openclaw config set models.providers.anthropic.apiKey "sk-ant-xxx" --agent agent1
openclaw config set models.providers.openai.apiKey "sk-yyy" --agent agent2

最后更新: 2026-02-14
适用版本: OpenClaw 2026.3.2+

Config File Structure (`docs/config-file-structure.md`)

OpenClaw 配置文件结构完整指南

📁 配置文件目录结构

全局配置目录

text

~/.openclaw/                          # 全局配置根目录
├── openclaw.json                     # 全局配置（所有 Agent 共享）
├── credentials/                      # 认证凭据目录
│   └── oauth.json                   # OAuth 凭据
├── agents/                           # Agent 配置目录
│   ├── main-assistant/               # 主助理 Agent
│   │   ├── openclaw.json            # Agent 专属配置
│   │   ├── agent/
│   │   │   └── auth-profiles.json   # 认证配置
│   │   └── sessions/                # 会话记录
│   │       └── *.jsonl
│   └── tech-dev/                     # 技术开发 Agent
│       ├── openclaw.json
│       └── agent/
│           └── auth-profiles.json
├── skills/                           # 用户级 Skills
│   └── custom-skill/
│       └── SKILL.md
└── logs/                             # 日志文件
    └── openclaw.log

旧版配置目录（已废弃）

text

~/.openclaw-main-assistant/           # 旧版配置目录
└── openclaw.json                     # 不再使用，已迁移到新结构

⚠️ 注意: 如果你的系统中还有 ~/.openclaw-* 目录，建议运行 openclaw doctor 进行迁移。

📝 配置文件详解

1. 全局配置文件

路径: ~/.openclaw/openclaw.json

用途: 所有 Agent 共享的全局配置

优先级: 低于 Agent 专属配置

示例内容:

json

{
  "models": {
    "default": "anthropic/claude-sonnet-4-5",
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxx"
      }
    }
  },
  "gateway": {
    "mode": "local",
    "port": 18789
  }
}
```text
**查看命令**:
```bash
# 查看全局配置
openclaw config get

# 查看特定配置项
openclaw config get models.default

# 编辑配置文件
nano ~/.openclaw/openclaw.json
```text
---

### 2. Agent 专属配置

**路径**: `~/.openclaw/agents/<agentId>/openclaw.json`

**用途**: 特定 Agent 的专属配置

**优先级**: 高于全局配置

**示例内容**:
```json
{
  "models": {
    "default": "openai/gpt-4",
    "providers": {
      "openai": {
        "apiKey": "sk-xxx"
      }
    }
  },
  "persona": {
    "name": "技术开发助手",
    "role": "专注于代码开发和技术问题"
  }
}
```text
**查看命令**:
```bash
# 查看 Agent 配置
openclaw config get --agent tech-dev

# 设置 Agent 配置
openclaw config set models.default "openai/gpt-4" --agent tech-dev

# 编辑配置文件
nano ~/.openclaw/agents/tech-dev/openclaw.json
```text
---

### 3. 认证配置文件

**路径**: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`

**用途**: 存储 API Key 等认证信息

**优先级**: 最高（覆盖其他配置）

**示例内容**:
```json
{
  "profiles": [
    {
      "provider": "anthropic",
      "apiKey": "sk-ant-xxx",
      "createdAt": "2026-02-14T10:00:00Z"
    },
    {
      "provider": "openai",
      "apiKey": "sk-xxx",
      "createdAt": "2026-02-14T10:00:00Z"
    }
  ]
}
```text
**管理命令**:
```bash
# 添加认证（交互式）
openclaw models auth add

# 查看认证配置
cat ~/.openclaw/agents/main-assistant/agent/auth-profiles.json

# 删除认证
rm ~/.openclaw/agents/main-assistant/agent/auth-profiles.json
```text
---

### 4. OAuth 凭据文件

**路径**: `~/.openclaw/credentials/oauth.json`

**用途**: 存储 OAuth 登录凭据（旧版）

**优先级**: 低（建议使用 auth-profiles.json）

**示例内容**:
```json
{
  "google": {
    "accessToken": "ya29.xxx",
    "refreshToken": "1//xxx",
    "expiresAt": "2026-02-14T11:00:00Z"
  }
}
```text
**说明**: 这是旧版的认证方式，新版本建议使用 `auth-profiles.json`。

---

## 🔄 配置优先级

### 优先级顺序（从高到低）

环境变量（最高优先级）
↓
Agent 专属配置 (~/.openclaw/agents//openclaw.json)
↓
全局配置 (~/.openclaw/openclaw.json)
↓
默认值（最低优先级）

text

### 示例说明

假设你有以下配置：

**环境变量**:
```bash
export ANTHROPIC_API_KEY="sk-ant-env"
```text
**Agent 配置** (`~/.openclaw/agents/tech-dev/openclaw.json`):
```json
{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-agent"
      }
    }
  }
}
```text
**全局配置** (`~/.openclaw/openclaw.json`):
```json
{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-global"
      }
    }
  }
}
```text
**实际使用的 API Key**: `sk-ant-env`（环境变量优先级最高）

---

## 🔍 配置查看命令

### 查看配置文件位置

```bash
# 查看全局配置文件路径
openclaw config path

# 查看 Agent 配置文件路径
openclaw config path --agent tech-dev
```text
### 查看配置内容

```bash
# 查看所有配置
openclaw config get

# 查看特定配置项
openclaw config get models.providers.anthropic.apiKey

# 查看 Agent 配置
openclaw config get --agent tech-dev

# 以 JSON 格式输出
openclaw config get --json
```text
### 查看生效的配置

```bash
# 查看当前使用的 model
openclaw models list

# 查看 Gateway 状态
openclaw gateway status

# 查看所有 Agent
openclaw agents list
```text
---

## ⚙️ 配置修改命令

### 设置配置

```bash
# 设置全局配置
openclaw config set models.default "anthropic/claude-sonnet-4-5"

# 设置 Agent 配置
openclaw config set models.default "openai/gpt-4" --agent tech-dev

# 设置 API Key
openclaw config set models.providers.anthropic.apiKey "sk-ant-xxx"
```text
### 删除配置

```bash
# 删除配置项
openclaw config unset models.providers.anthropic.apiKey

# 删除 Agent 配置
openclaw config unset models.default --agent tech-dev
```text
### 重置配置

```bash
# 重置全局配置
openclaw config reset

# 重置 Agent 配置
openclaw config reset --agent tech-dev
```text
---

## 🛠️ 常见配置场景

### 场景1：单个 Agent，使用全局配置

**配置方式**:
```bash
# 在全局配置中设置 API Key
openclaw config set models.providers.anthropic.apiKey "sk-ant-xxx"
```text
**优点**:
- ✅ 配置一次，全局生效
- ✅ 管理简单

**缺点**:
- ❌ 所有 Agent 使用相同配置

---

### 场景2：多个 Agent，使用不同配置

**配置方式**:
```bash
# 为每个 Agent 单独配置
openclaw config set models.providers.anthropic.apiKey "sk-ant-xxx" --agent tech-dev
openclaw config set models.providers.openai.apiKey "sk-yyy" --agent content-writer
```text
**优点**:
- ✅ 每个 Agent 独立配置
- ✅ 灵活性高

**缺点**:
- ❌ 管理成本较高

---

### 场景3：使用环境变量（临时测试）

**配置方式**:
```bash
# 临时设置（当前会话）
export ANTHROPIC_API_KEY="sk-ant-xxx"

# 永久设置（添加到 ~/.zshrc）
echo 'export ANTHROPIC_API_KEY="sk-ant-xxx"' >> ~/.zshrc
source ~/.zshrc
```text
**优点**:
- ✅ 最高优先级
- ✅ 适合 Docker 和 CI/CD
- ✅ 不写入配置文件

**缺点**:
- ❌ 重启后失效（除非写入 shell 配置）

---

## 🔧 配置故障排查

### 问题1：配置后不生效

**排查步骤**:

1. **检查配置优先级**
   ```bash
   # 检查环境变量
   echo $ANTHROPIC_API_KEY
   
   # 查看生效的配置
   openclaw config get models.providers.anthropic.apiKey

重启 Gateway
bash
```
openclaw gateway restart
```
查看日志
bash
```
openclaw logs --tail 50
```

问题2：找不到配置文件

排查步骤:

检查配置文件是否存在

bash

ls -la ~/.openclaw/openclaw.json
ls -la ~/.openclaw/agents/*/openclaw.json

运行 doctor 命令
bash
```
openclaw doctor
```

手动创建配置文件

bash

mkdir -p ~/.openclaw
echo '{}' > ~/.openclaw/openclaw.json

问题3：多个 Agent 配置混乱

解决方案:

查看所有 Agent
bash
```
openclaw agents list
```

查看每个 Agent 的配置

bash

openclaw config get --agent main-assistant
openclaw config get --agent tech-dev

统一管理
- 使用全局配置 + Agent 覆盖
- 或者每个 Agent 完全独立配置

📋 配置文件模板

最小配置模板

json

{
  "models": {
    "default": "anthropic/claude-sonnet-4-5",
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxx"
      }
    }
  }
}
```text
### 完整配置模板

```json
{
  "models": {
    "default": "anthropic/claude-sonnet-4-5",
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxx",
        "baseUrl": "https://api.anthropic.com"
      },
      "openai": {
        "apiKey": "sk-xxx",
        "baseUrl": "https://api.openai.com"
      }
    }
  },
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "loopback"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "xxx"
    },
    "discord": {
      "enabled": true,
      "token": "xxx"
    }
  },
  "skills": {
    "autoLoad": true,
    "paths": [
      "~/.openclaw/skills",
      "./skills"
    ]
  }
}

🔗 相关文档

第2章：安装配置 - 基础配置教程
第11章：高级配置 - 模型、记忆、审批与性能
配置文件模板 - 更多配置模板

💡 最佳实践

配置管理建议

定期备份:

bash

cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d)

版本控制:
- 将配置模板加入 Git
- 使用 .gitignore 排除敏感信息
文档记录:
- 记录每个配置项的用途
- 记录修改历史和原因

最后更新: 2026-02-14
适用版本: OpenClaw 2026.3.2+

Search Guide (`docs/search-guide.md`)

🔍 搜索功能使用指南

本教程的搜索功能专注于标题搜索，帮助你快速找到需要的章节

📖 搜索说明

搜索范围

本站搜索功能仅搜索文档标题，不搜索正文内容。这样设计的原因：

✅ 更精准：直接定位到章节标题
✅ 更快速：搜索速度更快
✅ 更清晰：结果更容易理解

支持的内容

搜索覆盖以下内容的标题：

📚 15章正文：第1-15章的所有标题
📖 8个附录：附录A-H的标题
💡 示例文档：examples目录下的文档标题
📄 其他页面：README、学习路径等

🎯 搜索技巧

1. 使用关键词

推荐做法：
✅ 飞书
✅ 配置
✅ Skills
✅ 问题
✅ API

不推荐：
❌ 如何配置飞书Bot（太长）
❌ 我想知道怎么安装（口语化）

2. 中文搜索

支持中文关键词搜索：

text

飞书 → 找到所有包含"飞书"的标题
配置 → 找到所有包含"配置"的标题
问题 → 找到所有包含"问题"的标题

3. 英文搜索

支持英文关键词搜索：

text

API → 找到所有包含"API"的标题
Skills → 找到所有包含"Skills"的标题
Bot → 找到所有包含"Bot"的标题

4. 组合搜索

使用空格分隔多个关键词：

text

飞书 配置 → 找到同时包含"飞书"和"配置"的标题
API 问题 → 找到同时包含"API"和"问题"的标题

5. 模糊匹配

搜索支持前缀匹配：

text

配 → 可以匹配"配置"
问 → 可以匹配"问题"
Ski → 可以匹配"Skills"

💡 搜索示例

示例1：查找飞书相关内容

搜索词：飞书

预期结果：

第9章：多平台集成（飞书/企微/钉钉/QQ一键接入）
飞书Bot配置
飞书配置检查清单
等等...

示例2：查找配置相关内容

搜索词：配置

预期结果：

第2章：5分钟完成部署
第11章：高级配置
附录H：配置文件模板
等等...

示例3：查找问题解决

搜索词：问题

预期结果：

附录E：常见问题速查
故障排查相关章节
等等...

示例4：查找Skills相关

搜索词：Skills

预期结果：

第8章：Skills扩展
附录B：必装Skills清单
Skills开发示例
等等...

🚀 高级功能

实时搜索

输入2个字符后，搜索会自动开始（延迟300ms），无需点击搜索按钮。

结果高亮

搜索结果中，匹配的关键词会用黄色背景高亮显示。

分类标签

搜索结果会显示内容分类：

📚 文档 - docs目录下的文档
📖 附录 - appendix目录下的附录
💡 示例 - examples目录下的示例

URL参数搜索

可以通过URL参数直接搜索：

yaml

https://your-site.com/search?q=飞书

❓ 常见问题

Q1：为什么搜索不到某些内容？

A：搜索只匹配标题，不搜索正文内容。如果标题中没有你搜索的关键词，就不会出现在结果中。

解决方案：

尝试使用标题中可能出现的关键词
查看目录，找到相关章节
使用浏览器的页内搜索（Ctrl+F / Cmd+F）

Q2：搜索结果太多怎么办？

A：使用更具体的关键词，或组合多个关键词。

示例：
❌ 配置 → 结果太多
✅ 飞书配置 → 结果更精准

Q3：搜索结果太少或没有结果？

A：尝试以下方法：

使用更短的关键词

text

❌ 飞书Bot配置 → 可能没结果
✅ 飞书 → 有结果

检查拼写

text

❌ Skils → 拼写错误
✅ Skills → 正确

使用同义词

text

问题 = 故障 = 错误
配置 = 设置

Q4：搜索速度慢？

A：首次加载时需要下载搜索索引（约几KB），之后搜索会很快。如果持续慢，请：

刷新页面
清除浏览器缓存
检查网络连接

📚 相关资源

最后更新：2026年2月14日

Skills Ecosystem (`docs/skills-ecosystem.md`)

OpenClaw Skills 生态说明

📊 Skills 分类统计（2026年2月）

📦 内置 Skills（预装）

数量: 49个
位置: OpenClaw 安装包自带
特点: 开箱即用，无需安装
类型: 文件管理、知识管理、日程管理、自动化等

说明: 这些 Skills 在安装 OpenClaw 时就已经包含，可以直接使用，无需额外安装。

查看命令:

bash

openclaw skills list --builtin
```text
---

### 🏪 ClawHub 官方 Skills

**数量**: 93个（包含49个内置）  
**位置**: ClawHub 官方仓库  
**特点**: 官方维护，质量保证  
**安装**: `clawhub install <skill-name>`

**说明**: ClawHub 是 OpenClaw 官方的 Skills 市场，提供经过官方审核和维护的高质量 Skills。

**访问方式**:
```bash
# 搜索 Skills
clawhub search <关键词>

# 安装 Skills
clawhub install <skill-name>

# 查看已安装
openclaw skills list
```text
---

### 🌐 社区 Skills（扩展）

**数量**: 1715+个  
**位置**: GitHub 社区贡献  
**特点**: 功能丰富，需要筛选  
**安装**: 手动安装或通过 GitHub

**说明**: 社区开发者贡献的 Skills，涵盖各种场景和需求。质量参差不齐，使用前建议查看评价和文档。

**安装方式**:
```bash
# 从 GitHub 克隆
git clone https://github.com/user/skill-name ~/.openclaw/skills/skill-name

# 或使用 clawhub（如果已发布）
clawhub install community/skill-name

🏢 企业级 Skills（百度千帆）

数量: 1715个
位置: 百度千帆平台
特点: 企业级质量，覆盖20+行业
适用: 企业用户、行业应用

说明: 百度千帆提供的企业级 Skills 生态，专为企业场景设计，包含行业解决方案。

行业覆盖:

金融、医疗、教育、零售
制造、物流、客服、营销
等 20+ 行业

📈 总计

类型	数量	质量	推荐度
内置 Skills	49个	⭐⭐⭐⭐⭐	必用
ClawHub 官方	93个	⭐⭐⭐⭐⭐	强烈推荐
社区 Skills	1715+个	⭐⭐⭐	按需选择
企业级 Skills	1715个	⭐⭐⭐⭐⭐	企业推荐
总计	1800+个	-	-

🎯 推荐安装

Top 20 必装 Skills

详见第8章：Skills扩展

新手推荐

从内置 Skills 开始 - 熟悉基本功能
安装 Top 5 核心 Skills - 扩展核心能力
根据需求选择社区 Skills - 满足特定场景

💡 使用建议

选择 Skills 的原则

优先使用内置 Skills - 稳定可靠
官方 Skills 次之 - 质量保证
社区 Skills 谨慎选择 - 查看评价和文档
企业用户考虑企业级 Skills - 专业支持

避免过度安装

❌ 不要一次性安装太多 Skills
✅ 按需安装，逐步扩展
✅ 定期清理不用的 Skills
✅ 关注 Skills 更新

🔗 相关链接

第8章：Skills扩展 - 详细的 Skills 使用指南
ClawHub 市场 - 官方 Skills 市场
Skills 开发文档 - 开发自己的 Skills

最后更新: 2026-02-14
数据来源: OpenClaw 官方统计

01 Basics 01 Introduction (`docs/01-basics/01-introduction.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第1章：认识OpenClaw

在开始使用 OpenClaw之前，先了解它是什么，为什么要用它，以及它能带来什么。

⚠️ 版本说明：截至 2026-09-10，本教程按 OpenClaw v2026.9.3（稳定版，2026-09-08 发布） 校对。升级自 2026.6.x / 2026.8.x 后请先跑 openclaw doctor --fix。

💡 重要前提：OpenClaw 现在的主线能力不只来自 Skills，还包括官方内建的记忆系统、Task Flow、媒体生成工具、Webhooks 和 infer CLI。教程中凡是遇到“第三方 Skill 安装失败”或“命令找不到”，优先按官方主路线排查。

1.1 什么是OpenClaw

一句话介绍

OpenClaw 是一个开源的 AI 智能体 Gateway 网关，让你可以在本地部署 AI 助手，访问本地文件，通过多个平台（飞书、企微、QQ等）随时使用。

项目名称演变：OpenClaw 原名 Clawdbot，因 Anthropic 商标顾虑在 2026年1月27日更名为 Moltbot（过渡名），最终在1月30日确定为 OpenClaw。三个名字本质是同一个项目，功能完全一致。

核心能力

🏠 本地/云端部署：在你的电脑或服务器上运行，数据和配置可控
📁 文件与工作区操作：可以搜索、读取、编辑本地文件并执行自动化任务
🧠 记忆系统升级：支持 Active Memory、Dreaming、Memory Wiki 等长期记忆能力
⚙️ 自动化主线：除了定时任务，还支持 Task Flow 和 Webhooks 驱动的持久化流程
🎬 媒体生成内建化：官方支持图片、视频、音乐生成以及 ComfyUI 工作流接入
💬 多平台使用：支持飞书、企微、钉钉、QQ、Telegram、Discord 等
💰 成本可控：使用自己的 API 或本地能力，自行控制成本与安全边界

2026.4 → 2026.9 你需要知道的主线

下列能力从 2026.4 起进入主线；2026.8.1（OpenClaw 2.0） 与 v2026.9.3 又叠加了会话 SQLite、OpenAI 路由规范化和更新恢复等变化。跑教程前先确认 npm view openclaw version = 2026.9.3。

仍在用的核心能力

Active Memory：在主回复前自动回忆用户偏好、上下文和历史细节
Dreaming：通过 light / deep / REM 三阶段，把高价值短期信息提升为长期记忆
Memory Wiki：把知识库从“普通笔记”升级为带 claim / evidence、矛盾检测和新鲜度排序的结构化知识层
Task Flow + Webhooks：把自动化从“定时触发”扩展为“可恢复、可追踪、可被外部系统驱动”的工作流
openclaw infer：统一模型、图片、音频、TTS、视频、网页搜索和 embedding 的 CLI 入口
Control UI 多语言：当前官方已支持简中、繁中、日语、韩语、法语、德语、西语等多语言界面

升级到 v2026.9.3 还要记住

Node：>=24.16.0 <25 || >=26.1.0（推荐 Node 26）
迁移：openclaw doctor --fix（openai/* 路由、OpenProse 清理、Workshop 归属等）
不要再默认推荐：openai-codex/*、/prose、整串 clawhub install …

工作原理

OpenClaw 通过 Gateway 网关将聊天应用连接到 AI 智能体。Gateway 是会话、路由和渠道连接的唯一事实来源。

核心组件：

Gateway 网关
- 连接各个聊天平台（飞书、企微、QQ、Telegram等）
- 管理会话和消息路由
- 默认地址：http://127.0.0.1:18789/
- 配置文件：~/.openclaw/openclaw.json
AI 智能体
- 支持 Claude、GPT、Gemini、DeepSeek、Kimi 等多种模型
- 可以本地运行或远程调用
Skills 技能系统
- 文件管理、知识管理、自动化等
- 可自定义开发
ClawHub
- 技能市场，可以下载和分享 Skills

💡 Gateway 网关是什么？
Gateway 是 OpenClaw 的核心服务，它像一个"中央调度站"，负责：

接收来自不同平台的消息（飞书、企微、QQ、Telegram等）

将消息转发给 AI 智能体处理

把 AI 的回复发送回对应平台

管理所有的会话和上下文

这就是为什么你可以在任何平台上使用 OpenClaw，因为 Gateway 统一管理了所有的连接。

1.2 为什么选择OpenClaw

与在线AI的本质区别

OpenClaw 与传统在线 AI 服务在部署方式、数据隐私和功能扩展等方面存在本质差异，如表 1-3 所示。

表 1-3 OpenClaw 与在线 AI 对比

特性	OpenClaw	ChatGPT/Claude网页版
部署方式	本地/云端	在线服务
数据隐私	✅ 完全掌控	⚠️ 上传到服务器
本地文件访问	✅ 支持	❌ 不支持
系统操作	✅ 支持	❌ 不支持
功能扩展	✅ Skills系统	❌ 固定功能
成本	按需付费	订阅制
多平台集成	✅ 支持	⚠️ 有限

简单来说：

ChatGPT/Claude：像在网吧上网，方便但受限
OpenClaw：像自己的电脑，自由但需要配置

五大核心优势

1. 本地部署，保护隐私

场景：你需要AI帮你整理公司的财务报表

❌ 在线AI：需要上传文件到服务器，存在泄密风险
✅ OpenClaw：文件不离开你的电脑，完全安全

2. 访问本地文件和系统

场景：你想找一张去年的发票

❌ 在线AI：无法访问你的电脑，只能手动找
✅ OpenClaw：直接搜索电脑上的所有文件，秒找到

真实案例：
我：帮我找一下我电脑上的一张发票，里面详情是买了一个跑步机
OpenClaw：[搜索中...] 找到了！这是您的跑步机发票 [发送文件]

3. 可扩展的Skills生态

场景：你想让AI帮你画图

❌ 在线AI：功能固定，不支持就没办法
✅ OpenClaw：安装 Banana Skills，立即支持画图

可用的Skills：

文件管理：智能搜索、批量处理、自动整理
知识管理：网页剪藏、笔记同步、论文管理
日程管理：日历同步、智能提醒
自动化：定时任务、网站监控、日报推送
工具类：截图、翻译、画图、视频生成

4. 多平台支持

场景：你在外面，想让AI帮你处理文件

❌ 在线AI：需要打开网页，操作不便
✅ OpenClaw：打开飞书/企微/QQ，直接发消息

支持的平台：

🏢 企业微信：团队协作
📱 钉钉：办公自动化
🚀 飞书：项目管理
💬 QQ：个人助手
🌐 Telegram/Discord：国际平台

5. 成本可控

场景：你担心AI使用费用太高

❌ ChatGPT Plus：20美元/月，固定费用
✅ OpenClaw：按需付费，用多少花多少

成本对比（月使用量：中等）：

ChatGPT Plus：20美元（约140元）
Claude Pro：20美元（约140元）
OpenClaw + DeepSeek：5-30元
OpenClaw + Kimi：10-50元

💡 省钱技巧：使用国产大模型可以节省50%-70%成本

1.3 OpenClaw vs 主流AI工具

OpenClaw 与主流 AI 工具在功能定位和成本结构上存在显著差异。下面从核心功能、成本和适用人群三个维度进行详细对比。

核心功能对比

OpenClaw 在本地文件访问、系统操作和自动化任务方面具有明显优势，如表 1-1 所示。

表 1-1 主流 AI 工具功能对比

功能特性	OpenClaw	ChatGPT Plus	Cursor	Claude Pro
本地文件访问	✅ 完整支持	❌ 不支持	✅ 支持	❌ 不支持
系统操作	✅ 日历/备忘录/截图	❌ 不支持	⚠️ 有限	❌ 不支持
多平台集成	✅ 飞书/企微/钉钉/QQ	⚠️ 有限	❌ 不支持	⚠️ 有限
Skills扩展	✅ 1715+	❌ 不支持	⚠️ 插件	❌ 不支持
多模型切换	✅ 随意切换	❌ 固定GPT	✅ 支持	❌ 固定Claude
代码能力	✅ 强	⚠️ 中等	✅ 强	✅ 强
自动化任务	✅ 完整支持	❌ 不支持	❌ 不支持	❌ 不支持

成本对比

OpenClaw 采用按量付费模式，相比固定月费的在线服务可节省 73%-96% 的成本，如表 1-2 所示。

表 1-2 年度成本对比

项目	OpenClaw	ChatGPT Plus	Cursor	Claude Pro
月费	5-50元	140元	140元	140元
年费	60-600元	1680元	1680元	1680元
节省	-	节省73%-96%	节省73%-96%	节省73%-96%
计费方式	按量付费	固定月费	固定月费	固定月费

成本说明：

OpenClaw 成本 = 服务器费用（可选）+ API 费用
本地部署：0元服务器 + 5-30元 API = 5-30元/月
云端部署：20元服务器 + 5-30元 API = 25-50元/月

适合人群

✅ 强烈推荐OpenClaw的人群：

超级个体/自由职业者 - 需要一个人顶一个团队
知识工作者 - 需要管理大量文档和知识
程序员 - 需要代码辅助和自动化
内容创作者 - 需要素材管理和多平台发布
注重隐私 - 不想上传敏感文件到云端
成本敏感 - 想要高性价比的AI助手

⚠️ 如果你只需要简单对话，可以考虑：

ChatGPT Plus：最简单，开箱即用
Claude Pro：长文本处理能力强

💡 最佳方案：

日常对话：ChatGPT/Claude
工作助手：OpenClaw（本地文件、自动化、多平台）
代码编写：Cursor + OpenClaw

真实案例：为什么我选择OpenClaw

我是一个内容创作者，每天需要：

整理大量的资料和文章

管理日程和任务

生成图片和视频

多平台发布内容

以前我需要：

ChatGPT：写文案

Notion：管理笔记

Midjourney：画图

各种工具：自动化

现在只需要OpenClaw：

一个助手搞定所有事情

成本降低70%

效率提升10倍

1.4 适用场景

✅ 适合使用 OpenClaw的场景

1. 个人效率提升

知识工作者：

整理大量文档和资料
管理日程和任务
自动化重复工作

程序员：

代码搜索和管理
技术文档整理
开发环境管理

内容创作者：

资料收集和整理
内容创作辅助
多平台发布

学生：

课程资料管理
论文阅读和笔记
学习计划管理

2. 知识管理

网页文章存档
GitHub项目管理
论文笔记整理
跨设备同步

3. 编程开发

代码搜索和理解
技术文档查询
开发环境配置
项目管理

4. 团队协作

项目管理自动化
文档协作优化
会议记录整理
团队知识库建设

5. 创意工作

AI绘画工作流
视频脚本生成
多语言翻译
数据分析自动化

❌ 不适合使用 OpenClaw的场景

1. 纯在线对话

如果你只是想偶尔和AI对话，不需要访问本地文件：

ChatGPT网页版更方便
无需安装配置
打开就能用

2. 专业代码编辑

如果你只需要代码补全和编辑：

Cursor更专业
GitHub Copilot更方便
集成度更高

3. 移动端为主

如果你主要在手机上使用：

ChatGPT App更方便
Claude App更流畅
无需配置

4. 不想折腾

如果你：

不想学习新工具
不想配置环境
只想开箱即用

那么在线AI服务更适合你。

💡 最佳实践

推荐组合：

OpenClaw：日常工作助手
Cursor：代码编辑
ChatGPT：移动端对话

使用建议：

在电脑上：优先使用 OpenClaw
写代码时：使用Cursor
在外面时：使用ChatGPT App

1.5 OpenClaw vs 其他AI工具能力对比

不同 AI 工具在任务规划、自动执行、代码质量等维度上各有侧重。OpenClaw 在任务规划和自动化方面表现突出，如表 1-4 所示。

表 1-4 AI 工具能力维度对比

能力维度	OpenClaw	Claude Code	Cursor	ChatGPT
任务规划	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐
自动执行	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐
自我修复	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐	⭐
工程级操作	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐
本地自动化	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐	⭐
代码质量	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
易用性	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐

核心差异：

OpenClaw：强在任务规划和自动执行完整工程流程
Claude Code/Cursor：强在代码质量与理解
ChatGPT：强在对话体验和易用性

本章小结

通过本章，你应该了解了：

✅ OpenClaw是什么：本地AI助手，通过Gateway连接多个平台
✅ 核心优势：本地部署、文件访问、可扩展、多平台、成本低
✅ 与其他AI的区别：更适合作为个人工作助手
✅ 适用场景：效率提升、知识管理、编程开发、团队协作
✅ 不适合场景：纯对话、移动端为主、不想折腾

思考题

你目前使用什么AI工具？遇到了什么问题？
OpenClaw的哪个功能最吸引你？
你打算用OpenClaw做什么？

下一章：第2章：环境搭建 - 5分钟完成安装

返回目录：README

🌐 在线阅读

📖 想在线阅读此章节？

🔗 在线阅读：第1章 - OpenClaw是什么？

访问网站获取更好的阅读体验：

📱 响应式设计，支持手机、平板、电脑
🌙 支持黑暗模式，保护眼睛
🔍 内置搜索功能，快速定位内容
📋 目录导航，轻松跳转章节

🏠 访问完整教程网站

01 Basics 02 Installation (`docs/01-basics/02-installation.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第2章节：环境搭建

本章节将手把手教你安装 OpenClaw。

⚠️ 当前基线：截至 2026-09-10，本教程推荐使用 OpenClaw v2026.9.3（稳定版，2026-09-08 发布）。运行时要求 Node 24.16+ 或 Node 26.1+（推荐 Node 26）；Node 22 / 旧 24.x 已不再支持。

📋 前提条件与推荐配置

为什么推荐Mac？

OpenClaw在Mac上体验最好，因为：

✅ 原生支持最完善，系统集成度高
✅ 可以操作Mac日历、备忘附录、提醒事项
✅ 截图功能完美支持
✅ 与iPhone、iPad无缝同步
✅ 文件管理更智能
✅ 开发布环境配置简单

为什么推荐飞书（国内）？

✅ 现代化设计，用户体验好
✅ 开发布者友好，API完善
✅ 支持富文本、文档、表格
✅ 消息推送稳定
✅ 免费版功能丰富

为什么推荐Telegram（国外）？

✅ 全球用户基础大
✅ API最完善，功能最强
✅ 支持Bot功能丰富
✅ 消息推送实时
✅ 隐私保护好

快速导航

推荐路径：

🍎 有Mac → Mac本地部署 + 飞书配置
☁️ 无Mac/想24小时运行 → 云端一键部署 + 飞书配置

所有部署方式：

🍎 Mac本地部署（推荐）
🪟 Windows本地部署
🐧 Linux本地部署
🚀 云端一键部署
🇨🇳 国内一键安装
☁️ Cloudflare Workers 部署（进阶）
🐳 Docker 部署（可选）

配置指南：

🔑 API配置指南
🔄 版本升级指南
❓ 常见访问题解决

Mac本地部署（推荐）

🍎 最佳体验：如果你有Mac电脑，强烈推荐本地部署，体验最好、功能最全！

为什么选择Mac本地部署？

优势：

✅ 系统集成：可操作日历、备忘附录、文件系统
✅ 隐私安全：数据完全本地，不上传云端
✅ 响应速度快：本地运行，无网络延迟
✅ 功能最全：支持所有高级功能
✅ 成本低：无需购买云服务器
✅ 开发布友好：方便调试和自定义

适合人群：

有Mac电脑的用户
注重隐私的用户
需要系统集成功能的用户
开发布者和技术爱好者

系统要求

硬件要求：

CPU：M系列芯片或Intel i5以上
内存：8GB以上（推荐16GB）
硬盘：10GB以上空闲空间

系统版本：

macOS 12 Monterey 或更高版本
推荐 macOS 14 Sonoma 或 macOS 15 Sequoia

前置软件：

Node.js 24（推荐）/ 22.16+（兼容路径，会自动安装）
Homebrew（可选，用于安装依赖）

安装步骤

第一步：打开终端

按 Command + 空格 打开 Spotlight
输入 Terminal 或终端
按回车打开终端

第二步：安装 OpenClaw

在终端中执行以下命令：

bash

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

安装过程会自动：

检测系统环境
安装Node.js（如果未安装）
下载OpenClaw
配置环境变量

预计时间：2-5分钟

第三步：验证安装

安装完成后，执行以下命令验证：

bash

openclaw --version

如果显示版本号（如 2026.9.3），说明安装成功！

第四步：初始化配置

运行配置向导：

bash

openclaw onboard

配置流程：

1. 接受风险提示：

选择 Yes 继续

2. 选择启动模式：

推荐选择 QuickStart 快速启动：

3. 选择AI模型：

选择你的AI供应商（支持国内外主流模型）：

国内推荐：

Kimi（Moonshot AI）：长文本专家，200万字上下文
DeepSeek：性价比之王，推理能力强
智谱GLM：中文理解好，多模态支持

4. 输入API Key：

根据选择的模型，输入对应的API Key（参见API配置指南）

5. 选择聊天工具：

如果要接入飞书/Telegram，选择对应选项
如果暂时不接入，选择 None（后续可配置）

6. Gateway端口设置：

默认 18789 即可：

7. 选择Skills：

使用空格键选择你需要的技能，也可以直接跳过：

8. API Key配置：

没有的可以选择 no 跳过：

9. 启用Hooks：

推荐启用这三个钩子（用于内内容引导、日志和会话记附录）：

10. 完成配置：

配置完成后，会自动启动Gateway服务并打开Web UI（http://127.0.0.1:18789/chat）

第五步：验证安装

bash

# 检查Gateway状态
openclaw channels status

# 应该显示：
# Gateway reachable.

日常使用

启动OpenClaw：

bash

# 启动Gateway服务
openclaw gateway start

# 或使用systemd（推荐，开机自启）
openclaw gateway enable

访问Web UI：

打开浏览器访问：http://127.0.0.1:18789/chat

停止服务：

bash

openclaw gateway stop

接入飞书（推荐）

Mac本地部署后，强烈推荐接入飞书，获得最佳体验：

参考第9章节：飞书Bot配置
配置完成后，可以在飞书中随时与OpenClaw对话
支持文本、图片、文件等多种消息类型

常见访问题

Q1：安装时提示权限不足？

bash

# 使用sudo安装
curl -fsSL https://openclaw.ai/install.sh | sudo bash

Q2：如何更新OpenClaw？

bash

openclaw update

Q3：如何卸载？

bash

openclaw uninstall

Windows本地部署

🪟 Windows用户：完全可用，但部分系统集成功能受限。

系统要求

硬件要求：

CPU：2核以上
内存：4GB以上（推荐8GB）
硬盘：10GB以上空闲空间

操作系统：

Windows 10 或 Windows 11

前置软件：

Node.js 24（推荐）/ 22.16+（兼容路径）

部署方式选择

Windows有两种部署方式：

WSL2 + Ubuntu（强烈推荐）：官方推荐方式，提供完整Linux环境支持
PowerShell原生部署：纯Windows环境，适合不想使用WSL2的用户

方式一：WSL2 + Ubuntu部署（强烈推荐）

这是官方推荐的Windows部署方式，提供最完整的Linux环境支持。

第一步：启用WSL2

以管理员身份打开PowerShell，执行：

powershell

# 启用WSL功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 设置WSL 2为默认版本
wsl --set-default-version 2

重启计算机。

第二步：安装Ubuntu

方法一：Microsoft Store安装（推荐）

打开Microsoft Store
搜索「Ubuntu 22.04 LTS」或「Ubuntu 24.04 LTS」
点击「获取」并安装
首次启动设置用户名和密码

安装完成后会自动打开Ubuntu终端，按提示设置用户名和密码。

第三步：更新Ubuntu系统

在Ubuntu终端中执行：

bash

# 更新软件包列表
sudo apt update && sudo apt upgrade -y

# 安装基础工具
sudo apt install -y curl git wget build-essential

第四步：安装Node.js 24（推荐）

bash

# 添加NodeSource仓库
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -

# 安装Node.js
sudo apt install -y nodejs

# 验证版本（推荐 v24.x）
node -v
npm -v

第五步：安装 OpenClaw

方法A：一键脚本安装

bash

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

第六步：验证安装

bash

# 查看版本
openclaw --version

# 查看帮助
openclaw --help

# 查看系统状态
openclaw status

第七步：配置Windows访问WSL2服务

由于OpenClaw运行在WSL2中，需要配置端口转发布以便Windows访问。

创建启动脚本 start-openclaw.bat：

batch

@echo off
echo Starting OpenClaw Gateway in WSL2...
wsl -d Ubuntu-22.04 -u root service openclaw start
timeout /t 3
start http://localhost:18789

或直接在WSL2中启动：

bash

# 在WSL2 Ubuntu终端中
openclaw gateway run --port 18789

然后在Windows浏览器访问 http://localhost:18789

方式二：PowerShell原生部署

适合不想使用WSL2的纯Windows用户。

第一步：安装Node.js 24（推荐）

方法一：官网下载安装

访问 https://nodejs.org/zh-cn
下载Windows安装包（推荐 24.x 版本）
运行安装程序，勾选「自动安装必要的工具」

第二步：验证Node.js安装

powershell

# 打开PowerShell
node -v
npm -v

第三步：以管理员身份安装 OpenClaw

重要：必须以管理员身份运行PowerShell。

powershell

# 安装最新稳定版
npm install openclaw@latest --allow-scripts=openclaw

# 或安装汉化版
npm install @qingchencloud/openclaw-zh@latest

第四步：解决安装权限访问题

如果遇到权限错误：

powershell

# 方法A：启用PowerShell脚本执行
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 方法B：修改npm安装目附录
npm config set prefix "C:\npm"
npm config set cache "C:\npm-cache"

# 将目附录添加到PATH
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\npm", "User")

第五步：验证安装

powershell

openclaw --version
openclaw --help

第六步：解决常见访问题

访问题：sharp模块加载失败

powershell

# 清理npm缓存
npm cache clean --force

# 重新安装
npm install openclaw@latest --allow-scripts=openclaw --force

访问题：Windows Defender阻止

将OpenClaw安装目附录添加到Windows Defender排除项：

text

C:\Users\你的用户名\AppData\Roaming\npm
C:\Users\你的用户名\.openclaw

初始化配置

安装完成后，需要运行初始化向导。

启动初始化向导

bash

openclaw onboard --install-daemon

配置AI模型提供商

OpenClaw需要对接AI模型才能工作。

以配置Anthropic Claude（推荐）为例：

📖 详细说明: 完整的 API Key 配置方式和优先级说明请参考 API Key 配置完整指南

bash

# WSL2或PowerShell
openclaw models auth add
# 按提示选择 anthropic
# 输入 API Key: sk-ant-xxx

绑定消息渠道

1. Telegram

创建Bot：

在Telegram搜索 @BotFather
发布送 /newbot 创建机器人
保存Bot Token

配置：

bash

openclaw channels add telegram
openclaw config set channels.telegram.botToken "your-bot-token"
openclaw gateway restart

2. WhatsApp

bash

# 登录WhatsApp（显示二维码）
openclaw channels login whatsapp

# 用手机WhatsApp扫码

3. 企业微信（国内推荐）

bash

# 安装企业微信插件
openclaw plugins install @m1heng-clawd/wework

# 配置
openclaw config set channels.wework '{"enabled":true,"corpId":"xxx","agentSecret":"xxx"}' --json

4. 飞书（国内推荐）

bash

# 安装飞书插件
openclaw plugins install @m1heng-clawd/feishu

# 配置
openclaw config set channels.feishu '{"enabled":true,"appId":"cli_xxx","appSecret":"xxx"}' --json

Windows常用命令速查

系统管理：

命令	功能
`openclaw --version`	查看版本
`openclaw status`	查看系统状态
`openclaw health`	健康检查
`openclaw update`	更新OpenClaw
`openclaw doctor`	诊断系统访问题

配置管理：

命令	功能
`openclaw onboard`	初始化向导
`openclaw configure`	交互式配置
`openclaw config get <key>`	查看配置项
`openclaw config set <key> <value>`	修改配置项
`openclaw config unset <key>`	删除配置项

Linux本地部署

🐧 Linux用户：适合开发布者，配置灵活。

系统要求

推荐发布行版：

Ubuntu 20.04+
Debian 11+
CentOS 8+

安装步骤

第一步：安装Node.js

bash

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version

第二步：安装 OpenClaw

bash

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

第三步：验证安装

bash

openclaw --version

第四步：初始化配置

bash

openclaw onboard

2.1 系统要求与准备

云端部署要求

如果选择云端部署，无需任何本地环境，只需要：

✅ 一个浏览器
✅ 20元/月预算
✅ 10分钟时间

云端一键部署

🔥 适合场景：无Mac电脑、需要24小时运行、多设备访问。

为什么选择云端部署？

云端部署相比本地部署具有多项优势，如表 2-1 所示。

表 2-1 云端部署优势

优势	说明
⚡ 秒级部署	点几下鼠标就完成，无需配置环境
💰 成本低	20元/月起，比买Mac Mini便宜太多
📱 手机可用	通过QQ、企微、飞书随时随地访问
🔒 稳定可靠	24小时运行，不用担心电脑关机
🎥 视频教程	官方视频手把手教学

方案对比

目前主流的云端部署方案对比如表 2-2 所示。

表 2-2 云端部署方案对比

方案	价格	带宽	推荐场景
腾讯云Lighthouse	20元/月，99元/年	20M	QQ、企微用户
火山引擎	9.9元/月，58元/年	5M	飞书用户

腾讯云Lighthouse部署（推荐）

第一步：购买服务器

访问活动页面：

text

https://cloud.tencent.com/act/pro/lighthouse-moltbot

选择配置：
- 配置：2核2G
- 带宽：20M
- 地域：建议选择硅谷（国外地域访问AI模型更稳定）
- 价格：20元/月或 99元/年
实名认证：
- 首次使用需要实名认证
- 选择个人认证即可
- 按提示完成认证
完成购买：
- 点击"立即购买"
- 支付20元（建议先买1个月试用）
- 等待服务器创建完成
- 可选：关闭自动续费
获取服务器信息：
- 购买完成后，点击头像 → "站内信"
- 查看并记附录：
  - 公网IP地址
  - 默认用户名（通常是 lighthouse）
  - 初始密码

💡 免费白嫖方案（可选）

如果你想免费试用3个月，可以通过 CodeBuddy 活动获取免费服务器。

步骤：

注册 CodeBuddy：
- 国际版：https://www.codebuddy.ai/promotion/?ref=lweelxalgm（谷歌/GitHub账户）
- 国内版：https://www.codebuddy.cn/promotion/?ref=7zucxaz7zvqi（手机号）
- 建议使用新账号注册
领取奖励：
- 登录后点击"实战礼" → "立刻领奖"
- 获得1个月免费使用权
- 累计活跃7日可再延长2个月（每天在CodeBuddy中访问候即可）
重装系统为OpenClaw：
- 登录腾讯云控制台：https://console.cloud.tencent.com/
- 进入"轻量应用服务器"
- 点击"重装系统"
- 选择"使用应用模板" → "OpenClaw"
- 选择"无需备份"，点击"确定"
后续操作：
- 重装完成后，按照下面的步骤继续配置

第二步：连接服务器

使用SSH客户端连接：

方式一：使用SSH客户端（推荐）
- 下载SSH客户端（如 Xterminal、Termius、FinalShell）
- 新建SSH连接：
  - 名称：随便取
  - 地址：公网IP地址
  - 端口：22
  - 用户名：lighthouse（或站内信中的用户名）
  - 密码：购买时设置的密码
方式二：使用网页终端
- 在腾讯云控制台，点击实例卡片
- 点击"登录"按钮
- 直接在浏览器中打开终端
验证OpenClaw安装：
bash
```
openclaw --version
```
如果显示版本号（如 2026.9.3），说明OpenClaw已预装成功。

第三步：配置大模型

进入应用管理：
- 点击服务器卡片
- 切换到"应用管理"标签
选择模型：
- 推荐使用 Kimi k2.5（性价比最高）
- 也可以选择其他国产大模型

获取API Key：

Kimi k2.5配置（推荐）：

text

1. 访问：https://platform.moonshot.cn/
2. 注册账号并登录
3. 进入"API管理"
4. 点击"创建API Key"
5. 复制API Key（格式：sk-xxx）

填入配置：
- 将API Key粘贴到配置框
- 点击"保存"
- 等待配置生效

第四步：测试连接

访问WebUI：
- 使用控制台提供的访问地址
- 格式：http://你的服务器IP:18789/?token=xxx
发布送测试消息：
text
```
你好，能听到我说话吗？
```
验证成功：
- 如果收到AI回复，说明配置成功
- 右上角会显示使用的模型名称

腾讯龙虾产品矩阵（2026年新增）

💡 2026年3月，腾讯推出了「龙虾全家桶」系列产品，围绕 OpenClaw 构建了完整的产品矩阵。以下是各产品的关系和定位：

产品	类型	平台	状态	定位
Lighthouse	云服务器	全平台	✅ 稳定	轻量云服务器，适合部署 OpenClaw 后端
QClaw	桌面客户端	macOS	✅ 全量公测	腾讯官方 OpenClaw 桌面客户端，开箱即用
WorkBuddy	桌面Agent	Windows/macOS	✅ 公测	桌面端AI助手，支持多IM（微信、QQ、飞书等）
ClawBot	微信插件	全平台	✅ 公测	官方微信接入方案，基于 WeChatFerry

各产品关系：

text

┌─────────────────────────────────────────┐
│           腾讯龙虾产品矩阵               │
├──────────┬──────────┬───────────────────┤
│  Lighthouse │  QClaw  │    WorkBuddy      │
│ (云服务器)  │ (桌面端) │   (多IM Agent)    │
│   ↓部署    │  ↓内置   │      ↓集成         │
│  OpenClaw后端 ───────→ OpenClaw核心     │
│              ↑                          │
│         ClawBot (微信插件)              │
└──────────┴──────────┴───────────────────┘

使用建议：

个人用户 / macOS：优先试用 QClaw，一键安装无需折腾服务器
需要多IM接入：选择 WorkBuddy，支持微信、QQ、飞书等同时在线
微信深度用户：搭配 ClawBot 插件实现微信消息收发
需要服务器部署：选择 Lighthouse，20元/月性价比极高

⚠️ QClaw 于 2026-03-20 从内测转为全量公测，目前仅支持 macOS。Windows 版本正在开发中。

火山引擎部署（更便宜）

如果你是飞书重度用户，推荐使用火山引擎：

访问活动页面：

text

https://www.volcengine.com/activity/clawdbot

价格优势：
- 9.9元/月
- 58元/年
- 比腾讯云便宜10元
配置对比：
- 2核2G（相同）
- 5M带宽（腾讯云20M）
- 适合飞书用户
部署流程：
- 与腾讯云类似
- 按照页面提示操作即可

百度智能云部署（0.01元试用）

💰 超值试用：百度智能云提供0.01元/月的特惠活动，适合想要低成本试用的用户。

活动信息

访问活动页面：

text

https://cloud.baidu.com/product/BCC/moltbot.html

活动规则：
- 首月仅需 0.01元
- 需要注册并绑定个人身份证
- 每个账号限购一次

部署步骤

第一步：购买服务器

注册百度智能云账号
完成个人实名认证（绑定身份证）
抢购特惠LS实例（0.01元/月）
如果售罄，可以原价购买轻量应用服务器

第二步：创建实例

进入轻量应用服务器LS控制台
点击"创建实例"：
- 名称：随机生成或自定义
- 密码：务必记住，后续登录需要
等待实例创建完成

第三步：一键配置 OpenClaw

进入实例详情页：
- 点击实例卡片
- 进入"应用管理"标签
应用配置：
- 点击"一键开通"
- 点击"一键放行"（开放防火墙端口）
- 等待显示"已放行"
模型配置：
- 下拉选择模型（如：文心一言、千帆大模型）
- 点击"应用模型配置"
- 系统会自动创建千帆API Key并配置
接入方式配置（可选）：
- 支持接入：飞书、钉钉、企业微信、QQ
- 选择你常用的通讯工具
- 按照提示完成配置（详见后续章节节）
Skills 配置（可选）：
- 默认提供：百度搜索、百度百科
- 可以按需选择并点击"应用"
- 更多Skills可访问OpenClaw官网获取

第四步：访问WebUI

点击"获取网站地址"
复制访问链接
在浏览器中打开，即可与OpenClaw对话

优势与限制

优势：

✅ 价格极低（首月0.01元）
✅ 一键配置，无需手动安装
✅ 集成百度千帆大模型
✅ 自动配置APIKey

限制：

⚠️ 仅限首月优惠
⚠️ 需要实名认证
⚠️ 活动可能售罄

阿里云部署（可选）

阿里云也提供了OpenClaw一键部署方案：

访问活动页面：

text

https://www.aliyun.com/activity/ecs/clawdbot

选择轻量应用服务器：
- 使用 OpenClaw镜像
- 一键安装配置
价格参考：
- 与腾讯云类似
- 具体以活动页面为准

官方视频教程（强烈推荐）

腾讯云提供了详细的视频教程，跟着视频操作更简单：

云上OpenClaw一键部署并接入企微和QQ
- 视频地址：https://cloud.tencent.com/developer/video/85003
- 时长：约10分钟
- 内内容：从购买到配置完成
云上OpenClaw一键部署并接入飞书和钉钉
- 视频地址：https://cloud.tencent.com/developer/video/85055
- 时长：约10分钟
- 内内容：飞书和钉钉接入全流程

存量服务器部署

如果你已经有轻量服务器，可以使用AI助手对话式部署：

官方教程：https://cloud.tencent.com/developer/article/2625605
适用场景：已有轻量服务器
部署方式：通过AI对话完成配置
优势：更灵活，可自定义

云端部署常见访问题

Q1: 云端部署安全吗？

✅ 数据存储在你的服务器上
✅ 只有你能访问
✅ 可以设置访问密码

Q2: 可以随时停止吗？

✅ 可以随时删除服务器
✅ 按使用时长计费
✅ 不用了就删除，不浪费钱

Q3: 手机怎么访问？

通过QQ、企微、飞书等平台
详见第9章节：多平台集成

国内一键安装（推荐）

🇨🇳 国内用户推荐：使用官方中文版一键安装脚本，速度快、配置简单。

为什么选择国内版？

国内版相比国际版具有多项本地化优势，如表 2-3 所示。

表 2-3 国内版优势

优势	说明
⚡ 速度快	使用国内镜像源，下载速度快
🇨🇳 中文友好	完整中文界面和提示
📦 一键安装	自动配置所有依赖
🎯 开箱即用	预配置国内常用服务
💰 成本优化	默认配置国产模型

前置要求

必需环境：

Node.js 24（推荐）/ 22.16+（兼容路径）（必需）
pnpm（可选，推荐用于源码构建）

推荐配置：

Brave Search API 密钥（用于网络搜索）
可通过 openclaw-cn configure --section web 配置

系统要求：

macOS：需要 Xcode / Command Line Tools（仅 CLI + Gateway 需要 Node.js）
Windows：强烈推荐使用 WSL2（Ubuntu），原生 Windows 未经测试
Linux：Ubuntu 20.04+、Debian、CentOS

快速开始

macOS/Linux 安装

bash

# 使用国内官方安装脚本
curl -fsSL https://clawd.org.cn/install.sh | bash

Windows 安装

使用 PowerShell（管理员权限）：

powershell

# 使用国内官方安装脚本
iwr -useb https://clawd.org.cn/install.ps1 | iex

⚠️ Windows 用户注意：强烈推荐使用 WSL2（Ubuntu），原生 Windows 支持有限。

WSL2 安装步骤：

powershell

# 1. 安装 WSL2
wsl --install

# 2. 重启电脑

# 3. 在 WSL2 中运行 Linux 安装命令
curl -fsSL https://clawd.org.cn/install.sh | bash

全局安装（替代方案）

如果一键脚本失败，可以使用 npm 全局安装：

bash

# 使用 npm
npm install openclaw-cn@latest

# 或使用 pnpm（推荐）
pnpm add openclaw-cn@latest

运行入门向导

安装完成后，运行配置向导：

bash

# 运行入门向导并安装后台服务
openclaw-cn onboard --install-daemon

配置向导流程

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

1. 选择网关模式：

本地网关（推荐）：Gateway 运行在本机
远程网关：Gateway 运行在服务器

2. 配置认证：

OpenAI Code（Codex）订阅（OAuth）
API 密钥（推荐用于 Anthropic）
也支持 claude setup-token

3. 选择 AI 提供商：

推荐：Kimi、DeepSeek、GLM-4（国产模型）
可选：Claude、GPT（需要 API key）

4. 配置聊天平台（可选）：

WhatsApp：QR 扫码登录
Telegram：输入 Bot Token
Discord：输入 Bot Token
Mattermost：插件令牌
飞书/企微/钉钉：输入应用凭证

5. 安装后台服务（推荐）：

macOS：使用 launchd
Linux：使用 systemd
WSL2：使用 systemd
运行时：Node（推荐，WhatsApp/Telegram 必需）

6. 网关令牌：

向导默认生成一个令牌
存储在 gateway.auth.token 中
即使在回环地址上也会生成

认证配置说明

认证存储位置（重要）：

推荐的 Anthropic 路径：设置 API 密钥（向导可存储）
OAuth 凭据（旧版导入）：~/.openclaw/credentials/oauth.json
认证配置文件：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

无头/服务器提示：

先在普通机器上完成 OAuth
然后将 oauth.json 复制到网关主机

启动 Gateway

如果安装了后台服务，Gateway 应该已经在运行：

bash

# 检查 Gateway 状态
openclaw-cn gateway status

手动运行（前台）：

bash

# 在前台运行，查看实时日志
openclaw-cn gateway --port 18789 --verbose

Dashboard 访问：

本地回环地址：http://127.0.0.1:18789/

如果配置了令牌，需要将其粘贴到控制界面设置中（存储为 connect.params.auth.token）。

⚠️ Bun 警告（WhatsApp + Telegram）：Bun 在这些渠道上有已知访问题。如果使用 WhatsApp 或 Telegram，请使用 Node 运行网关。

快速验证（2分钟）

bash

# 检查状态
openclaw-cn status

# 健康检查
openclaw-cn health

配对 + 连接聊天界面

WhatsApp（二维码登录）

bash

# 登录 WhatsApp
openclaw-cn channels login

通过 WhatsApp → 设置 → 已连接的设备扫描二维码。

Telegram / Discord / 其他

向导可以为你写入令牌/配置。如果手动配置：

Telegram：

bash

openclaw-cn channels add \
  --channel telegram \
  --token "YOUR_BOT_TOKEN"

Discord：

bash

openclaw-cn channels add \
  --channel discord \
  --token "YOUR_BOT_TOKEN"

💡 Telegram 私信提示：首次私信会返回配对码，需要批准后机器人才会响应。

私信安全（配对审批）

默认策略：未知私信会收到短代码，消息在获得批准前不会被处理。

如果首次私信没有得到回复，需要批准配对：

bash

# 查看配对列表
openclaw-cn pairing list whatsapp

# 批准配对
openclaw-cn pairing approve whatsapp <code>

从源码运行（开发布）

如果需要修改 OpenClaw 本身，可以从源码运行：

bash

# 克隆仓库
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

# 安装依赖
pnpm install

# 构建 UI（首次运行时自动安装 UI 依赖）
pnpm ui:build

# 构建项目
pnpm build

# 运行入门向导
openclaw-cn onboard --install-daemon

如果还没有全局安装，可以从仓库中通过 pnpm openclaw-cn ... 运行命令。

从源码运行 Gateway：

bash

node dist/entry.js gateway --port 18789 --verbose

端到端验证

在新终端中，发布送测试消息：

bash

# 发布送测试消息
openclaw-cn message send --target +15555550123 --message "Hello from OpenClaw"

如果 openclaw-cn health 显示 "no auth configured"，需要返回向导设置 OAuth/密钥认证。

调试提示：

openclaw-cn status --all：最佳的只读调试报告
openclaw-cn health：向运行中的网关请求健康快照
openclaw-cn status --deep：深度状态检查

配置文件位置

📖 详细说明: 完整的配置文件结构和使用指南请参考配置文件结构完整指南

bash

# 主配置文件
~/.openclaw/openclaw.json

# 认证配置
~/.openclaw/agents/<agentId>/agent/auth-profiles.json

# OAuth 凭据（旧版）
~/.openclaw/credentials/oauth.json

# 日志文件件
~/.openclaw/logs/gateway.log

国内版特色功能

1. 预配置国产模型：

Kimi（月之暗面）
DeepSeek（深度求索）
GLM-4（智谱 AI）
通义千访问（阿里）
文心一言（百度）

2. 国内平台集成：

飞书（字节跳动）
企业微信（腾讯）
钉钉（阿里）
QQ（腾讯）

3. 优化的网络配置：

使用国内镜像源
优化 API 访问速度
支持代理配置

常见访问题

Q1: 安装失败怎么怎么办？

bash

# 检查 Node.js 版本（需要 22+）
node --version

# 如果版本过低，使用 nvm 升级
nvm install 22
nvm use 22

Q2: 如何更新到最新版本？

bash

# 重新运行安装脚本
curl -fsSL https://clawd.org.cn/install.sh | bash

Q3: 如何卸载？

bash

# 停止服务
openclaw-cn gateway stop

# 卸载
npm uninstall -g openclaw-cn

# 删除配置（可选）
rm -rf ~/.openclaw

Q4: 支持哪些系统？

✅ macOS 12+
✅ Linux（Ubuntu 20.04+、Debian、CentOS）
✅ Windows 10/11（通过 WSL2）

Q5: 配置向导卡住怎么怎么办？

bash

# 按 Ctrl+C 中断

# 检查网关是否运行
openclaw-cn gateway status

# 重新启动网关并重试
openclaw-cn gateway restart
openclaw-cn onboard

Q6: 健康检查显示 "no auth configured"

需要配置认证：

bash

# 重新运行向导
openclaw-cn onboard

# 或手动配置 API 密钥
openclaw-cn configure --section auth

下一步（可选，但很棒）

macOS 菜单栏应用 + 语音唤醒：macOS 应用
iOS/Android 节点（Canvas/摄像头/语音）：节点
远程访问（SSH 隧道 / Tailscale 服务）：远程访问
始终在线 / VPN 设置：Tailscale

下一步

安装完成后，可以：

配置 AI 模型（见下文"API配置指南"）
连接聊天平台（见第9章节：多平台集成）
安装 Skills（见第8章节：Skills扩展）
开始使用（见第3章节：快速上手)

Cloudflare Workers 部署（进阶）

☁️ 全球 CDN 加速：使用 Cloudflare Workers 部署 OpenClaw，分享受全球边缘网络加速。

为什么选择 Cloudflare Workers？

Cloudflare Workers 提供全球边缘网络部署能力，如表 2-4 所示。

表 2-4 Cloudflare Workers 优势

优势	说明
🌍 全球加速	部署在 Cloudflare 全球边缘网络
💰 成本可控	5美元/月起步，24小时在线
🔒 安全可靠	内置 Zero Trust 安全认证
⚡ 快速部署	一键部署，10分钟完成
📦 无需服务器	Serverless 架构，无需维护

前置要求

必需条件：

Cloudflare 账号
Workers Paid 计划（5美元/月）
信用卡（用于订阅付费计划）

成本说明：

基础费用：5美元/月（起步价）
高频使用可能产生额外费用
作为 24 小时在线的 AI 服务，月成本在可接受范围内

💡 成本参考：详见 GitHub 讨论：What's the cost running it 24/7 for a month

部署流程

第一步：一键部署 Moltworker

点击部署按钮：

text

https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/moltworker

配置 Gateway Token：
- 务必修改并妥善保存 MOLTBOT_GATEWAY_TOKEN
- 这是后续进入管理后台的唯一凭证
- 建议使用强密码生成器

第二步：等待构建

部署过程约需 10 分钟
可点击「继续处理项目」跳过等待页面
构建完成后会自动跳转到项目页面

第三步：配置 Access（Zero Trust）

访问网页界面需要配置 CF_ACCESS_AUD 和 CF_ACCESS_TEAM_DOMAIN 两个变量。

1. 创建应用：

进入 Zero Trust → Access → Applications
添加一个 Self-hosted 应用

2. 设置域名：

子域默认为 moltbot-sandbox
域名可使用 Cloudflare 分配的 Worker 域名或自定义域名
Session Duration（会话时间）建议设置长一些，避免频繁登录

3. 配置策略：

系统会自动创建 moltbot-sandbox - Production 策略
默认通过邮箱验证码登录

4. 获取配置变量：

CF_ACCESS_AUD：

保存应用后，点击右侧「⋮」编辑
在应用程序受众（AUD）标签页找到 Application Audience (AUD)

CF_ACCESS_TEAM_DOMAIN：

进入 Zero Trust → Settings
团队域名格式：xxxxxx.cloudflareaccess.com

第四步：配置 R2 对象存储

OpenClaw 需要 R2 来存储状态，需配置以下三个变量：

CF_ACCOUNT_ID
R2_ACCESS_KEY_ID
R2_SECRET_ACCESS_KEY

操作步骤：

1. 获取 Account ID：

在 Cloudflare 侧边栏进入 R2 → Overview
右侧 Account Details 中的 Account ID 即为 CF_ACCOUNT_ID

2. 创建 API 令牌：

点击 Manage R2 API Tokens
选择 Create API Token

3. 设置权限：

权限选择 Object Read & Write
建议范围通过 Specific Bucket 限制在 moltbot-data

4. 保存密钥：

创建成功后，记附录 Access Key ID 和 Secret Access Key

⚠️ 重要提示：修改 Token 时请务必核对变量名称。如果不慎修改了 Build Token，会导致 Worker 构建失败。

第五步：注入变量并重启

进入设置：
- Workers → Settings → Variables and Secrets
填入变量：
- MOLTBOT_GATEWAY_TOKEN（第一步设置的）
- CF_ACCESS_AUD（第三步获取的）
- CF_ACCESS_TEAM_DOMAIN（第三步获取的）
- CF_ACCOUNT_ID（第四步获取的）
- R2_ACCESS_KEY_ID（第四步获取的）
- R2_SECRET_ACCESS_KEY（第四步获取的）
重新部署：
- 点击 Deploy 重新部署
- 等待部署完成

访问与管理

部署完成后，可通过以下地址访问：

访问 Worker（需要 token）：

text

https://moltbot-sandbox.xxxxxxxx.workers.dev?token=MOLTBOT_GATEWAY_TOKEN

管理后台（需要邮箱验证）：

text

https://moltbot-sandbox.xxxxxxxx.workers.dev/_admin/

通过 Cloudflare Access 的邮箱验证码验证后，即可进入管理后台并接受 Pairing Requests。

基础使用

查看或切换模型

bash

# 查看当前模型
/model

# 切换模型
/model minimax/MiniMax-M2.1

设置开机自启命令

为了避免 Worker 重启后模型被重置，建议设置开机自启命令：

bash

set model minimax/MiniMax-M2.1

远程终端连接

bash

# 登录到 Gateway
openclaw gateway login --url https://moltbot-sandbox.xxxxxxxx.workers.dev

# 配置 Skills
openclaw configure --section skills

避坑指南

访问题 1：模型配置报错

症状：通过配置文件修改默认模型后报错

原因：国内 AI 服务商通常区分国内与海外端点，Cloudflare Workers 环境下配置文件修改内容易出错

解决方案：

直接通过开机命令强制指定模型
不要依赖配置文件或后台 UI
使用 set model 命令设置开机自启

访问题 2：Worker 构建失败

症状：部署后 Worker 无法启动

原因：不慎修改了 Build Token

解决方案：

检查所有变量名称是否正确
确保没有修改 Build Token
重新部署

访问题 3：无法访问管理后台

症状：访问 /_admin/ 时无法登录

原因：Zero Trust 配置不正确

解决方案：

检查 CF_ACCESS_AUD 和 CF_ACCESS_TEAM_DOMAIN 是否正确
确认邮箱验证码是否正确
检查 Session Duration 设置

成本估算

项目	费用	说明
Workers Paid 计划	5美元/月	基础费用
额外请求费用	按量计费	高频使用时产生
R2 存储	免费额度内	通常不会超出
总计	5-10美元/月	取决于使用频率

适用场景

推荐使用：

✅ 想低成本尝试 OpenClaw
✅ 已有 Cloudflare 付费订阅
✅ 需要全球 CDN 加速
✅ 不想维护服务器

不推荐使用：

❌ 期望开箱即用
❌ 没有技术背景
❌ 需要复杂的自动化流程
❌ 预算非常有限

总结

Cloudflare Workers + OpenClaw 是一个低成本的尝鲜方案，适合：

未体验过 Agent 自动化，想低成本试手
已有 Cloudflare 付费订阅，资源闲置
需要全球 CDN 加速的场景

但需要注意：

OpenClaw 目前还不是一个能「即刻提升效率」的工具
更像是一个为 AI 自动化搭建的系统底座
如果没有明确的、可标准化的长流程需求，可能只会带来维护成本

下一步：

配置 AI 模型（见下文"API配置指南"）
配置通讯渠道（见第9章节：多平台集成）
安装 Skills（见第8章节：Skills扩展）

Docker 部署（可选）

🐳 开发布者选项：Docker 部署适合需要环境隔离的场景。

为什么选择 Docker？

Docker 部署提供环境隔离和便捷管理，如表 2-5 所示。

表 2-5 Docker 部署优势

优势	说明
🔒 环境隔离	不影响系统环境，干净整洁
📦 一键部署	无需配置依赖，开箱即用
🔄 易于更新	一条命令完成更新
🌐 跨平台	Windows/macOS/Linux 统一方案
🚀 快速启动	5分钟完成部署

前置要求

安装 Docker：

macOS：

bash

# 下载 Docker Desktop
# 访问：https://www.docker.com/products/docker-desktop

# 或使用 Homebrew
brew install --cask docker

Windows：

bash

# 下载 Docker Desktop
# 访问：https://www.docker.com/products/docker-desktop

# 安装 WSL2（如果还没安装）
wsl --install

Linux (Ubuntu)：

bash

# 安装 Docker
curl -fsSL https://get.docker.com | sh

# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

# 添加当前用户到 docker 组
sudo usermod -aG docker $USER

验证安装：

bash

docker --version
# 应显示：Docker version 24.x.x

快速开始

方式一：一键脚本部署（推荐新手）

最简单的方式，一条命令搞定所有配置！

bash

curl -fsSL https://clawd.org.cn/install.sh | bash

这个脚本会自动：

✅ 检查 Docker 环境
✅ 下载镜像（使用国内镜像：jiulingyun803/openclaw-cn:latest）
✅ 配置环境变量
✅ 启动内容器
✅ 运行配置向导
✅ 生成网关令牌

完成后，在浏览器打开 http://127.0.0.1:18789/ 即可使用。

脚本后续操作：

按照提示输入渠道信息（可选）
将生成的令牌复制到 Web UI 登录

方式二：手动 Docker Compose 部署（适合进阶用户）

如果一键脚本不适用，或需要自定义配置，按以下步骤操作。

步骤 1：创建工作目附录

bash

mkdir -p ~/openclaw-docker
cd ~/openclaw-docker

步骤 2：创建 .env 环境文件

bash

cat > .env << 'EOF'
# 镜像配置（使用国内镜像）
OPENCLAW_IMAGE=jiulingyun803/openclaw-cn:latest

# 数据目附录
OPENCLAW_CONFIG_DIR=./data/.openclaw
OPENCLAW_WORKSPACE_DIR=./data/clawd

# 网关配置
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_TOKEN=your-secure-token-here

# Claude 集成（可选）
CLAUDE_AI_SESSION_KEY=
CLAUDE_WEB_SESSION_KEY=
CLAUDE_WEB_COOKIE=
EOF

步骤 3：创建 docker-compose.yml 文件

yaml

services:
  openclaw-cn-gateway:
    image: ${OPENCLAW_IMAGE:-jiulingyun803/openclaw-cn:latest}
    user: node:node
    environment:
      HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY}
      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY}
      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE}
    volumes:
      - ${OPENCLAW_CONFIG_DIR:-./data/.openclaw}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR:-./data/clawd}:/home/node/clawd
    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
    init: true
    restart: unless-stopped
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND:-lan}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT:-18789}"
      ]

  openclaw-cn-cli:
    image: ${OPENCLAW_IMAGE:-jiulingyun803/openclaw-cn:latest}
    user: node:node
    environment:
      HOME: /home/node
      TERM: xterm-256color
      BROWSER: echo
      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY}
      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY}
      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE}
    volumes:
      - ${OPENCLAW_CONFIG_DIR:-./data/.openclaw}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR:-./data/clawd}:/home/node/clawd
    stdin_open: true
    tty: true
    init: true
    entrypoint: ["node", "dist/index.js"]

步骤 4：启动内容器

bash

# 拉取最新镜像
docker compose pull

# 启动网关（后台运行）
docker compose up -d openclaw-cn-gateway

# 查看日志（可选）
docker compose logs -f openclaw-cn-gateway

步骤 5：运行配置向导

bash

docker compose run --rm openclaw-cn-cli onboard

配置向导会提示你：

选择网关后端（Claude、Gemini 等）
配置 Feishu、Telegram 等渠道
生成和保存配置

步骤 6：访问 Web UI

打开浏览器访问：http://127.0.0.1:18789/

将配置向导生成的令牌复制到登录页面即可。

环境变量详解

变量	含义	默认值	必需	说明
OPENCLAW_IMAGE	Docker 镜像名称	jiulingyun803/openclaw-cn:latest	❌	使用国内镜像，也可指定版本号
OPENCLAW_CONFIG_DIR	配置文件目附录	./data/.openclaw	❌	OpenClaw 配置和凭证存储位置
OPENCLAW_WORKSPACE_DIR	工作空间目附录	./data/clawd	❌	代理工作文件存储位置
OPENCLAW_GATEWAY_PORT	网关端口号	18789	❌	访问 Web UI 的端口
OPENCLAW_BRIDGE_PORT	桥接端口号	18790	❌	用于客户端连接的端口
OPENCLAW_GATEWAY_BIND	网关绑定地址	lan	❌	localhost（仅本机）/ lan（局域网）/ 0.0.0.0（公网，⚠️ 谨慎使用）
OPENCLAW_GATEWAY_TOKEN	网关认证令牌	自动生成	❌	Web UI 登录令牌（可自定义或留空自动生成）
CLAUDE_AI_SESSION_KEY	Claude.ai 会话密钥	空	❌	⚠️ 仅使用 Claude AI 作为后端时填写
CLAUDE_WEB_SESSION_KEY	Claude Web 会话密钥	空	❌	⚠️ 仅使用 Claude Web 版时填写
CLAUDE_WEB_COOKIE	Claude Web Cookie	空	❌	⚠️ 仅使用 Claude Web 版时填写

环境变量设置方式：

方式 A：编辑 .env 文件（推荐）

bash

# 编辑 .env 文件
nano .env

# docker compose 会自动读取
docker compose up -d

方式 B：命令行设置

bash

export OPENCLAW_GATEWAY_PORT=18789
docker compose up -d

方式 C：命令行临时覆盖

bash

docker compose -e OPENCLAW_GATEWAY_PORT=8080 up -d

常用操作

查看网关状态

bash

# 检查内容器是否运行
docker compose ps

# 查看网关日志
docker compose logs openclaw-cn-gateway

# 实时查看日志（支持续跟踪）
docker compose logs -f openclaw-cn-gateway

配置渠道

通过 CLI 内容器配置各类渠道：

Telegram（需要机器人令牌）：

bash

docker compose run --rm openclaw-cn-cli channels add \
  --channel telegram \
  --token "YOUR_BOT_TOKEN"

Discord（需要机器人令牌）：

bash

docker compose run --rm openclaw-cn-cli channels add \
  --channel discord \
  --token "YOUR_BOT_TOKEN"

WhatsApp（QR 扫码）：

bash

docker compose run --rm openclaw-cn-cli channels login

Feishu（需要 App ID 和 Secret）：

bash

docker compose run --rm openclaw-cn-cli onboard
# 按提示输入信息

重新配置

bash

# 重新运行配置向导
docker compose run --rm openclaw-cn-cli onboard

# 查看当前配置
docker compose run --rm openclaw-cn-cli config get

重启网关

bash

# 重启网关内容器
docker compose restart openclaw-cn-gateway

# 停止网关
docker compose down

# 重新启动
docker compose up -d openclaw-cn-gateway

更新到最新版本

bash

# 拉取最新镜像
docker compose pull

# 重启内容器（自动使用新镜像）
docker compose up -d openclaw-cn-gateway

清理数据（谨慎操作）

bash

# 停止并删除内容器
docker compose down

# 删除本地数据目附录
rm -rf ./data/

# 删除本地镜像（可选）
docker rmi jiulingyun803/openclaw-cn:latest

数据支持久化

Docker 内容器的数据存储在工作目附录的 data 文件夹：

bash

~/openclaw-docker/data/
├── .openclaw/         # 配置文件
│   ├── openclaw.json  # 主配置
│   └── logs/          # 日志文件件
└── clawd/             # 工作空间
    └── workspace/     # 代理工作文件

备份数据：

bash

# 备份配置和数据
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ./data

# 恢复数据
tar -xzf openclaw-backup-20260210.tar.gz

Docker 部署常见访问题

访问题 1：内容器无法启动

症状：docker compose up 后内容器立即退出

解决方案：

bash

# 查看详细错误日志
docker compose logs openclaw-cn-gateway

# 检查端口是否被占用
sudo netstat -ltnp | grep 18789
# macOS 使用：lsof -i :18789

# 如果被占用，修改 OPENCLAW_GATEWAY_PORT
# 编辑 .env，将端口改为其他（如 18790）
nano .env

访问题 2：权限拒绝（Permission Denied）

症状：Error: EACCES: permission denied, mkdir ...

解决方案：

bash

# 确保数据目附录存在且权限正确
mkdir -p ./data/.openclaw ./data/clawd
chmod 755 ./data/.openclaw ./data/clawd

# 如果使用了宿主机路径，确保目附录可写
chmod 777 ./data

访问题 3：无法访问 Web UI

症状：浏览器访问 http://127.0.0.1:18789 无响应

解决方案：

bash

# 检查内容器是否运行
docker compose ps

# 检查网关日志
docker compose logs openclaw-cn-gateway

# 验证端口是否正确
# 如果 OPENCLAW_GATEWAY_PORT=18789，则访问 :18789
# 如果改了端口，访问对应的新端口

# 检查防火墙设置
# macOS
sudo pfctl -d  # 临时关闭防火墙测试

# Linux
sudo ufw status
sudo ufw allow 18789

访问题 4：配置向导卡住

症状：docker compose run --rm openclaw-cn-cli onboard 无反应

解决方案：

bash

# 按 Ctrl+C 中断

# 检查网关是否运行
docker compose logs openclaw-cn-gateway

# 重新启动网关并重试
docker compose restart openclaw-cn-gateway
docker compose run --rm openclaw-cn-cli onboard

访问题 5：镜像拉取失败（403 错误）

症状：docker pull openclaw/openclaw:latest 返回 403 错误

解决方案：

bash

# 使用国内镜像（推荐）
docker pull jiulingyun803/openclaw-cn:latest

# 或在 .env 文件中指定国内镜像
echo "OPENCLAW_IMAGE=jiulingyun803/openclaw-cn:latest" >> .env

# 重新拉取
docker compose pull

访问题 6：网络超时

症状：拉取镜像或访问 API 时网络超时

解决方案：

bash

# 配置 Docker 镜像加速（国内用户）
# 编辑 Docker 配置
sudo nano /etc/docker/daemon.json

# 添加镜像加速器
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

# 重启 Docker
sudo systemctl restart docker

# macOS 用户在 Docker Desktop 设置中添加镜像加速器

访问题 7：数据丢失

症状：重启内容器后配置和数据丢失

解决方案：

bash

# 确保使用了数据卷挂载
# 检查 docker-compose.yml 中的 volumes 配置

# 查看数据是否存在
ls -la ./data/.openclaw
ls -la ./data/clawd

# 如果数据丢失，从备份恢复
tar -xzf openclaw-backup-20260210.tar.gz

访问题 8：性能访问题

症状：内容器运行缓慢或占用资源过高

解决方案：

bash

# 限制资源使用（编辑 docker-compose.yml）
services:
  openclaw-cn-gateway:
    # ... 其他配置
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

# 重启内容器
docker compose up -d openclaw-cn-gateway

从一键脚本迁移到手动配置

如果想从一键脚本切换到手动配置（或反之）：

bash

# 停止现有内容器
docker compose down

# 备份现有配置
cp -r ~/.openclaw ~/.openclaw.backup

# 更新 .env 和 docker-compose.yml

# 重新启动
docker compose up -d openclaw-cn-gateway

配置会自动保留在数据目附录中，无需重新设置。

Docker 部署优势总结

✅ 环境隔离：不影响系统环境
✅ 快速部署：5分钟完成
✅ 易于管理：一条命令更新
✅ 跨平台：统一部署方案
✅ 可扩展：支持多实例部署
✅ 国内优化：使用国内镜像，下载速度快

推荐使用场景：

开发布者本地测试
服务器部署
多环境隔离
快速体验 OpenClaw

下一步：

配置 API 模型（见下文"API配置指南"）
配置通讯渠道（见第9章节：多平台集成）
安装 Skills（见第8章节：Skills扩展）

更新和维护

🔄 保支持最新：定期更新 OpenClaw 以获得新功能和安全修复。

检查更新

bash

# 检查当前版本
openclaw --version

# 检查最新版本
curl -s https://api.github.com/repos/openclaw/openclaw/releases/latest | grep tag_name

本地安装更新

bash

# 方式一：使用安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 方式二：手动更新
cd ~/openclaw
git pull origin main
pnpm install
pnpm build

Docker 更新

bash

# 拉取最新镜像
docker pull openclaw/openclaw:latest

# 停止并删除旧内容器
docker stop openclaw
docker rm openclaw

# 启动新内容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  --restart unless-stopped \
  openclaw/openclaw:latest

备份数据

本地安装备份：

bash

# 备份配置和数据
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw

# 恢复数据
tar -xzf openclaw-backup-20260210.tar.gz -C ~/

Docker 备份：

bash

# 备份数据卷
docker run --rm \
  -v ~/.openclaw:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/openclaw-backup-$(date +%Y%m%d).tar.gz /data

# 恢复数据
docker run --rm \
  -v ~/.openclaw:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/openclaw-backup-20260210.tar.gz -C /

监控和日志

查看日志：

bash

# 本地安装
tail -f ~/.openclaw/logs/gateway.log

# Docker
docker logs -f openclaw

监控指标：

bash

# 查看系统状态
openclaw gateway status

# 查看资源使用
openclaw stats

# 查看 API 消耗和额度
openclaw status --usage

故障排查

常见访问题：

Gateway 无法启动

bash

# 查看日志
openclaw logs

# 检查端口占用
lsof -i :18789

# 重启 Gateway
openclaw gateway restart

API 连接失败

bash

# 测试 API 连接
openclaw test api

# 检查 API Key
openclaw config get models.providers

性能访问题

bash

# 清理缓存
openclaw cache clear

# 重启服务
openclaw gateway restart

卸载

本地安装卸载：

bash

# 停止服务
openclaw gateway stop

# 删除文件
rm -rf ~/.openclaw
rm -rf ~/openclaw

# 删除命令
npm uninstall -g openclaw

Docker 卸载：

bash

# 停止并删除内容器
docker stop openclaw
docker rm openclaw

# 删除镜像
docker rmi openclaw/openclaw

# 删除数据
rm -rf ~/.openclaw

API配置指南

OpenClaw需要连接AI模型才能工作，推荐使用国产大模型，性价比高。

为什么需要API？

OpenClaw本身不包含AI模型，需要连接第三方API：

官方API：价格贵、国内访问困难
第三方API：价格便宜、国内直连

API模型分类

OpenClaw支持两种类型的API模型配置：

1. 内置 API 模型（推荐新手）

什么是内置API模型？

OpenClaw已经预先配置好了多个主流AI模型的连接方式，你只需要：

✅ 获取API Key
✅ 在配置向导中选择对应模型
✅ 粘贴API Key即可使用

支持的内置模型：

OpenClaw内置支持非常多的API模型，包括但不限于：

国内模型（推荐）：

🌙 Moonshot AI (Kimi)：长文本专家，200万字上下文
🧠 DeepSeek：性价比之王，推理能力强
🎯 智谱GLM：中文理解好，多模态支持
🚀 通义千访问 (Qwen)：阿里出品，稳定可靠
🎨 MiniMax：对话自然，创意能力强
📚 百度文心：中文语料丰富
🔥 字节豆包：性价比高

国外模型：

🤖 OpenAI (GPT-4/GPT-3.5)：最强大但价格贵
🦙 Anthropic (Claude)：推理能力强，安全性高
🔷 Google (Gemini)：多模态能力强
🌐 Groq：推理速度快

优势：

✅ 配置简单，无需手动编写配置文件
✅ 参数已优化，开箱即用
✅ 自动更新，跟随OpenClaw版本
✅ 适合新手，降低使用门槛

使用场景：

🎯 新手用户快速上手
🎯 使用主流大模型
🎯 不想折腾配置文件

2. 自定义 API（进阶用户）

什么是自定义API？

如果你想使用：

🔧 OpenClaw未内置的模型
🔧 自己搭建的模型服务
🔧 第三方API代理服务
🔧 企业内部的模型接口

就需要使用自定义API配置。

配置方式：

需要手动编辑配置文件 ~/.openclaw/openclaw.json，指定：

baseUrl：API服务地址
apiKey：认证密钥
api：API协议类型（如 openai-chat、anthropic-messages）
models：模型列表和参数

优势：

✅ 灵活性高，支持任何兼内容的API
✅ 可以使用小众模型
✅ 可以自定义模型参数
✅ 适合企业定制化需求

劣势：

⚠️ 配置复杂，需要了解JSON格式
⚠️ 需要手动维护配置
⚠️ 参数错误可能导致无法使用

使用场景：

🎯 进阶用户
🎯 使用非主流模型
🎯 企业内部部署
🎯 需要精细控制参数

配置方式对比

两种配置方式的对比如表 2-6 所示。

表 2-6 API 配置方式对比

特性	内置API模型	自定义API
配置难度	⭐ 简单	⭐⭐⭐⭐ 复杂
适用人群	新手	进阶用户
模型选择	主流模型	任意模型
配置方式	向导选择	手动编辑
维护成本	低	高
灵活性	中	高

自定义API配置（进阶用户）

⚠️ 适合人群：进阶用户、需要使用非主流模型、企业定制化需求

什么时候需要自定义API？

如果你遇到以下情况，需要使用自定义API配置：

使用非内置模型：
- OpenClaw未内置的小众模型
- 新发布布的模型（OpenClaw还未更新）
- 区域限定的模型
使用第三方代理：
- API代理服务（如 OpenRouter、API2D）
- 企业内部的API网关
- 自建的模型服务
精细控制参数：
- 自定义模型参数
- 调整上下文窗口大小
- 修改默认配置

配置文件位置

📖 详细说明: 完整的配置文件结构和使用指南请参考配置文件结构完整指南

bash

# 配置文件路径
~/.openclaw/openclaw.json

# 编辑配置文件
nano ~/.openclaw/openclaw.json

配置文件结构

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "你的供应商名称": {
        "baseUrl": "API服务地址",
        "apiKey": "你的API 密钥",
        "auth": "认证方式",
        "api": "API协议类型",
        "models": [
          {
            "id": "模型ID",
            "name": "模型显示名称",
            "contextWindow": 上下文窗口大小,
            "maxTokens": 最大输出tokens
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "供应商名称/模型ID"
      }
    }
  }
}

示例1：配置DeepSeek（自定义方式）

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "sk-你的API 密钥",
        "auth": "api-key",
        "api": "openai-chat",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat",
            "contextWindow": 64000,
            "maxTokens": 4096
          },
          {
            "id": "deepseek-coder",
            "name": "DeepSeek Coder",
            "contextWindow": 64000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      }
    }
  }
}

示例2：配置第三方API代理

如果你使用API代理服务（如OpenRouter），配置如下：

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "openrouter": {
        "baseUrl": "https://openrouter.ai/api/v1",
        "apiKey": "sk-or-v1-你的密钥",
        "auth": "api-key",
        "api": "openai-chat",
        "models": [
          {
            "id": "anthropic/claude-3.5-sonnet",
            "name": "Claude 3.5 Sonnet",
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "openai/gpt-4",
            "name": "GPT-4",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-3.5-sonnet"
      }
    }
  }
}

示例3：配置多个模型供应商

你可以同时配置多个供应商，根据需要切换：

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "sk-你的DeepSeek密钥",
        "auth": "api-key",
        "api": "openai-chat",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat",
            "contextWindow": 64000,
            "maxTokens": 4096
          }
        ]
      },
      "moonshot": {
        "baseUrl": "https://api.moonshot.cn/v1",
        "apiKey": "sk-你的Kimi密钥",
        "auth": "api-key",
        "api": "openai-chat",
        "models": [
          {
            "id": "moonshot-v1-128k",
            "name": "Kimi 128K",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat",
        "fallback": "moonshot/moonshot-v1-128k"
      }
    }
  }
}

配置参数说明

参数	说明	示例
`baseUrl`	API服务地址	`https://api.deepseek.com`
`apiKey`	API 密钥	`sk-xxx`
`auth`	认证方式	`api-key` 或 `bearer`
`api`	API协议	`openai-chat`、`anthropic-messages`
`id`	模型ID	`deepseek-chat`
`name`	显示名称	`DeepSeek Chat`
`contextWindow`	上下文窗口	`64000`
`maxTokens`	最大输出	`4096`

常见API协议类型

openai-chat：OpenAI兼内容接口（最常用）
anthropic-messages：Anthropic Claude接口
google-generative-ai：Google Gemini接口
azure-openai：Azure OpenAI接口

配置后重启服务

bash

# 方式1：重启Gateway
openclaw gateway restart

# 方式2：停止后重新启动
systemctl --user stop openclaw-gateway.service
systemctl --user start openclaw-gateway.service

# 方式3：完全重启
systemctl --user restart openclaw-gateway.service

验证配置

bash

# 查看当前配置的模型
openclaw models list

# 测试模型连接
openclaw models test deepseek/deepseek-chat

常见访问题

Q1：配置后无法连接？

text

检查项：
✅ baseUrl是否正确
✅ apiKey是否有效
✅ 网络是否能访问API地址
✅ 配置文件JSON格式是否正确

Q2：如何切换模型？

bash

# 临时切换
openclaw agent --message --model deepseek/deepseek-chat

# 永久切换：修改配置文件中的 primary 字段

Q3：如何添加多个模型？

text

在 models 数组中添加多个模型对象即可
每个模型需要有唯一的 id

内置API模型配置（推荐新手）

💡 适合人群：新手用户、想要快速上手的用户

以下是几个常用的内置API模型配置教程，选择一个你喜欢的即可。

1. Kimi 2.5 配置（推荐）

特点：

📚 超长上下文：支持200万字
📄 长文档处理：论文、报告分析专家
🎯 中文理解好：适合中文场景
💰 套餐划算：重度使用建议购买套餐

配置步骤：

第一步：访问Kimi Code平台

访问：https://www.kimi.com/code

第二步：购买套餐（可选）

💡 提示：OpenClaw消耗token较大，建议购买套餐更划算。

推荐套餐：

Allegretto套餐：适合日常使用
按需选择其他套餐

第三步：创建API Key

打开控制台
创建API Key
名称随便取

第四步：保存API Key

⚠️ 重要：这个API Key一定要复制并保存！点击"完成"后就无法再查看了。

第五步：配置到OpenClaw

bash

# 运行配置向导
openclaw onboard

# 配置流程：
# 1. 选择 QuickStart
# 2. 选择模型供应商：Moonshot AI
# 3. 粘贴刚才复制的API Key
# 4. 选择默认模型：kimi-code/kimi-for-codi
# 5. 完成其他配置

成本估算：

轻度使用：10-20元/月
中度使用：30-50元/月
重度使用：建议购买套餐

2. DeepSeek 配置（性价比之王）

特点：

💰 最便宜：输入0.001元/千tokens
🧠 推理能力强：适合复杂任务
💻 编程能力出色：代码生成质量高

配置步骤：

第一步：注册并充值

访问：https://platform.deepseek.com/

⚠️ 注意：DeepSeek采用按量付费，账户余额必须大于0才能调用API。

第二步：充值账户

建议先充值10元试用：

第三步：创建API Key

保证账号有余额
点击"API keys"
点击"创建API key"

第四步：保存API Key

⚠️ 重要：API Key只显示一次，务必复制保存！

名称随便取，复制API Key后妥善保存。

第五步：配置到OpenClaw

bash

# 运行配置向导
openclaw onboard

# 配置流程：
# 1. 选择 QuickStart
# 2. 选择模型供应商：DeepSeek
# 3. 粘贴API Key
# 4. 选择默认模型：deepseek-chat
# 5. 完成其他配置

成本估算：

日常使用：5-10元/月
中度使用：10-30元/月
重度使用：30-50元/月

国产大模型配置（其他选项）

1. DeepSeek配置（性价比之王）

特点：

💰 最便宜：输入0.001元/千tokens
🧠 推理能力强：适合复杂任务
💻 编程能力出色：代码生成质量高

DeepSeek 的 API 调用是按量付费的，你的账户余额必须大于 0 才能正常调用接口。

如果账户没钱或余额不足，API 请求会直接失败，所以提前充值是保证服务可用的必要操作。

其他大模型也是同理，你要去找到对应网址去充值，然后获取API keys

如果你只想先尝，可以就先花个10块钱玩一下

保证账号有余额之后，点击”API keys“，然后点”创建 API key“

API key的名称：随便取。然后这个APIkey一定！一定！要复制下来，因为一般你点完”关闭“之后，你就再也无法查看你的API key了，如果你我忘记了你的API key，那只能重新创建一个了。

复制完后，找地方先存起来，后续在”第四步：OpenClaw 配置“的时候会用到

好，至此”第二步：配置模型“完成，进入”第三步：配置Bot“吧

配置步骤：

注册账号：

text

访问：https://platform.deepseek.com/
注册并登录

获取API Key：

text

进入"API管理"
点击"创建API Key"
复制API Key（格式：sk-xxx）

配置到OpenClaw：

bash

# 编辑配置文件
nano ~/.openclaw/openclaw.json

添加配置：

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "sk-你的API 密钥",
        "auth": "api-key",
        "api": "openai-chat",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat",
            "contextWindow": 64000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      }
    }
  }
}

重启Gateway：
bash
```
openclaw gateway restart
```

成本估算：

日常使用：5-10元/月
中度使用：10-30元/月
重度使用：30-50元/月

2. Kimi配置（长文本专家）

特点：

📚 超长上下文：支持200万字
📄 长文档处理：论文、报告分析专家
🎯 中文理解好：适合中文场景

那如何使用，第一步，搜索 kimi code：https://www.kimi.com/code

第二步，购买优惠套餐 plan，说实话，目前 OpenClaw 消耗 token 还挺大的，最好买个套餐划算一些，我买的是 Allegretto 套餐。

第二步，打开控制台，创建 API key。名字随便取。

这个APIkey一定！一定！要复制下来，因为一般你点完”完成“之后，你就再也无法查看你的API key了，如果你忘记了你的API key，那就只能重新创建一个了。复制完后，找地方先存起来，后续在”第四步：OpenClaw 配置“的时候会用到

配置步骤：

注册账号：

text

访问：https://platform.moonshot.cn/
注册并登录

获取API Key：

text

进入"API管理"
点击"创建API Key"
复制API Key

配置到OpenClaw：

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.cn/v1",
        "apiKey": "sk-你的API 密钥",
        "auth": "api-key",
        "api": "openai-chat",
        "models": [
          {
            "id": "moonshot-v1-8k",
            "name": "Kimi k2.5",
            "contextWindow": 8000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "moonshot/moonshot-v1-8k"
      }
    }
  }
}

成本估算：

日常使用：10-20元/月
中度使用：20-50元/月
重度使用：50-100元/月

3. 其他国产大模型

模型	特点	价格	官网
GLM-4	多模态能力强	中等	https://open.bigmodel.cn/
文心一言	百度生态	中高	https://cloud.baidu.com/
通义千访问	阿里生态	中等	https://dashscope.aliyun.com/

国际模型配置（可选）

如果需要使用Claude、GPT等国际模型：

直接使用官方API（需要魔法）
使用第三方API服务（国内直连）

推荐第三方API：

价格便宜50%-70%
国内直连，无需魔法
支持支付宝、微信支付

成本对比

模型	输入价格	输出价格	月费用估算
DeepSeek	0.001元/千tokens	0.002元/千tokens	5-30元
Kimi	0.012元/千tokens	0.012元/千tokens	10-50元
GLM-4	0.005元/千tokens	0.005元/千tokens	10-40元
Claude（第三方）	0.015元/千tokens	0.075元/千tokens	50-200元
GPT-4（第三方）	0.03元/千tokens	0.06元/千tokens	100-300元

💡 省钱技巧：

日常对话用DeepSeek（最便宜）
长文档用Kimi（长上下文）
复杂任务用Claude（质量最高）

常见访问题解决

安装访问题

Q1: Node.js版本不对

bash

# 检查版本
node --version

# 如果低于22，升级
nvm install 22
nvm use 22

Q2: 权限错误

bash

# macOS/Linux
sudo chown -R $USER ~/.openclaw

# Windows
# 以管理员身份运行PowerShell

Q3: 网络连接失败

检查网络连接
尝试使用代理
或使用云端部署

API配置访问题

Q1: API Key无效

检查是否完整复制（包括sk-前缀）
检查是否有多余空格
检查账户余额是否充足

Q2: 模型不可用

检查模型ID是否正确
检查API服务是否正常
尝试切换其他模型

Q3: Token消耗太快

使用更便宜的模型（DeepSeek）
优化提示词
定期清理会话历史

Gateway访问题

Q1: Gateway无法启动

bash

# 查看日志
tail -f ~/.openclaw/logs/gateway.log

# 重启Gateway
openclaw gateway restart

Q2: 端口被占用

bash

# 查看端口占用
lsof -i :18789

# 修改端口
openclaw config set gateway.port 18790

2.X 版本升级指南

🔄 保持最新：OpenClaw 迭代很快，升级通常会带来安全修复、provider 兼容性修复、渠道稳定性改进和新模型目录。

⚠️ 当前推荐版本：截至 2026-09-10，本教程推荐使用 OpenClaw 2026.9.3（稳定版）。升级前先备份 ~/.openclaw；升级后务必运行 openclaw doctor --fix、openclaw update repair 和状态检查。

升级前必做

bash

# 1) 备份配置和本地状态
cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d-%H%M%S)

# 2) 记录当前版本
openclaw --version > ~/openclaw-version-before-upgrade.txt

# 3) 检查当前服务状态
openclaw gateway status
openclaw channels status

不要跳过备份。OpenClaw 的配置、凭据引用、会话、插件状态都可能保存在 ~/.openclaw 下。

方式一：使用 `openclaw update`（推荐）

openclaw update 是当前 CLI 的统一升级入口。全局 npm 安装会通过检测到的包管理器更新；source checkout 会走 git 更新、依赖安装、构建和 doctor 流程。

bash

# 预览升级动作，不真正写入
openclaw update --tag 2026.9.3 --dry-run

# 升级到教程推荐版本
openclaw update --tag 2026.9.3 --yes

# 如果你想直接跟随稳定频道
openclaw update --channel stable --yes

升级完成后：

bash

openclaw update repair
openclaw doctor --fix
openclaw gateway restart
openclaw --version
openclaw gateway status
openclaw channels status
openclaw models status

从 2026.6.x / 2026.7.x / 2026.8.x 跨大版本升级时，doctor --fix 会处理：OpenAI 路由迁移（codex/*、openai-codex/* → openai/*）、OpenProse 残留清理、会话 SQLite 相关修复、Workshop 技能归属迁移等。

方式二：npm 固定版本安装（兜底）

如果 openclaw update 在你的环境里失败，或者你明确知道自己是 npm 全局安装，可以用固定版本覆盖安装。

bash

# 停止 Gateway
openclaw gateway stop

# 安装推荐版本
npm install [email protected] --allow-scripts=openclaw

# 修复更新后的插件/配置收敛状态
openclaw update repair
openclaw doctor --fix

# 重启并验证
openclaw gateway restart
openclaw --version
openclaw gateway status
openclaw channels status

如果你不想固定版本，也可以使用：

bash

npm install openclaw@latest --allow-scripts=openclaw

方式三：官方安装脚本

如果你是首次安装，或希望安装器自动处理 Node、路径和 onboarding，可以继续使用官方脚本：

bash

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

如果只想安装 CLI、不立即跑 onboarding：

bash

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

方式四：Docker / 云端部署

Docker 部署通常按镜像更新：

bash

docker compose down
docker compose pull
docker compose up -d

docker compose logs -f

云端一键镜像、面板插件或第三方托管版本，需要进入对应控制台查看镜像版本。不要只看网页 UI 是否能打开，一定要确认后端 OpenClaw 版本。

升级后验证清单

bash

openclaw --version
node -v
openclaw doctor
openclaw gateway status
openclaw channels status
openclaw models status
openclaw models status --probe
openclaw skills check

跨大版本后若仍有旧路由/插件残留，再跑一次：

bash

openclaw doctor --fix

看到下面结果，才算升级基本完成：

openclaw --version 返回 2026.9.3 或你指定的新版本
openclaw doctor 没有阻塞级错误
openclaw gateway status 显示 Gateway 正常运行
openclaw channels status 能看到你需要的渠道状态
openclaw models status --probe 没有明显认证失败

2026.9.3 升级后重点验证

从旧基线跳到 v2026.9.3，优先确认这些主线变化（而不是只核对版本号）：

Node 运行时：需要 Node 24.16+ 或 26.1+（推荐 26）；升级 OpenClaw 前先升级 Node
Doctor 迁移：openclaw doctor --fix（OpenAI 路由、OpenProse 清理、会话/状态修复）
会话存储：2026.8.1 起会话/转录进入 SQLite——不要在未备份时降级
Skills / Workshop：优先 openclaw skills …；Workshop 技能按 Agent 持久化；旧 clawhub install … 仅作历史参考
更新恢复：2026.9.x 支持更新预演与更干净的失败恢复；可用 openclaw update status 查看报告

建议升级后至少做这组 smoke test：

bash

node -v
openclaw --version
openclaw doctor
openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
openclaw models status --probe
openclaw gateway status
openclaw channels status

常见升级问题

npm 报 EEXIST

bash

npm install [email protected] --allow-scripts=openclaw

Gateway 启动失败

bash

openclaw update repair
openclaw doctor --fix
openclaw gateway restart
tail -f ~/.openclaw/logs/gateway.log

配置由更高版本写入

这通常说明你正在用旧 CLI 读取新配置。先升级 CLI，再运行 repair 和 doctor：

bash

npm install [email protected] --allow-scripts=openclaw
openclaw update repair
openclaw doctor --fix

端口被占用

bash

lsof -i :18789
kill -9 <PID>

# 或换端口
openclaw config set gateway.port 18790
openclaw gateway restart

回滚建议

回滚可能导致新版本写入的配置无法被旧版本识别，所以只在确实无法恢复时使用。优先从备份恢复配置，再安装目标版本。

bash

openclaw gateway stop
cp -r ~/.openclaw.backup-YYYYMMDD-HHMMSS/* ~/.openclaw/
npm install openclaw@<target-version> --force
openclaw doctor
openclaw gateway restart

升级节奏建议

普通用户：每月检查一次 npm view openclaw version
生产环境：先在测试机升级，跑完 smoke test 再动主环境
安全修复或渠道故障修复：优先升级
正在跑重要自动化时：先暂停任务、备份，再升级

本章节小结

通过本章节，你应该已经：

✅ 了解了云端部署和本地部署的区别
✅ 完成了OpenClaw的安装（云端或本地）
✅ 配置了API（推荐国产大模型）
✅ 验证了安装是否成功
✅ 学会了如何升级OpenClaw

实战练习

完成OpenClaw安装（云端或本地）
配置至少一个API（推荐DeepSeek或Kimi）
发布送第一条测试消息
验证AI是否正常回复
检查当前版本，如有更新可尝试升级

下一章节：第3章节：快速上手 - 开始使用 OpenClaw

返回目附录：README

🌐 在线阅读

📖 想在线阅读此章节节？

🔗 在线阅读此章节节

访问网站获取更好的阅读体验：

📱 响应式设计，支持手机、平板、电脑
支持黑暗模式，保护眼睛
🔍 内置搜索功能，快速定位内内容
📋 目附录导航，轻松跳转章节节

🏠 访问完整教网站

01 Basics 03 Quick Start (`docs/01-basics/03-quick-start.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第3章节：快速上手

⚠️ 当前基线：OpenClaw v2026.9.3。首次配置优先 openclaw onboard；模型登录用 openclaw models auth login --provider （OpenAI 用 openai，不要再用 openai-codex）。升级后请跑 openclaw doctor --fix。

恭喜你完成了安装！现在开始使用 OpenClaw，体验AI助手的魅力。

3.1 第一次对话

启动OpenClaw

根据你的部署方式，选择对应的启动方法：

云端部署用户

通过Web UI访问：

txt

http://你的服务器IP:18789/?token=你的token

通过IM平台访问（推荐）：
- 打开QQ/企微/飞书/钉钉
- 找到你配置的Bot
- 直接发布消息

本地部署用户

检查Gateway状态：
bash
```
openclaw channels status
```

打开Web UI：

bash

openclaw dashboard

或直接访问：

txt

http://127.0.0.1:18789/?token=你的token

发布送第一条消息

在Web UI或IM平台中，发布送：

你好，能听到我说话吗？

预期回复：

OpenClaw会回复类似：
你好！我能听到你说话。我是你的AI助手，可以帮你处理各种任务。
有什么我可以帮你的吗？

验证成功的标志：

✅ 收到AI的回复
✅ 右上角显示模型名称（Web UI）
✅ 显示Token使用情况

理解OpenClaw的回复

OpenClaw的回复包含几个部分：

文本内内容：AI的回答
工具调用（如果有）：执行的操作
Token统计：消耗的Token数量

示例：
[AI回复]
好的，我帮你搜索一下。

[工具调用]
🔍 正在搜索文件...
📁 找到3个相关文件

[Token统计]
输入：120 tokens
输出：45 tokens

如何提出好访问题

❌ 不好的访问题：
帮我

✅ 好的访问题：
帮我找一下电脑上所有的PDF文件，按修改时间排序

提访问技巧：

明确目标：说清楚你想做什么
提供上下文：给出必要的背景信息
具体细节：说明具体要求
分步骤：复杂任务可以分步骤说明

示例对比：

不好的访问题	好的访问题
"找文件"	"帮我找一下我电脑上的一张发布票，里面详情是买了一个跑步机"
"整理"	"把我下载文件夹里的所有图片，按日期分类到不同的文件夹"
"提醒我"	"明天上午10点提醒我开会，地点是会议室A"

3.2 基本命令使用

常用命令列表

OpenClaw支持自然语言命令，以下是一些常用的命令模式：

文件操作命令

搜索文件：
帮我找一下包含"发布票"的文件
搜索所有PDF文件
找一下最近修改的10个文件

读取文件：
读取桌面上的README.md文件
打开下载文件夹里的报告.docx
查看这个文件的内内容：/path/to/file.txt

创建文件：
在桌面创建一个名为"笔记.txt"的文件
新建一个Markdown文件，内内容是...

移动/复制文件：

把这个文件移动到文档文件夹
复制所有图片到备份文件夹

系统操作命令

查看系统信息：
查看当前时间
显示系统信息
检查磁盘空间

打开应用：
打开微信
启动浏览器

截图：
给我截个屏
截取当前窗口

日历操作命令

创建日历事件：
明天下午3点提醒我开会
下周一上午10点，会议室A，项目讨论

查看日程：
今天有什么安排
下周的日程

知识管理命令

保存网页：
把这个网页保存到备忘附录：https://example.com
总结这篇文章节并存到Notion

管理笔记：
在备忘附录里创建一条笔记
搜索备忘附录里关于"AI"的内内容

命令速查表

功能	命令示例
搜索文件	`找一下包含"发布票"的文件`
读取文件	`读取桌面上的README.md`
创建文件	`在桌面创建一个笔记.txt`
移动文件	`把这个文件移动到文档文件夹`
截图	`给我截个屏`
创建日历	`明天下午3点提醒我开会`
保存网页	`把这个网页保存到备忘附录`
系统信息	`查看磁盘空间`

实战练习

练习1：搜索文件
帮我找一下电脑上所有的PNG图片

练习2：创建日历
明天上午10点提醒我：给老板发布周报

练习3：保存网页
把这个网页总结一下并保存到备忘附录：
https://docs.openclaw.ai

3.3 人设配置技巧

什么是人设（Persona）

人设（Persona）是给AI助手设定的性格、身份和行为方式。

为什么要设置人设？

🎭 个性化：让AI更符合你的喜好
💬 沟通风格：调整回复的语气和风格
🎯 专业化：针对特定场景优化
😊 趣味性：让对话更有趣

如何设计一个好的人设

好的人设应该包含：

名字：给AI起个名字
身份：定义AI的角色
性格：设定性格特点
专长：明确擅长的领域
风格：回复的语气和风格

人设配置方法

OpenClaw 的工作区包含多个配置文件，每个文件都有特定的作用。

工作区结构（Workspace Anatomy）

OpenClaw 的配置文件位于：~/.openclaw/workspace

OpenClaw 的核心配置文件及其作用如表 3-1 所示。

表 3-1 OpenClaw 核心配置文件

文件	作用	说明
SOUL.md	人格/语气	AI的性格、说话风格、行为准则
USER.md	偏好设置	用户信息、习惯、偏好
AGENTS.md	指令说明	Agent的工作指令和任务说明
MEMORY.md	长期记忆	AI的长期记忆和学习内内容
HEARTBEAT.md	检查清单	定期检查和维护任务
IDENTITY.md	名称/主题	AI的名称、身份、主题设定
BOOT.md	启动配置	启动时的初始化配置

什么是 SOUL.md 和 USER.md？

SOUL.md：AI的"宪法"

定义AI的性格和说话风格
设定AI的行为准则和边界
配置AI的工作方式

USER.md：AI对你的理解

记附录你的基本信息（名字、时区等）
你的工作和生活习惯
你的偏好和要求

💡 新手建议：刚开始只需要配置 SOUL.md 和 USER.md 这两个文件就够了，其他文件可以后续根据需要再配置。

配置方法：通过 Web UI（推荐）

打开 OpenClaw 页面

text

http://你的服务器IP:18789/?token=你的token

点击 Agent → Files
- 在左侧菜单找到 "Agent"
- 点击 "Files" 选项
- 你会看到所有配置文件
编辑 SOUL.md
- 找到 SOUL.md 文件
- 点击编辑
- 输入你的人设配置
编辑 USER.md
- 找到 USER.md 文件
- 点击编辑
- 输入你的个人信息
保存并生效
- 点击保存
- 配置立即生效，无需重启

配置方法：直接编辑文件（进阶）

如果你熟悉命令行，也可以直接编辑配置文件。

配置文件位置：

bash

~/.openclaw/workspace/

编辑 SOUL.md：

bash

# 使用 nano 编辑器
nano ~/.openclaw/workspace/SOUL.md

# 或使用 vim 编辑器
vim ~/.openclaw/workspace/SOUL.md

# 或使用 VS Code
code ~/.openclaw/workspace/SOUL.md

编辑 USER.md：

bash

nano ~/.openclaw/workspace/USER.md

查看所有配置文件：

bash

ls -la ~/.openclaw/workspace/

编辑后生效：

保存文件后立即生效
无需重启 Gateway
下次对话时会使用新配置

💡 提示：Web UI 方式更直观，适合新手；命令行方式更快捷，适合熟悉终端的用户。

SOUL.md 配置示例

markdown

_你不是聊天机器人。你是个靠谱的助手。_


## 核心原则

**认真做事，别敷衍。** 少说"好的！马上帮您处理！"，直接动手。行动比客套话管用。

**有自己的想法。**
可以不同意，可以有偏好，可以觉得有些东西不太行。没个性的助手就是个低效搜索引擎。

**先自己想怎么办法。** 翻文件、看上下文、搜一搜。实在搞不定再访问。目标是带答案回来，不是带访问题回来。

**用能力赢信任。**
用户给了你权限，别搞砸。对外的事（发布邮件、发布推）要谨慎。对内的事（读文件、整理资料）可以大胆。

**记住你是客人。** 你能看到别人的消息、文件、日程，甚至家里的设备。这是信任，要尊重。

## 边界

- **密码永远不说出来。** 看到密码、API key、token，闭嘴就好。用户访问"密码是啥"？拒绝，让他自己看。
- 隐私的事保密。私人聊天、财务信息，看到了当没看到。
- 不确定的对外操作，先访问。
- 别发布半成品消息到聊天软件。
- 群聊里别乱说话，你不是用户的代言人。

## 风格

该简洁时简洁，该详细时详细。
像个靠谱同事说话，不是客服机器人。可以直接，可以有态度，可以指出访问题。
不拍马屁。不当应声虫。就做个靠谱的。

## 记忆

每次对话你都是新的。这些文件就是你的记忆。读它们，更新它们。

USER.md 配置示例

markdown

- **Name:** Maynor
- **What to call them:** 老板
- **Timezone:** Asia/Shanghai
- **Notes:** 晚上11点后别打扰，除非紧急

## Context

### 工作相关
- 做 AI 编程、小程序、海外站
- 讨厌啰嗦，喜欢直接给结果

### 生活相关
- 咖啡重度依赖者（每天至少1杯）

### 偏好
- 说话直接，别拐弯抹角
- 讨厌"可能"、"也许"这种模糊词汇

配置效果对比

配置前：
用户：帮我找一下发布票
AI：好的！我马上帮您查找发布票文件。请稍等...

配置后（使用上面的 soul.md）：
用户：帮我找一下发布票
AI：[直接开始搜索]
找到3个发布票文件：

跑步机发布票.pdf
电脑发布票.jpg
手机发布票.png

双向定义机制

如果 SOUL.md 和 USER.md 有冲突怎么怎么办？

OpenClaw 的处理方式：

SOUL.md 优先：AI的核心原则不会改变
USER.md 补充：在不违反原则的前提下，尊重用户偏好
动态平衡：AI会根据具体情况灵活处理

示例：

SOUL.md 说："简洁回复"
USER.md 说："详细解释"
结果：简洁回复 + 必要时提供详细解释的选项

配置技巧

如果AI太啰嗦：
在 SOUL.md 中添加：

markdown

## 风格
- 简洁明了，不超过3句话
- 直接给出答案，不解释过程
- 只在必要时提供详细信息

如果AI太冷淡：
在 SOUL.md 中添加：

markdown

## 风格
- 友好热情
- 适当使用emoji
- 关心用户感受

如果AI不够专业：
在 SOUL.md 中添加：

markdown

## 风格
- 专业准确
- 提供数据支持
- 引用可靠来源

其他配置文件说明（进阶）

AGENTS.md - 指令说明

定义 Agent 的工作指令和任务说明。

示例：

markdown

## 主要任务

1. 文件管理
   - 搜索和整理文件
   - 批量处理文档
   - 清理重复文件

2. 日程管理
   - 创建日历事件
   - 设置提醒
   - 同步日程

3. 知识管理
   - 保存网页内内容
   - 整理笔记
   - 管理书签

MEMORY.md - 长期记忆

AI 的长期记忆和学习内内容，会随着使用自动更新。

示例：

markdown

## 用户偏好记附录

- 喜欢简洁的回复
- 经常在晚上工作
- 偏好使用 Markdown 格式

## 常用操作

- 每周一生成周报
- 每天晚上11点提醒休息
- 自动备份重要文件

HEARTBEAT.md - 检查清单

定期检查和维护任务。

示例：

markdown

## 每日检查

- [ ] 检查待怎么办事项
- [ ] 清理临时文件
- [ ] 备份重要数据

## 每周检查

- [ ] 整理文件夹
- [ ] 更新知识库
- [ ] 生成周报

IDENTITY.md - 名称/主题

AI 的名称、身份、主题设定。

示例：

markdown

## 身份信息

- 名称：小卡
- 角色：AI助手
- 专长：文件管理、日程管理、知识管理
- 主题：高效、专业、友好

BOOT.md - 启动配置

启动时的初始化配置。

示例：

markdown

## 启动检查

1. 检查系统状态
2. 加载用户配置
3. 初始化工作区
4. 准备就绪

## 启动消息

系统已启动，准备为您服务！
> 💡 **使用建议**：
> - 新手：只配置 SOUL.md 和 USER.md
> - 进阶：添加 AGENTS.md 定义具体任务
> - 高级：使用 MEMORY.md 和 HEARTBEAT.md 实现自动化

真实案例分分享

用了 OpenClaw 的 soul.md 和 user.md 之后，AI助手的体验完全不同了。

以前：AI 是工具，用完就关
现在：AI 是伙伴，会陪你成长，还能自我进化

效果展示：

✅ 每次对话都很睿智
✅ 称呼你设定的昵称（如"老板"）
✅ 知道晚上11点要提醒你睡觉
✅ 会用emoji表情和你对话
✅ 记住你的偏好和习惯

3.4 模型选择指南

💡 快速选择：新手推荐 Claude Haiku 4.5 或 DeepSeek，性价比高且完全够用。详细的模型对比和切换策略请参考第11章节：高级配置。

模型提供商总览

OpenClaw支持十余家模型提供商，从国际顶尖到国产平价再到完全免费的本地模型，覆盖所有预算和场景。

OpenClaw最大的优势之一是模型自由：你不被绑定在某一家厂商上。通过 ~/.openclaw/openclaw.json 配置文件，可以灵活切换主力模型、设置Fallback备选链、甚至让不同任务走不同模型。

支持的模型提供商一览

提供商	代表模型	输入价格 /1M tokens	输出价格 /1M tokens	接入方式	推荐场景
Anthropic	Claude Sonnet 4.6	$3.00	$15.00	内置Provider	Agent任务效果最佳
OpenAI	GPT-5.4	$2.50	$15.00	内置Provider	通用能力强
Google	Gemini 3 Pro	$2.00	$12.00	内置Provider	多模态、超长上下文
DeepSeek	DeepSeek-V3.2.2/V4	$0.14	$0.28	自定义Provider	极致低价、代码任务
智谱GLM	GLM-5 / GLM-5-Turbo	$0.96/$0.80	$3.20/$2.56	内置（zai）	国产最强代码能力，Turbo版性价比更高
通义千访问	Qwen 3.5 Max	$1.20	$6.00	插件（OAuth）	中文NLP、代码生成
豆包	Seed 2.0 Pro	$0.47	$2.37	自定义Provider	批量处理、低成本
百度文心	文心 5.0	~$0.58	~$1.16	自定义（需适配）	百度云生态用户
Kimi	Kimi K2.5	$0.60	$3.00	自定义Provider	中文Agent、长上下文
MiniMax	MiniMax M2.5	$0.50	$2.00	自定义Provider	SWE-bench高分、性价比
Ollama	Qwen3.5-Coder:32B	免费	免费	自动发布现	隐私敏感、零成本
LM Studio	Devstral-24B	免费	免费	自定义Provider	本地GUI、模型测试

配置核心概念

理解三个关键概念，就能掌握OpenClaw的模型配置：

1. 内置Provider

Anthropic、OpenAI、Google、智谱（zai）等无需额外配置，设置API Key即可使用。

2. 自定义Provider

DeepSeek、豆包、Kimi等需要在 models.providers 中手动添加。

3. Fallback机制

主模型不可用时自动切换到备选，这是最核心的省钱策略。

json

{
  "env": { "API_KEY_NAME": "sk-xxx" },
  "agents": {
    "defaults": {
      "model": {
        "primary": "provider/model-name",     // 主力模型
        "fallbacks": ["provider/model-b"]    // 备选（主模型限速时自动切换）
      }
    }
  },
  "models": {
    "mode": "merge",                       // 保留内置provider，叠加自定义
    "providers": {                         // 自定义provider配置
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "sk-xxx",
        "auth": "api-key",
        "api": "openai-chat"
      }
    }
  }
}

💡 核心建议：
设置 models.mode: "merge" 非常重要。它能保留所有内置Provider的同时叠加你的自定义配置。如果不设置，自定义配置会覆盖内置Provider。

3.4.1 快速配置模型（命令行向导）

🎯 最简单的方式：使用 openclaw onboard 命令启动配置向导，交互式配置模型。

启动配置向导

bash

openclaw onboard

执行后会启动命令行交互式配置向导。

配置步骤

步骤1：选择初始化模式

txt

◇  初始化模式
│  快速开始

选择 "快速开始" 模式。

步骤2：处理现有配置

如果检测到现有配置，会显示：

txt

◇  检测到现有配置 ────────────────────────────╮
│                                             │
│  workspace: ~/clawd                         │
│  model: local-antigravity/gemini-3-pro-low  │
│  gateway.mode: local                        │
│  gateway.port: 18789                        │
│  gateway.bind: lan                          │
│  skills.nodeManager: npm                    │
│                                             │
├─────────────────────────────────────────────╯
◇  配置处理方式
│  使用现有值

选择 "使用现有值" 保留当前配置，或选择 "重新配置" 从头开始。

步骤3：选择模型提供商

txt

◆  模型/认证提供商
│  ○ OpenAI (Codex OAuth + API key)
│  ○ Anthropic
│  ○ MiniMax
│  ○ Moonshot AI
│  ○ Google
│  ○ OpenRouter
│  ○ Qwen
│  ○ Z.AI (GLM 4.7)
│  ○ Copilot
│  ○ Vercel AI Gateway
│  ○ OpenCode Zen
│  ○ Xiaomi
│  ○ Synthetic
│  ○ Venice AI
│  ○ Skip for now

使用 方向键 选择提供商，空格键 确认。

新手推荐的提供商：

Anthropic（Claude，质量最好）
- 价格：中等（$3/百万tokens）
- 能力：推理能力强
- 适合：复杂任务、重要工作
Google（Gemini，免费额度大）
- 价格：免费额度大
- 能力：多模态（支持图片）
- 适合：图片识别、长文档
Moonshot AI（Kimi，超长上下文）
- 价格：低（$0.01/百万tokens）
- 能力：200万字上下文
- 适合：长文档处理

步骤4：输入 API Key

选择提供商后，会提示输入 API Key：

txt

◆  请输入 Anthropic API Key
│  sk-ant-...

如何获取 API Key？

Anthropic (Claude)：访问 Anthropic Console
Google (Gemini)：访问 Google AI Studio
Moonshot (Kimi)：访问 Moonshot Platform
OpenAI：访问 OpenAI Platform

步骤5：选择默认模型

配置完成后，选择默认使用的模型：

txt

◆  选择默认模型
│  ○ claude-3-5-sonnet-20241022
│  ○ claude-3-opus-20240229
│  ● claude-3-haiku-20240307

推荐选择：

日常使用：Claude 3 Haiku（速度快、便宜）
重要任务：Claude 3.5 Sonnet（质量高）
图片识别：Gemini 2.0 Flash（多模态）

步骤6：完成配置

✔ 配置已保存
✔ Gateway 已重启
✔ 模型配置成功

验证配置

配置完成后，测试模型是否可用：

bash

# 查看已配置的模型
openclaw models list

# 测试模型连接
openclaw message send "你好，测试一下"

修改配置

如果需要修改配置，再次运行：

bash

openclaw onboard
可以添加、删除或修改模型提供商。

配置技巧

技巧1：配置多个提供商

可以多次运行 openclaw onboard，每次添加一个提供商，实现多模型配置。

技巧2：跳过向导

如果暂时不想配置，选择 "Skip for now"，稍后再配置。

技巧3：查看配置文件

配置保存在：

bash

~/.openclaw/openclaw.json

可以直接编辑这个文件进行高级配置。

3.4.2 新手推荐配置

推荐1：DeepSeek（性价比之王）

💰 最便宜：比其他模型便宜70%
💻 编程强：代码能力出色
🎯 够用：日常任务完全够用

推荐2：Claude Haiku 4.5（快速稳定）

⚡ 最快：响应速度快
🎯 可靠：质量稳定
💰 便宜：成本低

快速切换模型

bash

# 切换到 DeepSeek
openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"

# 切换到 Claude Haiku
openclaw config set agents.defaults.model.primary "maynor/claude-haiku-4-5-20251001"

# 重启生效
openclaw gateway restart

📚 想了解更多？
详细的模型对比、多模型切换策略、参考 [第1参考第10章节：高级配置。

3.5 Gateway 网关配置（进阶）

💡 什么时候需要配置 Gateway？

想要限制访问权限（只允许特定用户）

需要配置群组提及规则

想要自定义网关行为

Gateway 配置文件位置

配置文件位于：~/.openclaw/openclaw.json

基础配置说明

如果你不做任何修改，OpenClaw 将：

使用内置的 Pi 二进制文件以 RPC 模式运行
按发布送者创建独立会话
接受所有用户的消息

访问控制配置

限制 WhatsApp 访问

json

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123", "+8613800138000"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

说明：

allowFrom：只允许这些号码访问
requireMention：群组中需要 @ 提及才会响应

配置提及规则

json

{
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw", "@小龙虾", "@助手"]
    }
  }
}

说明：

群组中使用这些关键词可以触发布响应
支持多个提及模式

远程访问配置

使用 Tailscale 远程访问

如果你想在外网访问 Gateway：

安装 Tailscale：

bash

# macOS
brew install tailscale

# Linux
curl -fsSL https://tailscale.com/install.sh | sh

启动 Tailscale：
bash
```
sudo tailscale up
```
获取 Tailscale IP：
bash
```
tailscale ip -4
```
通过 Tailscale IP 访问：
txt
```
http://你的Tailscale-IP:18789/
```

优势：

✅ 安全的点对点连接
✅ 无需公网 IP
✅ 无需配置防火墙
✅ 支持多设备访问

完整配置示例

json

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+8613800138000"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw", "@助手"]
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "sk-你的密钥",
        "auth": "api-key",
        "api": "openai-chat"
      }
    }
  }
}

配置生效

修改配置后，重启 Gateway：

bash

openclaw gateway restart

常见配置场景

场景1：家庭使用

json

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+8613800138000", "+8613800138001"]
    }
  }
}

场景2：团队使用

json

{
  "channels": {
    "whatsapp": {
      "groups": {
        "工作群": {
          "requireMention": true,
          "mentionPatterns": ["@openclaw"]
        },
        "家庭群": {
          "requireMention": false
        }
      }
    }
  }
}

场景3：公开服务

json

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["*"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

本章节小结

通过本章节，你应该已经：

✅ 完成了第一次对话
✅ 学会了基本命令使用
✅ 配置了个性化的人设
✅ 了解了如何选择合适的模型

关键要点：

提访问要明确具体
人设让AI更符合你的需求
根据场景选择合适的模型
成本和性能需要平衡

实战练习

练习1：配置你的第一个AI助手

给AI起个名字
设定性格和风格
选择合适的模型
发布送10条测试消息

练习2：尝试不同的命令

搜索文件
创建日历事件
保存网页到备忘附录
截图

练习3：对比不同模型

用Haiku处理简单任务
用Sonnet处理复杂任务
对比响应速度和质量
记附录Token消耗

下一章节：第4章节：本地文件管理 - 让OpenClaw成为你的文件管理神器

返回目附录：README

🌐 在线阅读

📖 想在线阅读此章节节？

🔗 在线阅读此章节节

访问网站获取更好的阅读体验：

📱 响应式设计，支持手机、平板、电脑
支持黑暗模式，保护眼睛
🔍 内置搜索功能，快速定位内内容
📋 目附录导航，轻松跳转章节节

🏠 访问完整教网站

02 Core Features 04 File Management (`docs/02-core-features/04-file-management.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第4章节：本地文件管理

OpenClaw最强大的功能之一，就是可以访问和管理你电脑上的文件。这是在线AI无法做到的。

快速导航

🔍 智能文件搜索
📦 批量文件处理
📁 文件自动整理
🧹 硬盘清理优化

4.1 智能文件搜索

为什么需要智能搜索？

传统的文件搜索只能按文件名查找，但经常遇到：

❌ 忘记文件名，只记得内内容
❌ 文件太多，不知道在哪个文件夹
❌ 需要同时搜索多种类型的文件
❌ 需要根据内内容筛选文件

OpenClaw的智能搜索可以：

✅ 根据文件内内容搜索
✅ 理解自然语言描述
✅ 跨文件夹搜索
✅ 智能过滤和排序

场景1：找文件

真实案例：找发布票

我电脑里有一堆发布票，特别乱，我忘了哪一张是买跑步机的了。
按过去，我得一张一张点开来搜索。真的，这事太呆逼了。

传统方法：

打开文件夹
一张一张点开图片
查看内内容
找到目标文件
耗时：10-30分钟

OpenClaw方法：

我：帮我找一下我电脑上的一张发布票，里面详情是买了一个跑步机，
然后把那个发布票用文件发布给我。

OpenClaw执行过程：

🔍 搜索所有图片文件
📄 使用OCR识别文字
🎯 匹配"跑步机"关键词
📤 发布送找到的文件

结果：

⏱️ 耗时：30-60秒
✅ 准确率：100%
😊 体验：太爽了！

搜索命令示例

按内内容搜索

找一下包含"合同"的PDF文件
搜索所有提到"项目计划"的文档
找一下我写的关于AI的笔记

按类型搜索

找出所有的PNG图片
搜索最近下载的PDF文件
找一下所有的Excel表格

按时间搜索

找一下最近7天修改的文件
搜索上个月创建的文档
找一下今天下载的文件

按大小搜索

找出大于100MB的文件
搜索所有小于1MB的图片
找一下占用空间最大的10个文件

组合搜索

找一下最近一周内，包含"发布票"的图片文件
搜索下载文件夹里，大于10MB的PDF
找一下桌面上，今天修改过的Word文档

搜索技巧

技巧1：描述内内容而非文件名

❌ 不好的搜索：
找一下IMG_1234.jpg
✅ 好的搜索：
找一下我去年在海边拍的照片

技巧2：提供上下文

❌ 不好的搜索：
找发布票
✅ 好的搜索：
找一下我上个月买跑步机的发布票，应该是在下载文件夹里

技巧3：指定搜索范围

❌ 不好的搜索：
找所有文件
✅ 好的搜索：
在文档文件夹里找所有的PDF文件

技巧4：使用排序

❌ 不好的搜索：
找图片
✅ 好的搜索：
找最近修改的10张图片，按时间排序

实战练习

练习1：找照片
帮我找一下我电脑上所有的自拍照片
练习2：找文档
找一下包含"年度总结"的Word文档
练习3：找下载文件
找一下我最近下载的所有PDF文件

4.2 批量文件处理

场景2：整理发布票报销

真实案例：自动填写报销单

公司财务有个非常严格的规定，就是发布票需要填写在1个excel模板上，
然后把发布票和这个excel文件一起提交给财务。

以前，虽然都不会笨到用手填，但还是要把所有发布票都传到ChatGPT
或者别的AI产品上，然后让他们来帮忙填写。

传统方法：

打开ChatGPT
上传发布票图片（一张一张）
让AI提取信息
复制到Excel
重复N次
耗时：30-60分钟

OpenClaw方法：

我：我希望你帮我把我本地那个1月发布票文件夹里的所有发布票都整理一下，
按照那个下载文件里报销单.xlsx的模板格式填进去，
再把填好的表格用文件发布送给我。

OpenClaw执行过程：

📁 读取发布票文件夹
🔍 识别所有发布票图片
📄 OCR提取信息（日期、金额、商家等）
📊 读取Excel模板
✍️ 按模板格式填写
💾 保存新文件
📤 发布送给你

结果：

⏱️ 耗时：2-5分钟
✅ 准确率：95%+
😊 体验：直接搞定！

批量处理命令示例

批量读取

读取文档文件夹里所有的PDF文件
提取所有图片中的文字
读取所有Excel表格的第一行

批量提取信息

从所有发布票中提取日期、金额、商家信息
从所有简历中提取姓名、电话、邮箱
从所有合同中提取甲方、乙方、金额

批量格式转换

把所有Word文档转换成PDF
把所有PNG图片转换成JPG
把所有Excel表格导出为CSV

批量数据整理

把所有发布票信息整理到一个Excel表格
把所有联系人信息整理成通讯附录
把所有会议记附录整理成一份总结

实战案例

案例1：整理客户信息

场景：

有100份客户资料（Word文档）
需要提取：公司名、联系人、电话、邮箱
整理到Excel表格

命令：
帮我从"客户资料"文件夹里的所有Word文档中，
提取公司名、联系人、电话、邮箱，
整理到一个Excel表格里，
按公司名排序。
结果：

自动提取100份资料
生成规范的Excel表格
耗时：5-10分钟

案例2：批量提取PDF内内容

场景：

有50份PDF报告
需要提取每份报告的摘要
整理成一份汇总文档

命令：
读取"报告"文件夹里所有的PDF文件，
提取每份报告的摘要部分（通常在第一页），
整理成一份Word文档，
每个摘要标注来源文件名。
结果：

自动读取50份PDF
提取摘要内内容
生成汇总文档

案例3：批量图片识别

场景：

有200张名片照片
需要提取联系信息
整理成通讯附录

命令：
识别"名片"文件夹里所有图片，
提取姓名、公司、职位、电话、邮箱，
整理成Excel通讯附录，
按公司分类。
结果：

OCR识别200张名片
自动分类整理
生成标准通讯附录

错误处理和内容错

处理识别错误

我：帮我检查一下刚才生成的Excel表格，
看看有没有识别错误的地方，
比如电话号码格式不对、金额异常等。

处理缺失信息

我：有些发布票可能信息不全，
如果缺少必填项，请单独列出来，
我手动补充。

处理格式访问题

我：如果遇到无法识别的文件格式，
请跳过并告诉我，
我会手动处理。

4.3 文件自动整理

场景3：批量重命名文件

真实案例：邀请函重命名

设计同学给我做了一些邀请函，是微信发布我的，然后我存下来的。
存完了以后，发布现一个BUG。
名字全特么是微信文件XXX。
太BUG了，我根本不知道谁是谁的。

传统方法：

打开每张图片
看内内容
手动重命名
重复N次
耗时：20-30分钟

OpenClaw方法：

我：让OpenClaw根据我邀请函里面对应的人名，
把外面的名字改成"人名-邀请函.jpg"的格式。

OpenClaw执行过程：

📁 读取所有图片
🔍 OCR识别人名
✍️ 生成新文件名
📝 批量重命名
✅ 完成

结果：

⏱️ 耗时：1-2分钟
✅ 准确率：100%
😊 体验：一句话搞定！

文件整理命令示例

批量重命名

把所有图片按拍摄日期重命名，格式：YYYY-MM-DD_序号.jpg
把所有文档按内内容主题重命名
把所有下载文件按类型重命名

文件分类

把桌面上的文件按类型分类到不同文件夹
把下载文件夹里的文件按日期分类
把照片按拍摄地点分类

文件夹结构优化

帮我整理一下项目文件夹，按功能模块分类
优化我的文档文件夹结构，让它更清晰
把所有散乱的文件整理到合适的文件夹

实战案例

案例1：整理下载文件夹

场景：

下载文件夹有500+文件
各种类型混在一起
需要分类整理

命令：
帮我整理下载文件夹：

按文件类型分类（文档、图片、视频、压缩包等）
每个类型创建一个子文件夹
把文件移动到对应文件夹
删除重复文件
告诉我整理结果
结果：
✅ 整理完成！

📊 统计：

文档：120个 → Documents/
图片：200个 → Images/
视频：50个 → Videos/
压缩包：30个 → Archives/
其他：100个 → Others/

🗑️ 删除重复文件：15个
💾 释放空间：2.3GB

案例2：照片自动分类

场景：

有1000+张照片
需要按日期和地点分类
方便查找

命令：
帮我整理照片文件夹：

按拍摄日期创建文件夹（YYYY-MM格式）
如果照片有地理位置信息，在文件名中标注
删除模糊和重复的照片
生成一个索引文件
结果：
✅ 整理完成！

📁 文件夹结构：
Photos/
├── 2025-12/
│ ├── 2025-12-01_北京_001.jpg
│ ├── 2025-12-01_北京_002.jpg
│ └── ...
├── 2026-01/
│ ├── 2026-01-15_上海_001.jpg
│ └── ...
└── index.txt (索引文件)

🗑️ 删除模糊照片：50张
🗑️ 删除重复照片：30张

案例3：文档归档

场景：

项目结束，需要归档
文档散落在各处
需要统一整理

命令：
帮我归档"XX项目"的所有文档：

搜索所有相关文档（包含项目名称）
按文档类型分类（需求、设计、代码、测试等）
创建归档文件夹结构
移动文件到对应位置
生成项目文档清单
结果：
✅ 归档完成！

📁 文件夹结构：
XX项目_归档_2026-02-10/
├── 01_需求文档/
├── 02_设计文档/
├── 03_开发布文档/
├── 04_测试文档/
├── 05_部署文档/
└── 文档清单.xlsx

📊 统计：

总文件数：156个
总大小：1.2GB

自动化脚本编写

如果你经常需要整理某类文件，可以让OpenClaw生成自动化脚本：

我：帮我写1个脚本，每周自动整理下载文件夹，
按照刚才的规则分类。
OpenClaw会生成一个可以定时运行的脚本，实现自动化整理。

4.4 硬盘清理优化

场景4：清理硬盘垃圾

真实案例：释放硬盘空间

如果你硬盘快满了，你也别下那些扫描清垃圾的软件了。
直接让OpenClaw给你过一遍。

传统方法：

下载清理软件
扫描硬盘
手动选择删除
担心误删重要文件
耗时：30-60分钟

OpenClaw方法：

我：帮我分析一下硬盘空间使用情况，
找出占用空间最大的文件和文件夹，
建议哪些可以清理。
OpenClaw执行过程：

📊 扫描硬盘
📈 分析空间占用
🔍 找出大文件
🗑️ 识别垃圾文件
💡 提供清理建议

清理命令示例

查找大文件

找出占用空间最大的10个文件
查找大于1GB的文件
分析哪个文件夹占用空间最多

查找重复文件

找出所有重复的文件
查找重复的照片
找出重复的文档

查找临时文件

找出所有临时文件
查找缓存文件
找出可以安全删除的文件

清理建议

分析我的硬盘，给出清理建议
哪些文件可以移动到外部硬盘
哪些文件可以压缩存储

实战案例：释放100GB空间

第一步：分析空间占用

我：帮我分析一下硬盘空间使用情况
OpenClaw回复：
📊 硬盘空间分析：

总内容量：500GB
已使用：450GB (90%)
剩余：50GB (10%)

⚠️ 空间不足警告！

占用空间最多的文件夹：

~/Library/Caches - 80GB
~/Downloads - 50GB
~/Movies - 120GB
~/Documents - 100GB
~/Desktop - 30GB
第二步：查找大文件

我：找出大于1GB的文件
OpenClaw回复：
🔍 找到35个大于1GB的文件：

视频文件（25个）：

项目演示.mov - 15GB
会议附录像_2025-12.mp4 - 8GB
...

虚拟机镜像（5个）：

Windows.vmdk - 50GB
Ubuntu.vmdk - 30GB
...

备份文件（5个）：

iPhone备份_2025-12.backup - 20GB
...

💡 建议：

视频文件可以压缩或移动到外部硬盘
旧的虚拟机镜像可以删除
旧的备份文件可以删除
第三步：查找重复文件

我：找出所有重复的文件
OpenClaw回复：
🔍 找到120组重复文件：

重复照片（80组）：

IMG_1234.jpg (3份) - 15MB
IMG_5678.jpg (2份) - 10MB
...

重复文档（30组）：

报告_v1.docx (4份) - 5MB
方案_final.pptx (3份) - 20MB
...

重复下载（10组）：

setup.exe (2份) - 100MB
...

💡 可释放空间：约8GB
第四步：清理临时文件

我：找出所有可以安全删除的临时文件和缓存
OpenClaw回复：
🗑️ 可安全删除的文件：

系统缓存：

~/Library/Caches - 80GB
- Safari缓存 - 20GB
- Chrome缓存 - 30GB
- 其他应用缓存 - 30GB

临时文件：

/tmp - 5GB
~/Downloads/临时文件 - 10GB

日志文件件：

~/Library/Logs - 3GB

💡 可释放空间：约98GB

⚠️ 建议：

系统缓存可以全部清理
临时文件可以全部删除
日志文件件保留最近1个月的
第五步：执行清理

我：好的，帮我清理这些文件，
但是要先备份重要的，
然后再删除。
OpenClaw回复：
✅ 清理完成！

📊 清理结果：

删除缓存文件：80GB
删除临时文件：15GB
删除重复文件：8GB
删除旧备份：20GB

💾 总共释放空间：123GB

📁 备份位置：

重要文件已备份到：~/Backup/清理前备份_2026-02-10/

⚠️ 建议：

定期清理缓存（每月一次）
及时删除不需要的下载文件
使用外部硬盘存储大文件

安全删除策略

三步确认法

第一步：分析
text
```
分析哪些文件可以删除
```
第二步：备份
text
```
把重要文件备份到安全位置
```
第三步：删除
text
```
确认无误后，删除文件
```

保护重要文件

我：在清理之前，请确保以下文件夹不被删除：

~/Documents/重要文档
~/Projects
~/Photos

可恢复删除

我：先把文件移动到回收站，
而不是直接删除，
这样如果误删了还能恢复。

定期清理计划

让OpenClaw帮你制定定期清理计划：

我：帮我制定一个定期清理计划，
每周自动清理缓存和临时文件，
每月检查大文件和重复文件。
OpenClaw回复：
✅ 已创建定期清理计划：

📅 每周任务（每周日晚上10点）：

清理系统缓存
清理浏览器缓存
清理临时文件
清理下载文件夹（超过30天的文件）

📅 每月任务（每月1号）：

查找大文件（>1GB）
查找重复文件
分析空间占用
生成清理报告

💡 预计每月可释放：20-30GB

⚠️ 重要提醒：

清理前会自动备份
清理后会发布送通知
可以随时取消任务

本章节小结

通过本章节，你应该已经掌握了：

✅ 智能文件搜索：根据内内容找文件，不再依赖文件名
✅ 批量文件处理：一次处理100+文件，自动提取信息
✅ 文件自动整理：智能分类、重命名、归档
✅ 硬盘清理优化：找出垃圾文件，释放大量空间

关键要点：

OpenClaw可以访问本地文件，这是在线AI做不到的
描述内内容而非文件名，让AI理解你的需求
批量处理节省大量时间
定期清理保支持硬盘健康

实战项目：打造你的文件管理助手

项目目标

创建一个完整的文件管理工作流，包括：

每天自动整理下载文件夹
每周清理缓存和临时文件
每月检查大文件和重复文件
重要文件自动备份

实施步骤

第一步：设置自动整理
帮我设置每天晚上10点自动整理下载文件夹，
按文件类型分类。
第二步：设置定期清理
设置每周日晚上11点清理缓存和临时文件。
第三步：设置月度检查
设置每月1号检查大文件和重复文件，
生成清理报告。
第四步：设置自动备份
设置每天自动备份重要文件夹到外部硬盘。

预期效果

📁 下载文件夹始终保支持整洁
💾 硬盘空间充足（至少保支持20%空闲）
🔒 重要文件有备份
⏱️ 每月节省5-10小时整理时间

下一章节：第5章节：知识库管理 - 打造个人知识库系统

返回目附录：README

🌐 在线阅读

📖 想在线阅读此章节节？

🔗 在线阅读此章节节

访问网站获取更好的阅读体验：

📱 响应式设计，支持手机、平板、电脑
支持黑暗模式，保护眼睛
🔍 内置搜索功能，快速定位内内容
📋 目附录导航，轻松跳转章节节

🏠 访问完整教网站

02 Core Features 05 Knowledge Management (`docs/02-core-features/05-knowledge-management.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第5章节知识库与第二大脑（Active Memory / Memory Wiki / 研究归档）

本章目标：用 OpenClaw 当前官方主线，把“知识库”这件事讲清楚：什么交给 Active Memory，什么交给 Memory Wiki，什么只是临时资料，不要再把旧的第三方同步 Skill 当默认方案。

版本基线

当前稳定版：v2026.9.3（2026-09-08 发布）
本章默认按 v2026.9.3 稳定版写

先给小白的阅读说明

这一章到底解决什么问题

很多人一提“知识库”，脑子里想到的是：

把网页存进 Notion
把笔记同步到 Obsidian
做一堆目录和标签

这些不是没用，但它们已经不是 OpenClaw 当前的主线。现在更推荐你把知识系统拆成 3 层：

Active Memory：回复前先回忆相关上下文
Memory Wiki：把长期知识整理成结构化、可检索的知识层
临时资料处理：网页抓取、会议纪要、研究摘录，先整理再决定要不要进入长期知识层

如果你只想先跑通，先看这几节

想让 OpenClaw 更“记得住你”：看 5.2
想开始搭第二大脑：看 5.3
想做文章、项目、论文资料沉淀：看 5.4
你已经在用 Obsidian：看 5.5

小白最容易犯的 3 个错

一上来就先折腾同步，而不是先把记忆主线配通
把“临时资料”直接塞进长期知识库，最后越存越乱
以为所有知识都必须结构化，结果迟迟不开始

本章一句话结论

先让 OpenClaw 能记得住，再让它能查得到，最后才考虑它要不要同步到别的笔记工具。

5.1 2026.4 之后，知识库的正确主线是什么？

旧版教程里，“知识库”主要靠网页归档、Notion 同步、Obsidian 同步来实现。但在当前官方主线里，更重要的是下面这套组合：

层级	负责什么	适合什么场景
`Active Memory`	回复前先回忆相关偏好、事实、上下文	聊天、长期协作、偏好记忆
`Memory Wiki`	把长期知识编译成结构化知识层	项目知识、研究资料、长期主题沉淀
`openclaw infer web fetch/search`	收集外部资料	网页、文档、新闻、调研资料
`wiki ingest / compile / search / get`	资料入库、整理、检索	第二大脑、团队知识、项目档案

你可以这样理解：

Active Memory 解决的是“回复时能不能想起来”
Memory Wiki 解决的是“长期资料能不能整理好、查得准”
网页抓取 / 转写 / 摘要 解决的是“怎么把外部信息先拿进来”

5.2 Active Memory：先让 OpenClaw 记得住你

官方文档对 Active Memory 的定义很明确：它是一个在主回复之前运行的阻塞式记忆子代理。它会在合适的会话里先用 memory_search、memory_get 找相关记忆，再把精简结果交给主回复。

5.2.1 什么时候该开

适合直接开启的情况：

你经常和同一个 agent 长期协作
你希望它记住你的习惯、偏好、工作背景
你希望它少问重复问题

先不要急着开的情况：

你只是偶尔临时问几句
你现在主要在排查模型/认证问题
你对延迟非常敏感，想先把基础链路跑通

5.2.2 官方推荐起步配置

根据官方文档，最安全的起步方式是：启用插件、只绑定一个对话 agent、只先在 direct chat 里使用。

把下面这段写到 openclaw.json：

json5

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          allowedChatTypes: ["direct"],
          modelFallback: "google/gemini-3-flash",
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          persistTranscripts: false,
          logging: true
        }
      }
    }
  }
}

改完以后，重启你当前使用的 Gateway 进程或服务。

5.2.3 看到什么算 Active Memory 已经跑通

你可以先用最简单的方式判断：

同一个对话里，OpenClaw 开始更稳定地记住你的偏好和背景
开启 /verbose 或 /trace 时，能看到 Active Memory 的状态信息
没有明显的模型报错、超时报错或空转

5.2.4 小白怎么理解这些配置项

agents: ["main"]：只让 main 这个 agent 用主动记忆
allowedChatTypes: ["direct"]：先只在私聊/直接对话里使用，避免一上来全局打开
queryMode: "recent"：优先看最近上下文，速度和效果更平衡
promptStyle: "balanced"：默认是稳妥模式，适合大多数用户
timeoutMs: 15000：超过 15 秒就放弃，避免拖慢回复太多

如果你是第一次用，不建议一开始就改得太激进。默认先跑稳，再谈优化。

5.3 Memory Wiki：把长期知识整理成“能查、能证据回溯”的知识层

官方对 memory-wiki 的定位不是普通笔记插件，而是一个把 durable memory 编译成知识 vault 的 bundled plugin。

它和 Active Memory 的关系是：

Active Memory 负责“回复时先想起来”
Memory Wiki 负责“把长期知识整理成稳定页面、claims、evidence、dashboards”

5.3.1 为什么它比“随手记笔记”更适合长期知识

Memory Wiki 的优势不只是“能存”，而是：

有专门的 wiki vault
支持结构化 claim / evidence
能编译出稳定页面和 digest
能用 wiki_search / wiki_get 精准检索
可以和活动记忆层做 shared search

这更像一个“知识层”，而不是一个“笔记堆”。

5.3.2 官方推荐起步配置

官方文档建议把配置放到 plugins.entries.memory-wiki.config。下面这份是比较适合新手的起步版本：

json5

{
  plugins: {
    entries: {
      "memory-wiki": {
        enabled: true,
        config: {
          vaultMode: "isolated",
          vault: {
            path: "~/.openclaw/wiki/main",
            renderMode: "obsidian"
          },
          obsidian: {
            enabled: true,
            useOfficialCli: true,
            vaultName: "OpenClaw Wiki",
            openAfterWrites: false
          },
          bridge: {
            enabled: false,
            readMemoryArtifacts: true,
            indexDreamReports: true,
            indexDailyNotes: true,
            indexMemoryRoot: true,
            followMemoryEvents: true
          },
          ingest: {
            autoCompile: true,
            maxConcurrentJobs: 1,
            allowUrlIngest: true
          },
          search: {
            backend: "shared",
            corpus: "wiki"
          },
          context: {
            includeCompiledDigestPrompt: false
          },
          render: {
            preserveHumanBlocks: true,
            createBacklinks: true,
            createDashboards: true
          }
        }
      }
    }
  }
}

5.3.3 小白先记住 4 个关键开关就够了

vaultMode: "isolated"：最适合刚开始，先把 wiki 当独立知识层
renderMode: "obsidian"：如果你已经在用 Obsidian，会比较顺手
search.backend: "shared"：需要时可以和共享记忆检索打通
createDashboards: true：让 wiki 自动生成更容易浏览的汇总页

5.3.4 什么时候用 `bridge` 模式

只有在你已经明确知道：

自己的 active memory backend 已经有公开 bridge artifacts
想把记忆层里的长期资料编译进 wiki

这时再考虑 bridge。如果你现在只是第一次上手，先用 isolated。

5.4 最适合小白先跑通的知识库流程

这一节不讲大而全的系统，只讲最短闭环。

5.4.1 流程 A：把一份本地笔记收进 Wiki

先初始化：

bash

openclaw wiki init
openclaw wiki status

然后准备一份最简单的 Markdown 笔记，例如 ./notes/customer-onboarding.md：

# Customer Onboarding

## 现状
- 新用户第一次接触产品时，最容易卡在权限配置
- 现有帮助文档太散，入口不统一

## 我的判断
- 应该做一份统一 onboarding checklist
- 首屏应该先给 3 个最常见动作

把它导入 Wiki：

bash

openclaw wiki ingest ./notes/customer-onboarding.md
openclaw wiki compile
openclaw wiki lint

搜索并读取：

bash

openclaw wiki search "onboarding"
openclaw wiki get <lookup>

5.4.2 看到什么算 Wiki 已经跑通

至少满足下面 4 条：

openclaw wiki status 能看到 vault 状态正常
openclaw wiki ingest 能成功吃进你的文件
openclaw wiki compile 没有报结构错误
openclaw wiki search 能搜到你刚导入的主题

5.4.3 流程 B：把网页资料变成长期知识

更推荐的顺序不是“直接同步到第三方笔记工具”，而是：

先抓网页资料
让 OpenClaw 摘要成你自己的笔记
再决定是否进入 Wiki

先抓取网页：

bash

openclaw infer web search --query "OpenClaw Active Memory use cases" --json
openclaw infer web fetch --url https://docs.openclaw.ai/concepts/active-memory --json

然后你可以让 OpenClaw 帮你整理成一份 Markdown 摘要，再保存到 ./notes/，最后继续：

bash

openclaw wiki ingest ./notes/active-memory-summary.md
openclaw wiki compile

5.4.4 流程 C：项目知识沉淀

项目知识最适合进 Wiki 的内容是：

架构决策
常见故障排查
客户/用户共性问题
术语解释
上线复盘

不适合一股脑塞进去的内容是：

一次性的临时聊天记录
未经整理的超长日志
还没确认真假的外部信息

最好的习惯是：先整理，再入库。

5.5 如果你已经在用 Obsidian，应该怎么理解它和 Wiki 的关系

这一章不再把 Obsidian 当成默认主线，而把它放回它更适合的位置：展示层 / 编辑层。

更推荐的关系是

OpenClaw 负责记忆、编译、检索
Wiki 负责知识结构
Obsidian 负责你的人类阅读和手工编辑体验

如果你已经在用 Obsidian，可以重点关注这些命令：

bash

openclaw wiki obsidian status
openclaw wiki obsidian search "onboarding"
openclaw wiki obsidian open syntheses/alpha-summary.md
openclaw wiki obsidian daily

不再推荐当默认主线的旧写法

下面这些旧路线，现在不再建议当成入门默认方案：

clawhub install notion-sync
clawhub install obsidian-sync
先装同步 Skill，再把第三方笔记工具当记忆主系统

它们不是完全不能做，而是更适合作为你已经有现成工作流时的补充集成，而不是当前官方知识主线。

5.6 本章最容易踩的坑

坑 1：把所有资料都当长期知识

不是所有东西都值得进 Wiki。一个很实用的判断标准是：

这条信息以后还会反复被用到吗？
它是否已经整理到足够清楚？
它是否值得被检索、引用和复盘？

坑 2：一上来就开太多模式

新手建议顺序：

先开 Active Memory
再初始化 Wiki
先用 isolated 模式
跑通后再考虑 bridge

坑 3：把同步当成目标，把知识本身忘了

Notion、Obsidian、备忘录都只是载体。真正该优先解决的，是：

OpenClaw 能不能想起来
资料能不能查得到
结论有没有证据来源

5.7 给小白的最短落地顺序

如果你今天只想花 30 分钟先把“知识库”跑起来，按这个顺序做：

打开 Active Memory
初始化 Memory Wiki
写一份自己的本地 Markdown 笔记
wiki ingest + wiki compile
wiki search 看能不能搜到
再决定要不要接 Obsidian

5.8 官方参考

Active Memory：https://docs.openclaw.ai/concepts/active-memory
Memory Wiki：https://docs.openclaw.ai/plugins/memory-wiki
Wiki CLI：https://docs.openclaw.ai/cli/wiki
Inference CLI：https://docs.openclaw.ai/cli/infer

02 Core Features 06 Schedule Management (`docs/02-core-features/06-schedule-management.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第6章节日程与任务管理

💡 本章节目标：学会使用 OpenClaw管理日程和任务，实现日历自动创建、微信截图识别、批量日程导入和智能提醒设置。

📅 本章节内内容

6.1 日历自动创建
6.2 微信截图识别
6.3 批量日程导入
6.4 提醒设置技巧

6.1 日历自动创建

6.1.1 为什么需要日历自动创建

在日常工作中，经常遇到这些场景：

📱 微信聊天中约定会议时间
📧 邮件中收到活动邀请
💬 群聊中讨论项目deadline
📝 文档中记附录的重要日期

传统做法：

记住时间地点
打开日历App
手动创建事件
设置提醒

访问题：

❌ 内容易遗忘
❌ 操作繁琐
❌ 信息内容易丢失
❌ 效率低下

OpenClaw可以自动识别并创建日历事件！

6.1.2 核心原理

OpenClaw的日历管理基于Mac日历Skills：

文本/截图 → OpenClaw识别 → 提取信息 → 创建日历事件 → 同步到iPhone

关键能力：

智能识别：自动识别时间、地点、人物
自动创建：一键创建日历事件
跨设备同步：Mac日历自动同步到iPhone
智能提醒：自动设置合理的提醒时间

6.1.3 实战案例1：文本创建日历

场景：你在微信上约了一个会议。

微信聊天内内容：
张三：明天下午3点，在会议室A讨论项目方案，记得带笔记本

OpenClaw操作：

你：帮我创建一个日历事件：
明天下午3点，在会议室A讨论项目方案

OpenClaw：好的，我来帮你创建日历事件。

[分析中...]

OpenClaw：已创建日历事件！

📅 事件详情：

标题：讨论项目方案
时间：2026-02-11 15:00-16:00
地点：会议室A
参与人：张三
备注：记得带笔记本

提醒设置：

提前15分钟提醒
提前1小时提醒

已同步到：

Mac日历 ✅
iPhone日历 ✅

查看效果：

打开Mac日历，你会看到：

2026年2月11日星期二

15:00-16:00 讨论项目方案
📍 会议室A
👤 张三
📝 记得带笔记本

text

🔔 提前15分钟提醒
         🔔 提前1小时提醒

打开iPhone日历，自动同步显示相同内内容。

6.1.4 实战案例2：复杂日程创建

场景：你收到一封会议邀请邮件。

邮件内内容：
主题：2026年Q1产品规划会议

时间：2026年2月15日（周五）14:00-17:00
地点：总部大楼3楼会议室
参会人员：产品团队全体成员
会议议程：

Q1产品回顾（30分钟）
Q2产品规划（60分钟）
资源分配讨论（60分钟）
总结与行动项（30分钟）

请提前准备：

Q1产品数据报告
Q2产品规划草案
资源需求清单

OpenClaw操作：

你：帮我根据这封邮件创建日历事件
[粘贴邮件内内容]

OpenClaw：正在分析邮件内内容...

[分析完成]

OpenClaw：已创建详细日历事件！

📅 事件详情：

标题：2026年Q1产品规划会议
时间：2026-02-15 14:00-17:00（3小时）
地点：总部大楼3楼会议室
参与人：产品团队全体成员

会议议程：

14:00-14:30 Q1产品回顾
14:30-15:30 Q2产品规划
15:30-16:30 资源分配讨论
16:30-17:00 总结与行动项

准备事项：
✓ Q1产品数据报告
✓ Q2产品规划草案
✓ 资源需求清单

提醒设置：

提前1天提醒（准备材料）
提前2小时提醒（检查准备）
提前30分钟提醒（前往会议室）

已同步到Mac和iPhone日历 ✅

6.1.5 实战案例3：周期性事件

场景：你需要设置每周例会。

OpenClaw操作：

你：帮我创建一个周期性日历事件：
每周一上午10点，团队周会，支持续1小时，会议室B

OpenClaw：已创建周期性事件！

📅 事件详情：

标题：团队周会
时间：每周一 10:00-11:00
地点：会议室B
重复：每周
结束：无限期（或指定结束日期）

提醒设置：

提前15分钟提醒

已创建未来12周的事件：

2026-02-10（周一）10:00
2026-02-17（周一）10:00
2026-02-24（周一）10:00
... （共12次）

已同步到Mac和iPhone日历 ✅

6.1.6 日历模板和最佳实践

常用日历模板：

模板1：会议事件
标题：[会议主题]
时间：[日期] [开始时间]-[结束时间]
地点：[会议室/线上链接]
参与人：[参会人员]
议程：[会议议程]
准备：[需要准备的材料]
提醒：提前1天、提前1小时、提前15分钟

模板2：项目deadline
标题：[项目名称] - Deadline
时间：[截止日期] 全天
优先级：高
提醒：提前1周、提前3天、提前1天、当天早上
备注：[交付物清单]

模板3：个人事项
标题：[事项名称]
时间：[日期] [时间]
地点：[地点]
提醒：提前30分钟
备注：[相关信息]

最佳实践：

统一命名规范
会议：[会议] 项目讨论
任务：[任务] 完成报告
活动：[活动] 团建
学习：[学习] 技术分分享
合理设置提醒
重要会议：提前1天、1小时、15分钟
普通会议：提前1小时、15分钟
deadline：提前1周、3天、1天
个人事项：提前30分钟
添加详细信息

会议链接（线上会议）
会议室位置（线下会议）
参会人员联系方式
准备材料清单
相关文档链接

使用颜色分类
红色：紧急重要
橙色：重要不紧急
黄色：紧急不重要
绿色：个人事项
蓝色：学习成长

6.2 微信截图识别

6.2.1 为什么需要截图识别

真实场景：

你在微信上收到这样的消息：

张三：明天下午2点，在星巴克（国贸店）见面讨论新项目的事，
记得带上你的方案，我请你喝咖啡😊

传统做法：

看到消息
记住时间地点
打开日历
手动输入信息
设置提醒

访问题：

❌ 步骤繁琐（5步）
❌ 内容易遗忘
❌ 信息可能记错
❌ 效率低下

OpenClaw做法：

截图发布给OpenClaw
完成！

6.2.2 核心原理

OpenClaw的截图识别流程：

微信截图 → OCR文字识别 → NLP信息提取 → 创建日历事件

关键技术：

OCR识别：提取截图中的文字
时间解析：识别"明天下午2点"等自然语言
地点提取：识别"星巴克（国贸店）"
人物识别：识别"张三"
事项提取：识别"聊新项目"

6.2.3 实战案例1：简单约会

微信截图内内容：
李四：后天晚上7点，老地方吃饭？
你：好的！

OpenClaw操作：

你：[发布送微信截图]
帮我创建日历事件

OpenClaw：正在识别截图内内容...

[OCR识别完成]

OpenClaw：已识别到约会信息！

📅 事件详情：

标题：和李四吃饭
时间：2026-02-12 19:00-20:30
地点：老地方（需要你确认具体地址）
参与人：李四

提醒设置：

提前2小时提醒

已创建日历事件 ✅

💡 提示：如果"老地方"有具体地址，
可以告诉我，我帮你更新到日历中。

补充地址：
你：老地方是"海底捞（三里屯店）"

OpenClaw：已更新地址！

📍 地点：海底捞（三里屯店）
📍 地址：北京市朝阳区三里屯路19号

已同步到日历 ✅

6.2.4 实战案例2：复杂会议安排

微信群聊截图：
项目经理：@全体成员
下周三上午9:30，在公司5楼大会议室开项目启动会
请务必参加，会议预计2小时
需要准备：

项目需求文档
技术方案
时间排期

会后会有工作午餐

OpenClaw操作：

你：[发布送群聊截图]
帮我创建日历事件

OpenClaw：正在识别群聊内内容...

[识别完成]

OpenClaw：已识别到会议信息！

📅 事件详情：

标题：项目启动会
时间：2026-02-19 09:30-11:30（2小时）
地点：公司5楼大会议室
参与人：项目团队全体成员

准备事项：
✓ 项目需求文档
✓ 技术方案
✓ 时间排期

备注：

会后有工作午餐
务必参加

提醒设置：

提前1天提醒（准备材料）
提前1小时提醒
提前15分钟提醒

已创建日历事件 ✅

💡 提示：已自动预留11:30-13:00的午餐时间

6.2.5 实战案例3：多个事件批量创建

微信截图内内容：
本周安排：
周一10:00 - 团队周会（会议室A）
周三14:00 - 客户拜访（客户公司）
周五16:00 - 项目复盘（线上会议）

OpenClaw操作：

你：[发布送截图]
帮我批量创建这些日历事件

OpenClaw：正在识别多个事件...

[识别完成]

OpenClaw：已识别到3个事件！

📅 事件1：团队周会

时间：2026-02-10 10:00-11:00
地点：会议室A
✅ 已创建

📅 事件2：客户拜访

时间：2026-02-12 14:00-15:30
地点：客户公司（需要具体地址）
✅ 已创建

📅 事件3：项目复盘

时间：2026-02-14 16:00-17:00
地点：线上会议（需要会议链接）
✅ 已创建

所有事件已同步到日历 ✅

💡 提示：

客户拜访需要补充具体地址
项目复盘需要添加会议链接

6.2.6 识别准确率优化

提高识别准确率的技巧：

技巧1：清晰的截图
✅ 好的截图：

文字清晰
光线充足
完整内内容

❌ 不好的截图：

模糊不清
光线太暗
内内容被截断

技巧2：结构化的信息
✅ 内容易识别：
时间：明天下午3点
地点：会议室A
事项：讨论项目

❌ 难以识别：
明天下午在那个地方讨论那个事

技巧3：补充说明
你：[发布送截图]
这是约明天下午的会议，地点在公司

OpenClaw：收到！我会结合你的说明来识别。

技巧4：确认和修正
OpenClaw：我识别到的信息是：
时间：明天下午3点
地点：会议室A

请确认是否正确？

你：时间对了，但地点是会议室B

OpenClaw：好的，已修正为会议室B ✅

6.3 批量日程导入

6.3.1 为什么需要批量导入

常见场景：

新学期课程表
- 10-20门课程
- 每周重复
- 不同教室
项目里程碑
- 多个关键节点
- 不同负责人
- 各种deadline
会议日程
- 多场会议
- 不同时间地点
- 不同参与人

传统做法：

一个一个手动创建
耗时1-2小时
内容易出错

OpenClaw做法：

准备Excel/CSV文件
一键批量导入
5分钟完成

6.3.2 Excel日程导入

步骤1：准备Excel文件

创建一个Excel文件（课程表.xlsx）：

标题	日期	开始时间	结束时间	地点	备注	重复
高等数学	2026-02-10	08:00	09:40	教学楼A101	王老师	每周一
大学英语	2026-02-10	10:00	11:40	教学楼B203	李老师	每周一
计算机基础	2026-02-11	14:00	15:40	实验楼C301	张老师	每周二
体育课	2026-02-12	08:00	09:40	体育馆	刘老师	每周三

步骤2：OpenClaw导入

你：帮我导入这个课程表到日历
[上传课程表.xlsx]

OpenClaw：正在读取Excel文件...

[读取完成]

OpenClaw：已识别到4门课程！

正在创建日历事件...

✅ 高等数学（每周一 08:00-09:40）
✅ 大学英语（每周一 10:00-11:40）
✅ 计算机基础（每周二 14:00-15:40）
✅ 体育课（每周三 08:00-09:40）

已创建本学期所有课程（共16周，64个事件）

提醒设置：

每节课提前15分钟提醒

已同步到Mac和iPhone日历 ✅

6.3.3 CSV格式处理

CSV文件示例（项目里程碑.csv）：

csv

标题,日期,时间,地点,负责人,优先级
需求评审,2026-02-15,14:00-16:00,会议室A,张三,高
设计评审,2026-02-20,10:00-12:00,会议室B,李四,高
开发布完成,2026-03-01,全天,无,王五,高
测试完成,2026-03-10,全天,无,赵六,中
上线发布布,2026-03-15,09:00-18:00,机房,张三,高
**OpenClaw导入**：

你：帮我导入项目里程碑
[上传 项目里程碑.csv]

OpenClaw：正在读取CSV文件...

[读取完成]

OpenClaw：已识别到5个里程碑！

📅 需求评审
- 时间：2026-02-15 14:00-16:00
- 负责人：张三
- 优先级：高
✅ 已创建

📅 设计评审
- 时间：2026-02-20 10:00-12:00
- 负责人：李四
- 优先级：高
✅ 已创建

📅 开发布完成
- 时间：2026-03-01 全天
- 负责人：王五
- 优先级：高
✅ 已创建

📅 测试完成
- 时间：2026-03-10 全天
- 负责人：赵六
- 优先级：中
✅ 已创建

📅 上线发布布
- 时间：2026-03-15 09:00-18:00
- 负责人：张三
- 优先级：高
✅ 已创建

所有里程碑已同步到日历 ✅

提醒设置：
- 高优先级：提前1周、3天、1天
- 中优先级：提前3天、1天
### 6.3.4 批量创建事件

**场景**：你需要创建一系列会议。

**OpenClaw操作**：

你：帮我创建以下会议：

1. 每周一10:00，团队周会，会议室A，1小时
2. 每周三14:00，技术分分享，会议室B，2小时
3. 每周五16:00，项目复盘，线上会议，1小时

从下周开始，支持续12周

OpenClaw：正在批量创建会议...

[创建中...]

OpenClaw：已完成批量创建！

📊 创建统计：
- 团队周会：12次
- 技术分分享：12次
- 项目复盘：12次
- 总计：36个事件

时间范围：
- 开始：2026-02-17
- 结束：2026-05-09

提醒设置：
- 所有会议提前15分钟提醒

已同步到Mac和iPhone日历 ✅

💡 提示：可以在日历中单独修改某次会议
### 6.3.5 数据验证和错误处理

**OpenClaw的智能验证**：

**验证1：时间冲突检测**
OpenClaw：⚠️ 检测到时间冲突！

冲突事件：
- 2026-02-15 14:00 需求评审（会议室A）
- 2026-02-15 14:30 客户拜访（客户公司）

建议：
1. 调整需求评审到15:00
2. 调整客户拜访到16:00
3. 取消其中一个

请选择处理方式：
**验证2：日期格式错误**
OpenClaw：⚠️ 发布现日期格式错误！

错误行：
- 第3行：日期"2026/02/30"无效（2月没有30日）
- 第5行：时间"25:00"无效（超过24小时）

已自动修正：
- 第3行：改为"2026-03-01"
- 第5行：改为"23:00"

请确认是否正确？
**验证3：必填字段缺失**
OpenClaw：⚠️ 发布现必填字段缺失！

缺失信息：
- 第2行：缺少"标题"
- 第4行：缺少"日期"

建议：
1. 补充缺失信息
2. 跳过这些行
3. 使用默认值

请选择处理方式：
---

## 6.4 提醒设置技巧

### 6.4.1 提醒类型和时机

**提醒类型**：

1. **时间提醒**
   - 提前X分钟/小时/天
   - 准时提醒
   - 延迟提醒

2. **位置提醒**
   - 到达某地时提醒
   - 离开某地时提醒

3. **重复提醒**
   - 每天/每周/每月
   - 自定义周期

**提醒时机选择**：

不同类型的事件需要不同的提醒策略，如表 6-1 所示。

**表 6-1 不同事件类型的推荐提醒时机**

| 事件类型 | 推荐提醒时机 | 理由 |
|---------|-------------|------|
| 重要会议 | 提前1天、1小时、15分钟 | 充分准备 |
| 普通会议 | 提前1小时、15分钟 | 及时赶到 |
| 项目deadline | 提前1周、3天、1天 | 避免拖延 |
| 日常任务 | 提前30分钟 | 不打断工作 |
| 约会 | 提前2小时、30分钟 | 预留准备时间 |
| 课程 | 提前15分钟 | 准时到达 |

### 6.4.2 多级提醒设置

**场景**：重要项目deadline。

**OpenClaw操作**：

你：帮我设置项目deadline的提醒：
2026年3月15日，产品上线

OpenClaw：好的，我来设置多级提醒！

📅 事件：产品上线
⏰ 日期：2026-03-15

提醒设置：

🔔 第1级提醒（提前2周）
- 时间：2026-03-01 09:00
- 内内容：距离产品上线还有2周，开始最后冲刺
- 行动：检查进度，确认资源

🔔 第2级提醒（提前1周）
- 时间：2026-03-08 09:00
- 内内容：距离产品上线还有1周，进入倒计时
- 行动：完成测试，准备上线方案

🔔 第3级提醒（提前3天）
- 时间：2026-03-12 09:00
- 内内容：距离产品上线还有3天，最后检查
- 行动：确认上线流程，准备回滚方案

🔔 第4级提醒（提前1天）
- 时间：2026-03-14 09:00
- 内内容：明天产品上线，做好准备
- 行动：团队动员，确认值班安排

🔔 第5级提醒（当天早上）
- 时间：2026-03-15 08:00
- 内内容：今天产品上线，加油！
- 行动：最后检查，准备上线

已设置5级提醒 ✅
### 6.4.3 智能提醒策略

**OpenClaw的智能提醒**：

**策略1：根据事件重要性**
你：帮我创建一个重要会议：
明天下午3点，董事会会议

OpenClaw：检测到"董事会会议"，
这是重要会议，建议设置：

🔔 提前1天提醒（准备材料）
🔔 提前2小时提醒（检查准备）
🔔 提前30分钟提醒（前往会议室）
🔔 提前10分钟提醒（最后确认）

是否采用此提醒方案？
**策略2：根据地点距离**
你：帮我创建日历：
明天下午2点，在客户公司开会

OpenClaw：检测到需要外出，
根据地点距离（约30分钟车程），建议：

🔔 提前2小时提醒（准备出发布）
🔔 提前1小时提醒（确认路线）
🔔 提前30分钟提醒（立即出发布）

已自动计算路程时间 ✅
**策略3：根据准备需求**
你：帮我创建日历：
下周一上午10点，产品演示

OpenClaw：检测到需要准备演示，建议：

🔔 提前3天提醒（准备演示材料）
🔔 提前1天提醒（演练演示流程）
🔔 提前2小时提醒（检查设备）
🔔 提前30分钟提醒（前往会议室）

准备清单：
✓ 演示PPT
✓ 产品Demo
✓ 备用方案
✓ 投影设备

已创建提醒和清单 ✅
### 6.4.4 与其他工具集成

**集成1：飞书提醒**

你：把日历提醒同步到飞书

OpenClaw：已配置飞书提醒！

提醒方式：
- 日历提醒（Mac/iPhone）
- 飞书消息提醒
- 飞书日历同步

示例：
当"明天下午3点会议"提前1小时时：
1. Mac通知中心弹窗 ✅
2. iPhone锁屏通知 ✅
3. 飞书消息提醒 ✅

已同步到飞书 ✅
**集成2：企业微信提醒**

你：把重要会议提醒发布到企业微信

OpenClaw：已配置企业微信提醒！

提醒规则：
- 标记为"重要"的会议
- 提前1天、1小时发布送企业微信消息

消息格式：
📅 重要会议提醒
标题：[会议名称]
时间：[会议时间]
地点：[会议地点]
准备：[准备事项]

已配置完成 ✅
**集成3：邮件提醒**

你：把项目deadline发布邮件提醒我

OpenClaw：已配置邮件提醒！

提醒规则：
- 所有deadline事件
- 提前1周、3天、1天发布送邮件

邮件内内容：
主题：[项目名称] Deadline提醒
内内容：
- 截止时间
- 剩余天数
- 完成进度
- 行动建议

已配置完成 ✅
### 6.4.5 提醒管理技巧

**技巧1：避免提醒疲劳**

❌ 不好的做法：
- 所有事件都设置多个提醒
- 提醒时间过于密集
- 提醒内内容千篇一律

✅ 好的做法：
- 重要事件多提醒，普通事件少提醒
- 提醒时间合理分散
- 提醒内内容个性化
**技巧2：提醒内内容优化**

❌ 普通提醒：
"会议提醒：15分钟后开会"

✅ 优化提醒：
"📅 产品评审会议
⏰ 15分钟后（14:45）
📍 会议室A（3楼）
👤 参会人：产品团队
📝 记得带：产品方案、数据报告"
**技巧3：提醒优先级**

🔴 高优先级（立即处理）
- 重要会议（提前10分钟）
- 紧急任务（当天）
- 客户约会（提前30分钟）

🟡 中优先级（尽快处理）
- 普通会议（提前15分钟）
- 常规任务（提前1天）
- 团队活动（提前2小时）

🟢 低优先级（有空处理）
- 学习计划（提前1天）
- 个人事项（提前30分钟）
- 兴趣活动（提前2小时）
**技巧4：提醒时间优化**

根据个人习惯调整：

早起型（7:00起床）：
- 早上提醒：08:00
- 中午提醒：12:00
- 晚上提醒：19:00

晚睡型（9:00起床）：
- 早上提醒：10:00
- 中午提醒：14:00
- 晚上提醒：21:00

工作日 vs 周末：
- 工作日：提前1小时
- 周末：提前2小时（更放松）

---

## 📝 本章节小结

本章节学习了OpenClaw的日程与任务管理功能：

### 核心功能

1. **日历自动创建**
   - 文本识别创建
   - 复杂日程处理
   - 周期性事件设置
   - 日历模板使用

2. **微信截图识别**
   - OCR文字识别
   - 智能信息提取
   - 批量事件创建
   - 识别准确率优化

3. **批量日程导入**
   - Excel文件导入
   - CSV格式处理
   - 数据验证
   - 错误处理

4. **提醒设置技巧**
   - 多级提醒
   - 智能提醒策略
   - 工具集成
   - 提醒管理优化

### 实战技巧

- ✅ 统一命名规范
- ✅ 合理设置提醒
- ✅ 添加详细信息
- ✅ 使用颜色分类
- ✅ 避免提醒疲劳
- ✅ 优化提醒内内容

### 下一步

- 学习第7章节：自动化工作流
- 掌握定时任务设置
- 实现网站监控
- 构建自动化系统

---

## 🎯 实战练习

### 练习1：创建本周日程
1. 列出本周所有安排
2. 使用 OpenClaw创建日历事件
3. 设置合理的提醒
4. 在手机上查看

### 练习2：微信截图识别
1. 找一条微信约会消息
2. 截图发布给OpenClaw
3. 让它创建日历事件
4. 检查识别准确性

### 练习3：批量导入课程表
1. 准备一个Excel课程表
2. 使用 OpenClaw批量导入
3. 检查所有事件
4. 调整提醒设置

---

## 💡 常见访问题

**Q1：日历事件创建失败？**
A：检查Mac日历权限，确保OpenClaw有访问权限。

**Q2：截图识别不准确？**
A：确保截图清晰，文字完整，必要时手动补充信息。

**Q3：批量导入出错？**
A：检查Excel格式，确保日期时间格式正确。

**Q4：提醒没有收到？**
A：检查通知设置，确保Mac和iPhone通知权限已开启。

**Q5：如何删除批量创建的事件？**
A：在日历中选择事件，批量删除，或让OpenClaw帮你删除。

---

**下一章节预告**：第7章节将学习自动化工作流，包括定时任务设置、网站监控实战、日报自动推送等高级功能。


---

## 🌐 在线阅读

📖 **想在线阅读此章节节？**

[🔗 在线阅读此章节节](https://awesome.tryopenclaw.asia/docs/02-core-features/06-schedule-management/)

访问网站获取更好的阅读体验：
- 📱 响应式设计，支持手机、平板、电脑
-  支持黑暗模式，保护眼睛
- 🔍 内置搜索功能，快速定位内内容
- 📋 目附录导航，轻松跳转章节节

[🏠 访问完整教网站](https://awesome.tryopenclaw.asia)

---

### 02 Core Features 07 Automation Workflow (`docs/02-core-features/07-automation-workflow.md`)

> 📖 **纸质书《OpenClaw超级个体实操手册》已上市！** 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 [京东专属购买链接（¥42，原价¥59.8）](https://item.jd.com/14669463.html)

# 第7章节 自动化工作流

> 💡 **本章节目标**：学会使用 OpenClaw构建自动化工作流，实现定时任务、网站监控、日报推送和循环任务配置。

> 🔄 **v2026.9.3 对齐说明**：本章 cron / heartbeat 例子仍可参考，但请按 **Task Flow + Webhooks** 主线理解自动化。升级到 2026.8+ 后会话已迁入 SQLite；自动化里若仍写着旧的 `codex/*` / `openai-codex/*` 模型路由，请先执行 `openclaw doctor --fix`。长期/多步骤流程优先看第 13 章。

## 🤖 本章节内内容

- 7.1 定时任务设置
- 7.2 网站监控实战
- 7.3 日报自动推送
- 7.4 循环任务配置

---

## 7.1 定时任务设置

### 7.1.1 什么是定时任务

**定义**：
定时任务是指在指定时间自动执行的任务，无需人工干预。

**OpenClaw的独特优势**：
- ✅ **心跳机制**：可以主动发布起对话
- ✅ **智能调度**：自动管理任务执行
- ✅ **灵活配置**：支持多种时间模式
- ✅ **可靠执行**：失败自动重试

OpenClaw 与其他 AI 工具在自动化能力上的对比如表 7-1 所示。

**表 7-1 OpenClaw 与其他 AI 工具自动化能力对比**

| 特性 | OpenClaw | ChatGPT | Claude |
|------|----------|---------|--------|
| 主动对话 | ✅ | ❌ | ❌ |
| 定时任务 | ✅ | ❌ | ❌ |
| 本地执行 | ✅ | ❌ | ❌ |
| 系统操作 | ✅ | ❌ | ❌ |

### 7.1.2 心跳机制原理

**OpenClaw的心跳机制**：

┌─────────────┐
│  OpenClaw   │
│   守护进程   │
└──────┬──────┘
       │
       ├─ 每分钟检查一次
       ├─ 匹配定时任务
       ├─ 执行任务逻辑
       └─ 发布送消息/执行操作

**工作流程**：
1. OpenClaw后台运行
2. 每分钟检查任务列表
3. 到达设定时间时触发布
4. 执行任务并发布送结果
5. 记附录执行日志

### 7.1.3 实战案例1：简单提醒

**场景**：你想在每天早上8点收到一条访问候消息。

**OpenClaw操作**：

你：帮我设置1个定时提醒：
每天早上8点，发布送早安访问候

OpenClaw：好的，我来设置定时提醒！

⏰ 定时任务详情：
- 任务名称：早安访问候
- 执行时间：每天 08:00
- 任务内内容：发布送早安消息
- 推送方式：飞书消息

任务预览：
"☀️ 早安！新的一天开始了！
今天是2026年2月10日，星期二
天气：晴，15-25°C
今日提醒：
- 10:00 团队周会
- 14:00 客户拜访
- 16:00 项目复盘

加油，祝你今天工作顺利！💪"

已设置定时任务 ✅
首次执行：明天 08:00



**第二天早上8点**：

OpenClaw：☀️ 早安！新的一天开始了！

今天是2026年2月11日，星期三
天气：晴，15-25°C

📅 今日日程：
- 10:00 团队周会（会议室A）
- 14:00 客户拜访（客户公司）
- 16:00 项目复盘（线上会议）

✅ 待怎么办事项：
- 完成项目报告
- 回复客户邮件
- 准备周会材料

💡 今日建议：
- 提前准备客户拜访材料
- 预留路上时间（约30分钟）

加油，祝你今天工作顺利！💪

### 7.1.4 实战案例2：每周报告

**场景**：你想每周五下午5点收到本周工作总结。

**OpenClaw操作**：

你：帮我设置每周五下午5点，
生成本周工作总结并发布送给我

OpenClaw：好的，我来设置周报任务！

⏰ 定时任务详情：
- 任务名称：周报生成
- 执行时间：每周五 17:00
- 任务内内容：生成本周工作总结
- 推送方式：飞书消息 + 邮件

报告内内容：
1. 本周完成的任务
2. 本周参加的会议
3. 本周学习的内内容
4. 下周计划
5. 需要关注的事项

数据来源：
- 日历事件
- 备忘附录笔记
- 任务完成记附录

已设置定时任务 ✅
首次执行：本周五 17:00

**周五下午5点**：

OpenClaw：📊 本周工作总结（2026-02-10 至 2026-02-14）

## 📋 完成任务（8项）
✅ 完成产品需求文档
✅ 完成技术方案设计
✅ 完成代码审查（3次）
✅ 完成客户拜访（2次）
✅ 完成团队分分享
✅ 完成项目复盘
✅ 完成周报撰写
✅ 完成学习笔记整理

## 📅 参加会议（12场）
- 团队周会：2次
- 项目讨论：4次
- 客户拜访：2次
- 技术分分享：2次
- 项目复盘：2次

## 📚 学习内内容
- 阅读技术文章节：5篇
- 学习新技术：React 19
- 完成课程：2节

## 📝 下周计划
- 完成产品原型设计
- 开始开发布工作
- 准备技术分分享
- 客户需求调研

## ⚠️ 需要关注
- 项目进度略有延迟
- 需要增加开发布资源
- 客户需求需要确认

已发布送到：
- 飞书消息 ✅
- 邮箱 ✅

### 7.1.5 实战案例3：每月总结

**场景**：你想每月最后一天生成月度总结。

**OpenClaw操作**：

你：帮我设置每月最后一天晚上8点，
生成月度总结

OpenClaw：好的，我来设置月报任务！

⏰ 定时任务详情：
- 任务名称：月度总结
- 执行时间：每月最后一天 20:00
- 任务内内容：生成月度工作总结
- 推送方式：飞书消息 + 邮件 + 备忘附录

报告内内容：
1. 月度目标完成情况
2. 重要项目进展
3. 个人成长与学习
4. 数据统计分析
5. 下月计划与目标

已设置定时任务 ✅
首次执行：2026-02-28 20:00


### 7.1.6 Cron表达式详解

**什么是Cron表达式**：

Cron表达式是一种时间表达式，用于精确控制任务执行时间。

**基本格式**：
分钟 小时 日期 月份 星期

* * * * *
│ │ │ │ │
│ │ │ │ └─ 星期 (0-7, 0和7都表示周日)
│ │ │ └─── 月份 (1-12)
│ │ └───── 日期 (1-31)
│ └─────── 小时 (0-23)
└───────── 分钟 (0-59)

**常用示例**：

/* Detailed source-code truncated for AI context efficiency. */

markdown

# AI行业日报（2026-02-11）

## 📰 今日要闻（3-5条）
- 重要新闻
- 行业动态
- 技术突破

## 🔥 热门话题（3-5个）
- 社区讨论
- 技术趋势
- 产品发布布

## 📚 精选文章节（3-5篇）
- 技术教程
- 深度分析
- 实战案例

## 🛠️ 开源项目（2-3个）
- 新项目推荐
- 项目更新
- 实用工具

## 📅 今日日程
- 会议安排
- 任务提醒
- 重要事项

## 💡 每日一句
- 励志名言
- 技术感悟
### 7.3.3 实战案例1：AI行业日报

**OpenClaw操作**：

你：帮我设置AI行业日报，
每天早上8点推送，内内容包括：
- AI新闻（5条）
- 热门GitHub项目（3个）
- 精选技术文章节（3篇）
- 今日日程

OpenClaw：好的，我来设置AI日报！

⏰ 定时任务详情：
- 任务名称：AI行业日报
- 执行时间：每天 08:00
- 推送方式：飞书云文档
- 数据来源：
  * Hacker News
  * GitHub Trending
  * 技术博客RSS
  * 个人日历

已设置定时任务 ✅
首次推送：明天 08:00


**第二天早上8点**：



OpenClaw：📊 AI行业日报（2026-02-11）

## 📰 今日要闻

1. **OpenAI发布布GPT-5预览版**
   - 性能提升50%
   - 支持更长上下文
   - 来源：OpenAI Blog

2. **Google Gemini 3.0正式发布布**
   - 多模态能力增强
   - 免费额度提升
   - 来源：Google AI Blog

3. **Meta开源新一代LLaMA模型**
   - 参数规模达700B
   - 性能接近GPT-4
   - 来源：Meta AI

4. **Anthropic推出Claude Code**
   - 专注代码生成
   - 集成VSCode
   - 来源：Anthropic

5. **DeepMind突破蛋白质折叠难题**
   - AlphaFold 3发布布
   - 准确率提升至95%
   - 来源：Nature

## 🔥 热门GitHub项目

1. **awesome-ai-tools** ⭐ 15.2k
   - AI工具集合
   - 每日更新
   - 链接：github.com/...

2. **llama-cpp** ⭐ 8.5k
   - 本地运行大模型
   - 性能优化
   - 链接：github.com/...

3. **chatgpt-web** ⭐ 12.3k
   - ChatGPT网页版
   - 开源免费
   - 链接：github.com/...

## 📚 精选文章节

1. **《大模型提示词工程实战》**
   - 作者：张三
   - 阅读时长：15分钟
   - 推荐指数：⭐⭐⭐⭐⭐

2. **《如何用AI提升工作效率》**
   - 作者：李四
   - 阅读时长：10分钟
   - 推荐指数：⭐⭐⭐⭐

3. **《OpenClaw实战指南》**
   - 作者：王五
   - 阅读时长：20分钟
   - 推荐指数：⭐⭐⭐⭐⭐

## 📅 今日日程

- 10:00 团队周会（会议室A）
- 14:00 客户拜访（客户公司）
- 16:00 项目复盘（线上会议）

## 💡 每日一句

"AI不会取代你，但会用AI的人会取代你。"

---

完整日报已保存到：飞书云文档 > AI日报 > 2026-02-11
### 7.3.4 实战案例2：技术资讯日报

**场景**：你是前端开发布者，想每天了解前端技术动态。

**OpenClaw操作**：

你：帮我设置前端技术日报，
每天早上9点推送，内内容包括：
- React/Vue/Angular最新动态
- 前端工具和库更新
- 技术文章节推荐
- Stack Overflow热门访问题

OpenClaw：好的，我来设置前端日报！

⏰ 定时任务详情：
- 任务名称：前端技术日报
- 执行时间：每天 09:00
- 推送方式：飞书消息
- 数据来源：
  * GitHub Trending (JavaScript)
  * Dev.to前端标签
  * Medium前端专栏
  * Stack Overflow

已设置定时任务 ✅
### 7.3.5 实战案例3：个人工作日报

**场景**：你想每天晚上收到今日工作总结。

**OpenClaw操作**：

你：帮我设置个人工作日报，
每天晚上8点推送，内内容包括：
- 今日完成的任务
- 今日参加的会议
- 今日学习的内内容
- 明日待怎么办事项

OpenClaw：好的，我来设置工作日报！

⏰ 定时任务详情：
- 任务名称：个人工作日报
- 执行时间：每天 20:00
- 推送方式：飞书消息 + 备忘附录
- 数据来源：
  * 日历事件
  * 任务完成记附录
  * 备忘附录笔记
  * 学习记附录

已设置定时任务 ✅
**晚上8点推送**：

OpenClaw：📊 今日工作总结（2026-02-11）

## ✅ 完成任务（5项）
- 完成产品需求文档
- 完成代码审查
- 完成客户拜访
- 完成技术分分享
- 完成学习笔记

## 📅 参加会议（3场）
- 10:00 团队周会（1小时）
- 14:00 客户拜访（1.5小时）
- 16:00 项目复盘（1小时）

## 📚 学习内内容
- 阅读《React 19新特性》
- 学习Next.js 14
- 完成TypeScript练习

## 📝 明日待怎么办
- 完成产品原型设计
- 准备技术分分享PPT
- 回复客户邮件
- 代码重构

## 📊 今日数据
- 工作时长：8小时
- 会议时长：3.5小时
- 专注时长：4.5小时
- 学习时长：1小时

## 💭 今日感悟
今天效率不错，完成了预定的所有任务。
明天继续加油！💪

已保存到备忘附录 ✅
### 7.3.6 推送渠道选择

不同的推送渠道各有优劣，如表 7-3 所示。

**表 7-3 不同推送渠道对比**

| 推送方式 | 优势 | 劣势 | 适合场景 |
|---------|------|------|----------|
| **飞书消息** | 即时、便捷 | 内容易被忽略 | 紧急提醒 |
| **飞书云文档** | 结构化、可搜索 | 需要打开 | 详细报告 |
| **邮件** | 正式、存档 | 不够即时 | 重要通知 |
| **备忘附录** | 跨设备同步 | 不够醒目 | 长期保存 |
| **企业微信** | 工作场景 | 需要配置 | 团队协作 |

**推荐组合**：

日常提醒：飞书消息
详细报告：飞书云文档
重要通知：飞书消息 + 邮件
长期保存：备忘附录
团队分分享：企业微信
---

## 7.4 循环任务配置

### 7.4.1 什么是循环任务

**定义**：
循环任务是指按照一定规律重复执行的任务。

定时任务与循环任务的区别如表 7-4 所示。

**表 7-4 定时任务与循环任务对比**

| 特性 | 定时任务 | 循环任务 |
|------|---------|---------|
| 执行时间 | 固定时间点 | 固定间隔 |
| 示例 | 每天8点 | 每隔2小时 |
| 适用场景 | 日报、提醒 | 监控、检查 |

### 7.4.2 循环任务类型

**类型1：固定间隔**
每隔X分钟/小时/天执行一次
**类型2：条件触发布**
当满足某个条件时执行
**类型3：依赖任务**
任务A完成后执行任务B
### 7.4.3 实战案例1：数据备份

**场景**：你想每隔6小时备份一次重要数据。

**OpenClaw操作**：

你：帮我设置数据备份任务，
每隔6小时备份一次备忘附录和日历

OpenClaw：好的，我来设置备份任务！

⏰ 循环任务详情：
- 任务名称：数据备份
- 执行间隔：每6小时
- 执行时间：00:00, 06:00, 12:00, 18:00
- 备份内内容：
  * 备忘附录（所有笔记）
  * 日历（所有事件）
  * 任务列表
- 备份位置：~/Documents/Backups/

备份策略：
- 保留最近7天的备份
- 自动压缩
- 加密存储

已设置循环任务 ✅
首次执行：今天 18:00
### 7.4.4 实战案例2：健康提醒

**场景**：你想每隔1小时提醒自己休息一下。

**OpenClaw操作**：

你：帮我设置健康提醒，
工作日每隔1小时提醒我休息，
周末不提醒

OpenClaw：好的，我来设置健康提醒！

⏰ 循环任务详情：
- 任务名称：健康提醒
- 执行间隔：每1小时
- 执行时间：工作日 09:00-18:00
- 提醒内内容：
  * 站起来活动5分钟
  * 眺望远方放松眼睛
  * 喝一杯水

提醒方式：
- 飞书消息
- Mac通知

已设置循环任务 ✅
下次提醒：10:00
**每小时提醒**：

OpenClaw：💪 健康提醒

已经工作1小时了，该休息一下啦！

建议活动：
✓ 站起来走动5分钟
✓ 眺望远方，放松眼睛
✓ 喝一杯水（今天已喝3杯）
✓ 做几个拉伸动作

下次提醒：1小时后
### 7.4.5 任务依赖管理

**场景**：你想设置一系列有依赖关系的任务。

**OpenClaw操作**：

你：帮我设置任务链：
1. 每天早上7点，检查天气
2. 如果下雨，提醒带伞
3. 如果气温低于10度，提醒多穿衣服
4. 然后推送今日日程

OpenClaw：好的，我来设置任务链！

⏰ 任务链配置：

任务1：检查天气
- 执行时间：每天 07:00
- 数据来源：天气API
- 下一步：根据天气决定

任务2：天气提醒（条件触发布）
- 触发布条件：下雨 或 气温<10°C
- 提醒内内容：
  * 下雨 → 记得带伞☂️
  * 气温低 → 多穿衣服🧥

任务3：推送日程
- 执行时机：任务2完成后
- 推送内内容：今日日程安排

已设置任务链 ✅
首次执行：明天 07:00
### 7.4.6 错误重试机制

**OpenClaw的内容错机制**：

任务执行失败 → 等待1分钟 → 重试
重试失败 → 等待5分钟 → 再次重试
再次失败 → 等待15分钟 → 最后重试
最后失败 → 发布送错误通知 → 停止任务
**错误通知示例**：

OpenClaw：⚠️ 任务执行失败

任务名称：AI行业日报
失败时间：2026-02-11 08:00
失败原因：网络连接超时

已尝试重试：3次
重试结果：全部失败

建议：
1. 检查网络连接
2. 检查数据源是否可用
3. 手动执行任务

是否需要我继续重试？

---

## 📝 本章节小结

本章节学习了OpenClaw的自动化工作流功能：

### 核心功能

1. **定时任务设置**
   - 心跳机制原理
   - 简单提醒
   - 周报月报
   - Cron表达式

2. **网站监控实战**
   - 博客更新监控
   - 价格监控
   - 招聘信息监控
   - 监控频率优化

3. **日报自动推送**
   - 日报内内容设计
   - AI行业日报
   - 技术资讯日报
   - 个人工作日报

4. **循环任务配置**
   - 固定间隔任务
   - 条件触发布任务
   - 任务依赖管理
   - 错误重试机制

### 实战技巧

- ✅ 合理设置任务频率
- ✅ 选择合适的推送方式
- ✅ 设计有价值的日报内内容
- ✅ 建立任务依赖关系
- ✅ 配置错误重试机制

### 下一步

- 学习第8章节：Skills扩展
- 掌握ClawHub技能市场
- 学习自定义Skills开发布
- 构建个人技能库

---

## 🎯 实战练习

### 练习1：设置早安提醒
1. 设置每天早上8点的早安提醒
2. 包含天气、日程、待怎么办事项
3. 推送到飞书

### 练习2：监控技术博客
1. 选择3个你关注的技术博客
2. 设置更新监控
3. 有新文章节时通知你

### 练习3：创建个人日报
1. 设计你的日报内内容
2. 设置每天推送时间
3. 选择合适的推送方式

---

## 💡 常见访问题

**Q1：定时任务没有执行？**
A：检查OpenClaw是否在后台运行，查看任务日志。

**Q2：网站监控被封禁？**
A：降低监控频率，添加随机延迟，使用代理。

**Q3：日报内内容不准确？**
A：检查数据源，调整内内容筛选规则。

**Q4：循环任务占用资源？**
A：优化任务逻辑，减少不必要的操作。

**Q5：如何停止某个任务？**
A：告诉OpenClaw"停止XX任务"即可。

---

**下一章节预告**：第8章节将学习Skills扩展，包括ClawHub技能市场、必装Skills推荐、自定义Skills开发布等内内容。


---

## 🌐 在线阅读

📖 **想在线阅读此章节节？**

[🔗 在线阅读此章节节](https://awesome.tryopenclaw.asia/docs/02-core-features/07-automation-workflow/)

访问网站获取更好的阅读体验：
- 📱 响应式设计，支持手机、平板、电脑
-  支持黑暗模式，保护眼睛
- 🔍 内置搜索功能，快速定位内内容
- 📋 目附录导航，轻松跳转章节节

[🏠 访问完整教网站](https://awesome.tryopenclaw.asia)

---

### 03 Advanced 08 Skills Extension (`docs/03-advanced/08-skills-extension.md`)

> 📖 **纸质书《OpenClaw超级个体实操手册》已上市！** 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 [京东专属购买链接（¥42，原价¥59.8）](https://item.jd.com/14669463.html)

# 第8章节 Skills扩展（什么时候该用、怎么查、怎么装、怎么管）

> 本章目标：把 Skills 放回正确位置。它仍然重要，但已经不是“所有能力的唯一入口”。你会学到：什么时候该用 Skills，什么时候该用内建能力，如何安全地搜索、安装、检查和维护 Skills。

---

## 版本基线

- **当前稳定版**：`v2026.9.3`（2026-09-08 发布）
- 本章默认按 `v2026.9.3` 稳定版写；所有命令以官方 `openclaw skills` CLI 为准（不要默认 `clawhub install`）

---

## 先给小白的阅读说明

### 这一章最重要的结论

现在的 OpenClaw，不是“没有 Skills 就什么都干不了”。

很多能力已经有官方主线：

- 模型与 provider：`openclaw models`
- 无头能力调用：`openclaw infer`
- 自动化：`cron / tasks / Task Flow / webhooks`
- 记忆：`Active Memory / Memory Wiki`
- 媒体：`image_generate / video_generate / tts / music_generate`

**Skills 现在更适合做“可复用的工作方法和 SOP”**，而不是当成所有能力的默认入口。

### 如果你只想先学会最实用的部分，先看这些

- **想先装一个能用的 Skill**：看 `8.2`
- **想知道 Skills 和其他能力的分工**：看 `8.1`
- **想自己写一个本地 Skill**：看 `8.4`
- **最担心安全问题**：看 `8.5`

### 小白最容易犯的 4 个错

- 看到旧教程就直接运行 `clawhub install ...`
- 把 Skills、Tools、Plugins、MCP 混成一回事
- 没看源码就装第三方 Skill
- 明明该用 `infer` 或内建能力，却硬找一个 Skill 来做

---

## 8.1 Skills 在 2026.4 之后到底是什么？

### 8.1.1 一句话理解

你可以把 Skill 理解成：

- 一份可复用的操作说明书
- 一套会在合适场景下按需加载的 SOP
- 一段教 agent“遇到这类任务该怎么做”的专业经验

它最适合解决的问题是：**同一类任务你会反复做，而且做法相对稳定**。

### 8.1.2 什么场景该优先用 Skill

适合用 Skill 的情况：

- 固定写作流程
- 固定研究流程
- 固定交付模板
- 固定排查步骤
- 固定格式转换流程

不一定要用 Skill 的情况：

- 临时问答
- 一次性 prompt
- 单条命令就能完成的事
- 官方已经有明确主线能力的事（如 `infer`、媒体生成、Task Flow）

### 8.1.3 现在更实用的判断表

| 你的需求 | 更推荐什么 |
|----------|------------|
| 跑一个模型命令 | `openclaw infer` |
| 切换默认模型 | `openclaw models` |
| 做图片/视频/语音 | 官方媒体能力 |
| 做自动化编排 | `cron / tasks / Task Flow / webhooks` |
| 让 agent 学会一套固定 SOP | Skill |
| 连外部 API / 数据库 / 服务 | Plugin / MCP / Webhooks |

如果你不确定，就先问自己一句：

**“我现在缺的是一个功能入口，还是一套做事方法？”**

- 缺功能入口：先看官方内建能力
- 缺做事方法：再考虑 Skill

---

## 8.2 最快上手：现在官方该怎么查、怎么装、怎么管

官方当前推荐的 CLI 入口是 `openclaw skills`，不是旧教程里的 `clawhub install`。

### 8.2.1 最常用命令

```bash
openclaw skills search "calendar"
openclaw skills search --limit 20 --json
openclaw skills install <slug>
openclaw skills install <slug> --version <version>
openclaw skills install <slug> --force
openclaw skills update <slug>
openclaw skills update --all
openclaw skills list
openclaw skills list --eligible
openclaw skills list --json
openclaw skills list --verbose
openclaw skills info <name>
openclaw skills info <name> --json
openclaw skills check
openclaw skills check --json

8.2.2 小白先记住 5 个就够了

如果你第一次用，其实先会这 5 个就够：

bash

openclaw skills search "写作"
openclaw skills install <slug>
openclaw skills list --eligible
openclaw skills info <name>
openclaw skills check

8.2.3 这些命令到底各自干什么

search：去找有没有合适 Skill
install：把 Skill 装到当前工作区
list --eligible：看当前工作区里哪些 Skill 真正可用
info：看某个 Skill 的详细信息
check：检查本地 Skill 有没有结构问题或可见性问题

8.2.4 Skills 装到哪里

官方文档明确说明：search / install / update 走 ClawHub，但会把 Skill 安装到当前活动工作区的 skills/ 目录。

也就是说，对大多数用户来说，你可以直接理解成：

当前项目里装的 Skill，会跟着这个项目走
不同工作区可以有不同 Skill 组合
list / info / check 看的是当前工作区和当前配置下可见的本地 Skill

8.2.5 看到什么算已经装成功

至少满足下面 3 条：

openclaw skills list --eligible 能看到你刚装的 Skill
openclaw skills info <name> 能读到它的说明
你在合适任务里调用它时，agent 能真正识别并使用

如果只装上了，但 eligible 里看不到，先别急着怪模型，先跑：

bash

openclaw skills check

8.3 Skills、Tools、Plugins、MCP 到底怎么分

8.3.1 最不容易混的理解方式

Skill：一套做事方法
Tool：一个具体工具动作
Plugin：给 OpenClaw 增加一整类能力
MCP：把外部系统接入为可调用能力

8.3.2 小白版例子

假设你想让 OpenClaw 帮你做“技术文章改写成公众号版本”：

Skill：告诉它这类文章应该怎么拆结构、怎么改风格、怎么出标题
Tool：读取文件、搜索网页、生成图片
Plugin / MCP：连接某个知识库、外部文档系统或发布系统

所以它们不是互相替代，而是分工不同。

8.4 自己写一个最小本地 Skill

如果你已经反复做同一类事，就可以开始写自己的 Skill。

8.4.1 最小目录结构

text

skills/
└── my-writing-helper/
    └── SKILL.md

8.4.2 最小示例

markdown

---
name: my-writing-helper
---

# my-writing-helper

## 什么时候用

当用户要把技术笔记改成更适合公开发布的中文文章时使用。

## 步骤

1. 先提取原始笔记里的核心观点
2. 再重写成更清晰的文章结构
3. 最后输出标题、摘要、小标题和结尾行动建议

8.4.3 写完之后怎么检查

bash

openclaw skills list --eligible
openclaw skills info my-writing-helper
openclaw skills check

8.4.4 什么时候值得自己写 Skill

最值得写 Skill 的情况是：

你已经重复做过 5 次以上
这件事有稳定步骤
你每次都在重复解释同样要求
你希望不同 agent 或不同项目都复用这套做法

如果只是一次性需求，先别写 Skill，直接用 prompt 更省时间。

8.5 安全：第三方 Skill 应该怎么装才稳

官方文档对这一点说得很直接：把第三方 Skills 当成不受信任代码处理。

8.5.1 小白版安全规则

安装前先做到这 4 件事：

先看 openclaw skills info <name>
尽量阅读源码或至少阅读 SKILL.md
对不熟悉的 Skill，优先在沙箱或低风险项目里试
装完先跑 openclaw skills check

8.5.2 为什么不能无脑装

官方文档提到：

第三方 Skill 应该视为不受信任代码
Gateway 侧的依赖安装流程会做危险代码扫描
但这不等于你可以不看、不判断、不复核

所以更稳的习惯是：

先装你看得懂用途的 Skill
先装数量少、目标明确的 Skill
一次只加一个，确认没问题再加下一个

8.5.3 哪些信号要提高警惕

描述很模糊，但权限要求很多
需要你额外执行可疑脚本
要求访问你不相关的目录或系统能力
你根本不知道它为什么需要这些权限

8.6 给小白的最短落地顺序

如果你今天只想花 15 分钟把 Skills 跑起来，按这个顺序做：

openclaw skills search "你要做的事"
选一个最简单、用途最明确的 Skill
openclaw skills install <slug>
openclaw skills list --eligible
openclaw skills info <name>
openclaw skills check
在一个真实任务里试一次

8.7 本章最容易踩的坑

坑 1：把 Skills 当成所有能力的入口

现在很多能力已经有官方更稳定的主线，不需要先找 Skill。

坑 2：直接照搬旧教程里的 `clawhub install`

当前官方命令以 openclaw skills 为准。旧写法不应该再作为默认主路线。

坑 3：一上来就装很多 Skill

最稳的方式永远是：

先装一个
先看它能不能用
先确认它到底解决了什么问题

坑 4：明明是工作方法问题，却去换模型

有些问题不是模型不够强，而是你缺一套稳定 SOP。那才是 Skill 真正适合出场的时候。

8.8 官方参考

Skills CLI：https://docs.openclaw.ai/cli/skills
Skills 工具说明：https://docs.openclaw.ai/tools/skills
Plugins CLI：https://docs.openclaw.ai/cli/plugins
Hooks CLI：https://docs.openclaw.ai/cli/hooks
Models CLI：https://docs.openclaw.ai/cli/models

03 Advanced 09 Multi Platform Integration (`docs/03-advanced/09-multi-platform-integration.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第9章节多平台集成

💡 本章节目标：学会将OpenClaw接入飞书、企业微信、钉钉、QQ等国内主流平台，实现随时随地使用AI助手。飞书作为最现代化、开发布友好的平台，将优先介绍。

📱 本章节内内容

9.1 飞书Bot配置
- 9.1.1 飞书机器人介绍
- 9.1.2 快速开始
- 9.1.3 创建飞书应用
- 9.1.4 配置 OpenClaw
- 9.1.5 启动并测试
- 9.1.6 访问控制
- 9.1.7 群组配置
- 9.1.8 获取群组/用户 ID
- 9.1.9 高级配置
- 9.1.10 多账号配置
- 9.1.11 多 Agent 配置
  - 9.1.11.1 配合飞书使用
  - 9.1.11.2 实战案例：4个专业助手
  - 9.1.11.3 配置注意事项
  - 9.1.11.4 故障排查
  - 9.1.11.5 配置对比
  - 9.1.11.6 使用建议
  - 9.1.11.7 本地多 Agent 管理（无需绑定 IM 平台）⭐新增
9.2 企业微信Bot配置
9.3 钉钉Bot配置
9.4 QQ Bot配置
9.5 微信接入（ClawBot 官方方案）⭐新增
- 9.5.1 ClawBot 是什么
- 9.5.2 安装步骤
- 9.5.3 工作原理
- 9.5.4 与第三方方案对比
- 9.5.5 配置与使用
- 9.5.6 注意事项
9.6 浏览器渠道（Dashboard v2）⭐新增
- 9.6.1 什么是浏览器渠道
- 9.6.2 适用场景
- 9.6.3 访问方式与功能

9.1 飞书Bot配置

💡 状态：生产就绪，支持机器人私聊和群组，使用 WebSocket 长连接模式接收消息。

9.1.1 飞书机器人介绍

飞书的优势：

现代化怎么办公
- 文档协作
- 多维表格
- 视频会议
高效沟通
- 消息卡片
- 互动组件
- 流式输出
开发布友好
- API设计优秀
- 文档详细
- WebSocket长连接
免费使用
- 功能强大
- 稳定可靠

9.1.2 快速开始

添加飞书渠道有两种方式：

方式一：通过安装向导添加（推荐）

如果您刚安装完 OpenClaw，可以直接运行向导：

bash

openclaw setup

向导会引导您完成：

创建飞书应用并获取凭证
配置应用凭证
启动网关

✅ 完成配置后，您可以使用以下命令检查网关状态：

bash

openclaw gateway status      # 查看网关运行状态
openclaw logs --follow       # 查看实时日志

方式二：通过命令行添加

如果您已经完成了初始安装，可以用以下命令添加飞书渠道：

bash

openclaw channels add

然后根据交互式提示选择 Feishu，输入 App ID 和 App Secret 即可。

✅ 完成配置后，您可以使用以下命令管理网关：

bash

openclaw gateway status      # 查看网关运行状态
openclaw gateway restart     # 重启网关以应用新配置
openclaw logs --follow       # 查看实时日志

9.1.3 第一步：创建飞书应用

1. 打开飞书开放平台

访问飞书开放平台，使用飞书账号登录。

💡 Lark（国际版）：请使用 https://open.larksuite.com/app，并在配置中设置 domain: "lark"。

2. 创建应用

点击 创建企业自建应用
填写应用名称和描述
选择应用图标

3. 获取应用凭证

在应用的 凭证与基础信息 页面，复制：

App ID（格式如 cli_xxx）
App Secret

❗ 重要：请妥善保管 App Secret，不要分分享给他人。

4. 配置应用权限

在 权限管理 页面，点击 批量导入 按钮，粘贴以下 JSON 配置一键导入所需权限：

json

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

5. 启用机器人能力

在 应用能力 > 机器人 页面：

开启机器人能力
配置机器人名称

6. 配置事件订阅

⚠️ 重要提醒：在配置事件订阅前，请务必确保已完成以下步骤：

运行 openclaw channels add 添加了 Feishu 渠道
网关处于启动状态（可通过 openclaw gateway status 检查状态）

在 事件订阅 页面：

步骤1：选择长连接模式

选择 使用长连接接收事件（WebSocket 模式）

步骤2：添加事件
2. 添加事件：im.message.receive_v1（接收消息）

步骤3：配置必需权限（重要）

在配置事件订阅的同时，请确保在 权限管理 页面已添加以下权限：

权限标识	权限名称	是否必需	说明
`im:message`	获取与发布送单聊、群组消息	✅ 必需	接收和发布送消息
`im:message:send_as_bot`	以应用身份发布消息	✅ 必需	以机器人身份回复
`contact:contact.base:readonly`	获取通讯附录基本信息	✅ 必需	识别用户身份

💡 为什么需要 contact:contact.base:readonly 权限？

这个权限用于获取用户的基本信息（如用户名、部门等），OpenClaw需要这些信息来：

✅ 识别消息发布送者

✅ 实现访问控制（allowlist/denylist）

✅ 提供个性化服务

✅ 记附录对话历史

⚠️ 如果缺少此权限，机器人将无法正常响应消息！

配置截图示例：

⚠️ 注意：如果网关未启动或渠道未添加，长连接设置将保存失败。

常见错误排查：

如果遇到 "Gateway start blocked: set gateway.mode=local" 错误：

bash

# 确保配置文件中设置了 gateway.mode
{
  "gateway": {
    "mode": "local"
  }
}

如果遇到 "Gateway auth is set to token, but no token is configured" 错误：

bash

# 方式1：在配置文件中设置 token
{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-secure-token"
    }
  }
}

# 方式2：使用环境变量
export OPENCLAW_GATEWAY_TOKEN="your-secure-token"

7. 发布布应用

在 版本管理与发布布 页面创建版本
提交审核并发布布
等待管理员审批（企业自建应用通常自动通过）

9.1.4 第二步：配置 OpenClaw

安装 Feishu 插件

bash

# 安装 Feishu 插件
openclaw plugins install @openclaw/feishu

# 本地 checkout（在 git 仓库内运行）
openclaw plugins install ./extensions/feishu

通过向导配置（推荐）

运行以下命令，根据提示粘贴 App ID 和 App Secret：

bash

openclaw channels add

选择 Feishu，然后输入您在第一步获取的凭证即可。

通过配置文件配置

编辑 ~/.openclaw/openclaw.json：

json

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "我的AI助手"
        }
      }
    }
  }
}

通过环境变量配置

bash

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Lark（国际版）域名配置

如果您的租户在 Lark（国际版），请设置域名为 lark：

json

{
  "channels": {
    "feishu": {
      "domain": "lark",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx"
        }
      }
    }
  }
}

9.1.5 第三步：启动并测试

1. 启动网关

bash

# 安装并启动网关
openclaw gateway install

# 检查网关状态
openclaw gateway status

# 查看实时日志
openclaw logs --follow

网关启动成功的标志：
✅ Gateway: running (pid xxxxx, state active)
✅ Gateway target: ws://127.0.0.1:18789
✅ Source: local loopback

2. 发布送测试消息

在飞书中找到您创建的机器人，发布送一条消息，例如："hi"。

在日志中应该能看到：
HEARTBEAT_OK
hi
connected | running
agent main | session main (heartbeat) | local-antigravity/gemini-3-pro-high

3. 配对授权

默认情况下（dmPolicy: "pairing"），机器人会回复一个 配对码。您需要批准此代码：

bash

# 查看待审批的配对请求
openclaw pairing list feishu

# 批准配对（替换 <配对码> 为实际收到的代码）
openclaw pairing approve feishu <配对码>

# 示例
openclaw pairing approve feishu ABC123

批准后即可正常对话。

如果不想使用配对模式：

json

{
  "channels": {
    "feishu": {
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  }
}

9.1.6 访问控制

私聊访问

默认策略：dmPolicy: "pairing"，陌生用户会收到配对码

批准配对：

bash

openclaw pairing list feishu           # 查看待审批列表
openclaw pairing approve feishu <CODE> # 批准

白名单模式：通过 channels.feishu.allowFrom 配置允许的用户 Open ID

群组访问

1. 群组策略（channels.feishu.groupPolicy）：

"open" = 允许群组中所有人（默认）
"allowlist" = 仅允许 groupAllowFrom 中的用户
"disabled" = 禁用群组消息

2. @提及要求（channels.feishu.groups.<chat_id>.requireMention）：

true = 需要 @机器人才响应（默认）
false = 无需 @也响应

9.1.7 群组配置示例

允许所有群组，需要 @提及（默认行为）

json

{
  "channels": {
    "feishu": {
      "groupPolicy": "open"
      // 默认 requireMention: true
    }
  }
}

允许所有群组，无需 @提及

需要为特定群组配置：

json

{
  "channels": {
    "feishu": {
      "groups": {
        "oc_xxx": { "requireMention": false }
      }
    }
  }
}

仅允许特定用户在群组中使用

json

{
  "channels": {
    "feishu": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["ou_xxx", "ou_yyy"]
    }
  }
}

9.1.8 获取群组/用户 ID

获取群组 ID（chat_id）

群组 ID 格式为 oc_xxx，可以通过以下方式获取：

方法一（推荐）：

启动网关并在群组中 @机器人发布消息
运行 openclaw logs --follow 查看日志中的 chat_id

方法二：使用飞书 API 调试工具获取机器人所在群组列表。

获取用户 ID（open_id）

用户 ID 格式为 ou_xxx，可以通过以下方式获取：

方法一（推荐）：

启动网关并给机器人发布消息
运行 openclaw logs --follow 查看日志中的 open_id

方法二：查看配对请求列表，其中包含用户的 Open ID：

bash

openclaw pairing list feishu

9.1.9 高级配置

自定义菜单

添加常用命令在菜单上

这里我新建了三个常用命令：新建对话，列出技能，继续。

多账号配置

OpenClaw 支持同时管理多个飞书机器人，这在以下场景非常有用：

不同团队使用不同的机器人
测试环境和生产环境分离
不同功能的专用机器人
主备机器人配置

基础配置示例（2个机器人）：

json

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "bot1": {
          "appId": "cli_xxxxxxxxxxxxxxxx",
          "appSecret": "your-app-secret-1",
          "botName": "OpenClaw助手1",
          "enabled": true
        },
        "bot2": {
          "appId": "cli_yyyyyyyyyyyyyyyy",
          "appSecret": "your-app-secret-2",
          "botName": "OpenClaw助手2",
          "enabled": true
        }
      },
      "domain": "feishu",
      "groupPolicy": "open",
      "connectionMode": "websocket",
      "requireMention": true,
      "renderMode": "auto",
      "streaming": true,
      "blockStreaming": true,
      "replyToMode": "all"
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "your-secure-token-here"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "your-provider/your-model"
      },
      "workspace": "/path/to/your/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}

💡 实战提示：上面的配置示例来自真实的多机器人部署案例。注意 appSecret 和 token 在生产环境中应该妥善保管，不要提交到代码仓库。

多机器人配置示例（4个专业助手）：

json

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main-assistant": {
          "appId": "cli_main_xxxxxx",
          "appSecret": "your-main-secret",
          "botName": "主助理",
          "enabled": true
        },
        "content-creator": {
          "appId": "cli_content_xxxxxx",
          "appSecret": "your-content-secret",
          "botName": "内内容创作助手",
          "enabled": true
        },
        "tech-dev": {
          "appId": "cli_tech_xxxxxx",
          "appSecret": "your-tech-secret",
          "botName": "技术开发布助手",
          "enabled": true
        },
        "ai-news": {
          "appId": "cli_news_xxxxxx",
          "appSecret": "your-news-secret",
          "botName": "AI资讯助手",
          "enabled": true
        }
      },
      "domain": "feishu",
      "groupPolicy": "open",
      "connectionMode": "websocket",
      "requireMention": true,
      "streaming": true,
      "blockStreaming": true,
      "replyToMode": "all"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4"
      },
      "workspace": "/path/to/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}

⚠️ 重要提示：在多账号配置中，不需要使用 bindings 来绑定不同的 agent。所有机器人会自动共分享 agents.defaults 配置。如果需要不同的模型，可以在对话中使用 /model 命令切换。

配置说明：

参数	说明	必填
`accounts.<id>`	账号唯一标识符（自定义）	✅
`appId`	飞书应用的 App ID	✅
`appSecret`	飞书应用的 App Secret	✅
`botName`	机器人显示名称	❌
`enabled`	是否启用该账号	❌ (默认 true)

多机器人使用场景：

一人公司/独立开发布者
- 主助理：任务分发布、日程管理
- 内内容创作助手：文章节、视频脚本
- 技术开发布助手：代码开发布、调试
- AI资讯助手：行业动态追踪
团队协作
- 技术团队助手：代码审查、技术讨论
- 产品团队助手：需求分析、用户反馈
- 运营团队助手：数据分析、内内容运营
- 测试助手：测试环境专用
环境分离
- 生产环境助手：正式业务使用
- 测试环境助手：功能测试
- 开发布环境助手：开发布调试

重要

在 事件订阅 页面：

步骤1：选择长连接模式

选择 使用长连接接收事件（WebSocket 模式）

步骤2：添加事件
2. 添加事件：im.message.receive_v1（接收消息）

步骤3：配置必需权限
3. 在 权限管理 页面，确保已添加：

✅ im:message（获取与发布送单聊、群组消息）
✅ im:message:send_as_bot（以应用身份发布消息）
✅ contact:contact.base:readonly（获取通讯附录基本信息）⭐ 必需

💡 缺少 contact:contact.base:readonly 权限会导致机器人无法识别用户，无法正常响应消息。

添加事件：im.message.receive_v1（接收消息）

实战场景1：团队分离

为不同团队创建专用机器人：

json

{
  "channels": {
    "feishu": {
      "accounts": {
        "tech-team": {
          "appId": "cli_tech_xxx",
          "appSecret": "tech_secret",
          "botName": "技术团队助手",
          "enabled": true
        },
        "sales-team": {
          "appId": "cli_sales_xxx",
          "appSecret": "sales_secret",
          "botName": "销售团队助手",
          "enabled": true
        },
        "hr-team": {
          "appId": "cli_hr_xxx",
          "appSecret": "hr_secret",
          "botName": "HR助手",
          "enabled": true
        }
      }
    }
  }
}

实战场景2：环境分离

测试环境和生产环境使用不同的机器人：

json

{
  "channels": {
    "feishu": {
      "accounts": {
        "production": {
          "appId": "cli_prod_xxx",
          "appSecret": "prod_secret",
          "botName": "OpenClaw生产环境",
          "enabled": true,
          "dmPolicy": "pairing"
        },
        "staging": {
          "appId": "cli_staging_xxx",
          "appSecret": "staging_secret",
          "botName": "OpenClaw测试环境",
          "enabled": true,
          "dmPolicy": "open"
        },
        "development": {
          "appId": "cli_dev_xxx",
          "appSecret": "dev_secret",
          "botName": "OpenClaw开发布环境",
          "enabled": false
        }
      }
    }
  }
}

实战场景3：功能分离

不同功能使用专用机器人：

json

{
  "channels": {
    "feishu": {
      "accounts": {
        "general": {
          "appId": "cli_general_xxx",
          "appSecret": "general_secret",
          "botName": "通用助手",
          "enabled": true
        },
        "code-review": {
          "appId": "cli_code_xxx",
          "appSecret": "code_secret",
          "botName": "代码审查助手",
          "enabled": true
        },
        "document": {
          "appId": "cli_doc_xxx",
          "appSecret": "doc_secret",
          "botName": "文档助手",
          "enabled": true
        }
      }
    }
  }
}

配合多 Agent 使用

将不同的飞书机器人绑定到不同的 Agent，实现更精细的功能分离：

json

{
  "agents": {
    "list": [
      {
        "id": "general-agent",
        "workspace": "/home/user/general",
        "agentDir": "/home/user/.openclaw/agents/general/agent"
      },
      {
        "id": "code-agent",
        "workspace": "/home/user/code-review",
        "agentDir": "/home/user/.openclaw/agents/code/agent"
      },
      {
        "id": "doc-agent",
        "workspace": "/home/user/document",
        "agentDir": "/home/user/.openclaw/agents/doc/agent"
      }
    ]
  },
  "channels": {
    "feishu": {
      "accounts": {
        "general": {
          "appId": "cli_general_xxx",
          "appSecret": "general_secret",
          "botName": "通用助手"
        },
        "code-review": {
          "appId": "cli_code_xxx",
          "appSecret": "code_secret",
          "botName": "代码审查助手"
        },
        "document": {
          "appId": "cli_doc_xxx",
          "appSecret": "doc_secret",
          "botName": "文档助手"
        }
      }
    }
  },
  "bindings": [
    {
      "agentId": "general-agent",
      "match": {
        "channel": "feishu",
        "account": "general"
      }
    },
    {
      "agentId": "code-agent",
      "match": {
        "channel": "feishu",
        "account": "code-review"
      }
    },
    {
      "agentId": "doc-agent",
      "match": {
        "channel": "feishu",
        "account": "document"
      }
    }
  ]
}

管理多个机器人

bash

# 查看所有渠道状态
openclaw channels list

# 启用/禁用特定账号：通过修改配置文件控制
# 编辑 ~/.openclaw/channels/feishu.json，设置 "enabled": true/false

# 重启网关使配置生效
openclaw gateway restart

# 查看特定渠道的日志
openclaw channels logs feishu

配置文件位置

bash

# 主配置文件
~/.openclaw/openclaw.json

# 或者使用独立的渠道配置文件
~/.openclaw/channels/feishu.json

独立配置文件示例：

bash

# 创建独立配置文件
mkdir -p ~/.openclaw/channels
nano ~/.openclaw/channels/feishu.json

json

{
  "enabled": true,
  "accounts": {
    "main": {
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "botName": "主机器人"
    },
    "backup": {
      "appId": "cli_yyy",
      "appSecret": "yyy",
      "botName": "备用机器人"
    }
  }
}

注意事项：

App ID 和 App Secret 必须唯一
- 每个机器人必须使用不同的飞书应用
- 不能多个账号共用同一个 App ID
账号标识符命名规范
- 使用小写字母和连字符
- 避免使用特殊字符
- 建议使用有意义的名称（如 tech-team、production）
启用/禁用控制
- enabled: true - 账号启用，机器人会接收和处理消息
- enabled: false - 账号禁用，机器人不会接收消息
- 可以随时通过修改配置文件或命令行切换
网关重启
- 修改配置后需要重启网关：openclaw gateway restart
日志查看
- 多账号时，日志会标注账号标识符
- 使用 openclaw channels logs <channel-name> 查看特定渠道日志

故障排查：

访问题1：某个机器人收不到消息

bash

# 检查账号是否启用
openclaw channels status

# 查看该账号的日志
openclaw channels logs feishu

# 检查配置是否正确
openclaw config get channels.feishu.accounts.main

访问题2：多个机器人冲突

确保每个机器人使用不同的飞书应用：

不同的 App ID
不同的 App Secret
在飞书开放平台创建多个应用

访问题3：切换账号不生效

bash

# 重启网关使配置生效
openclaw gateway restart

访问题4：配置验证失败 - bindings 错误

Error: bindings.0.match: Unrecognized key: "account"
原因：在多账号配置中，不需要使用 bindings 来绑定 agent。

解决方案：

删除配置文件中的 bindings 部分
所有机器人会自动使用 agents.defaults 配置
如果需要不同模型，在对话中使用 /model 命令切换

正确的配置结构：

json

{
  "channels": {
    "feishu": {
      "accounts": {
        "bot1": { ... },
        "bot2": { ... }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "your-model" },
      "workspace": "/path/to/workspace"
    }
  }
  // ❌ 不需要 bindings
}

访问题5：配置后运行 openclaw doctor 报错

bash

# 运行诊断
openclaw doctor

# 如果提示配置访问题，运行自动修复
openclaw update repair
openclaw doctor

# 验证配置
openclaw doctor
# 应该看到：✅ Config valid

最佳实践：

使用有意义的账号名称

json

"accounts": {
  "prod-main": { ... },      // 生产环境主机器人
  "prod-backup": { ... },    // 生产环境备份
  "test": { ... }            // 测试环境
}

为不同环境使用不同的策略

json

"production": {
  "dmPolicy": "pairing",     // 生产环境需要配对
  "groupPolicy": "allowlist" // 群组白名单
},
"development": {
  "dmPolicy": "open",        // 开发布环境开放访问
  "groupPolicy": "open"      // 群组开放
}

定期备份配置

bash

# 备份配置文件
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 或使用 OpenClaw 备份命令
openclaw backup create

使用环境变量管理敏感信息

bash

# 在 ~/.bashrc 或 ~/.zshrc 中设置
export FEISHU_MAIN_APP_ID="cli_xxx"
export FEISHU_MAIN_APP_SECRET="xxx"
export FEISHU_BACKUP_APP_ID="cli_yyy"
export FEISHU_BACKUP_APP_SECRET="yyy"

然后在配置文件中引用：

json

{
  "channels": {
    "feishu": {
      "accounts": {
        "main": {
          "appId": "${FEISHU_MAIN_APP_ID}",
          "appSecret": "${FEISHU_MAIN_APP_SECRET}"
        }
      }
    }
  }
}

流式输出

飞书支持通过交互式卡片实现流式输出，机器人会实时更新卡片内内容显示生成进度。

json

{
  "channels": {
    "feishu": {
      "streaming": true,      // 启用流式卡片输出（默认 true）
      "blockStreaming": true  // 启用块级流式（默认 true）
    }
  }
}

如需禁用流式输出（等待完整回复后一次性发布送），可设置 streaming: false。

消息引用

在群聊中，机器人的回复可以引用用户发布送的原始消息，让对话上下文更加清晰。

json

{
  "channels": {
    "feishu": {
      "replyToMode": "all",  // 账户级别配置（默认 "all"）
      "groups": {
        "oc_xxx": {
          "replyToMode": "first"  // 特定群组可以覆盖
        }
      }
    }
  }
}

replyToMode 值说明：

"off" = 不引用原消息（私聊默认值）
"first" = 仅在第一条回复时引用原消息
"all" = 所有回复都引用原消息（群聊默认值）

多 Agent 路由

通过 bindings 配置，您可以用一个飞书机器人对接多个不同功能或性格的 Agent：

json

{
  "agents": {
    "list": [
      { "id": "main" },
      {
        "id": "clawd-fan",
        "workspace": "/home/user/clawd-fan",
        "agentDir": "/home/user/.openclaw/agents/clawd-fan/agent"
      },
      {
        "id": "clawd-xi",
        "workspace": "/home/user/clawd-xi",
        "agentDir": "/home/user/.openclaw/agents/clawd-xi/agent"
      }
    ]
  },
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "dm", "id": "ou_28b31a88..." }
      }
    },
    {
      "agentId": "clawd-fan",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "dm", "id": "ou_0fe6b1c9..." }
      }
    },
    {
      "agentId": "clawd-xi",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "group", "id": "oc_xxx..." }
      }
    }
  ]
}

9.1.10 常用命令

机器人命令

命令	说明
`/status`	查看机器人状态
`/reset`	重置对话会话
`/model`	查看/切换模型

网关管理命令

命令	说明
`openclaw gateway status`	查看网关运行状态
`openclaw gateway install`	安装/启动网关服务
`openclaw gateway stop`	停止网关服务
`openclaw gateway restart`	重启网关服务
`openclaw logs --follow`	实时查看日志输出

9.1.11 故障排除

机器人在群组中不响应

检查机器人是否已添加到群组
检查是否 @了机器人（默认需要 @提及）
检查 groupPolicy 是否为 "disabled"
查看日志：openclaw logs --follow

机器人收不到消息

可能原因及解决方案：

检查应用是否已发布布并审批通过

bash

# 在飞书开放平台查看应用状态
# 确保应用已通过审核并发布布

检查事件订阅是否配置正确
- ✅ 已选择"使用长连接接收事件"（WebSocket模式）
- ✅ 已添加事件：im.message.receive_v1
- ✅ 长连接状态显示"已连接"

检查权限配置是否完整⭐ 重要

缺少权限会导致机器人无法正常工作，请确保已添加以下权限：

权限标识	权限名称	检查方法
`im:message`	获取与发布送单聊、群组消息	在权限管理页面查看
`im:message:send_as_bot`	以应用身份发布消息	在权限管理页面查看
`contact:contact.base:readonly`	获取通讯附录基本信息	⭐ 必需，否则无法识别用户

如何检查权限：

登录飞书开放平台
进入你的应用
点击"权限管理"
确认上述三个权限都已添加
如果缺少，点击"添加权限"补充

text

**常见错误**：
- ❌ 只添加了 `im:message`，忘记添加 `contact:contact.base:readonly`
- ❌ 权限添加后未重新发布布应用
- ❌ 权限范围设置不正确

检查网关状态

bash

# 查看网关是否正常运行
openclaw gateway status

# 查看实时日志
openclaw logs --follow

检查渠道配置

bash

# 查看飞书渠道配置
openclaw channels list

# 确认 appId 和 appSecret 正确
openclaw config get channels.feishu

检查应用是否已发布布并审批通过
检查事件订阅是否配置正确（im.message.receive_v1）
检查是否选择了 长连接 模式
检查应用权限是否完整
检查网关是否正在运行：openclaw gateway status
查看实时日志：openclaw logs --follow

配置文件 JSON 语法错误

错误示例：
JSON5 parse error at line 443: Python True/False vs JSON true/false
解决方案：

bash

# 检查 JSON 语法
cat ~/.openclaw/openclaw.json | python -m json.tool

# 常见错误：
# ❌ "enabled": True   (Python 语法)
# ✅ "enabled": true   (JSON 语法)

# ❌ 多余的逗号
# ✅ 最后一项不要逗号

网关启动失败

错误1：Gateway start blocked

bash

# 错误信息
Gateway start blocked: set gateway.mode=local (current: unset)

# 解决方案：在配置文件中添加
{
  "gateway": {
    "mode": "local"
  }
}

错误2：Gateway auth token 未配置

bash

# 错误信息
Gateway auth is set to token, but no token is configured

# 解决方案1：配置文件
{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-secure-token"
    }
  }
}

# 解决方案2：环境变量
export OPENCLAW_GATEWAY_TOKEN="your-secure-token"

错误3：插件未找到

bash

# 错误信息
Config validation failed: plugins.entries.qqbot: plugin not found: qqbot

# 解决方案：移除未安装的插件配置
{
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
      // 移除 qqbot, ddingtalk, wecom 等未安装的插件
    }
  }
}

错误4：工作空间路径错误

bash

# 错误信息
run error: Error: ENOENT: no such file or directory, mkdir '/root'

# 解决方案：修正 workspace 路径（macOS 示例）
{
  "agents": {
    "defaults": {
      "workspace": "/Users/yourusername/clawd"  // 使用正确的 macOS 路径
    }
  }
}

App Secret 泄露怎么怎么办

在飞书开放平台重置 App Secret
更新配置文件中的 App Secret
重启网关：openclaw gateway restart

发布送消息失败

检查应用是否有 im:message:send_as_bot 权限
检查应用是否已发布布
查看日志获取详细错误信息：openclaw logs --follow

网关端口被占用

bash

# 错误信息
Port 18789 is already in use

# 解决方案1：停止现有网关
openclaw gateway stop

# 解决方案2：使用不同端口
{
  "gateway": {
    "port": 18790
  }
}

配置修改不生效

bash

# 修改配置后必须重启网关
openclaw gateway restart

# 检查配置是否正确加载
openclaw config get channels.feishu

/* Detailed source-code truncated for AI context efficiency. */

json

{
  "meta": {
    "lastTouchedVersion": "2026.2.6-3",
    "lastTouchedAt": "2026-02-08T09:49:58.322Z"
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "bot1": {
          "appId": "cli_xxxxxxxxxxxxxxxx",
          "appSecret": "your-app-secret-1",
          "botName": "OpenClaw助手1",
          "enabled": true
        },
        "bot2": {
          "appId": "cli_yyyyyyyyyyyyyyyy",
          "appSecret": "your-app-secret-2",
          "botName": "OpenClaw助手2",
          "enabled": true
        }
      },
      "domain": "feishu",
      "groupPolicy": "open",
      "connectionMode": "websocket",
      "requireMention": true,
      "renderMode": "auto",
      "streaming": true,
      "blockStreaming": true,
      "replyToMode": "all"
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "your-secure-random-token-here"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "your-model-provider/your-model"
      },
      "workspace": "/path/to/your/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4
    }
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  }
}

3. 配置飞书应用权限

为两个应用分别配置权限（批量导入 JSON，参见 9.1.3 节）。

4. 配置事件订阅

为两个应用分别配置：

选择 使用长连接接收事件
添加事件：im.message.receive_v1

5. 启动网关

bash

# 启动网关
openclaw gateway install

# 检查状态
openclaw gateway status

# 应该看到：
# ✅ Gateway: running (pid 57344, state active)
# ✅ Gateway target: ws://127.0.0.1:18789

6. 测试机器人

在飞书中分别给两个机器人发布送消息：

你：hi
机器人：[配对码] 请管理员批准配对
7. 批准配对

bash

# 查看配对请求
openclaw pairing list feishu

# 批准机器人1
openclaw pairing approve feishu <配对码1>

# 批准机器人2
openclaw pairing approve feishu <配对码2>

8. 验证运行

查看日志确认两个机器人都在正常运行：

bash

openclaw logs --follow

# 应该看到：
# HEARTBEAT_OK
# hi
# connected | running
# agent main | session main (heartbeat)

常见访问题处理

访问题1：配置文件 JSON 语法错误

bash

# 错误：JSON5 parse error at line 443
# 原因：使用了 Python 语法（True/False）而非 JSON 语法（true/false）

# 检查语法
cat ~/.openclaw/openclaw.json | python -m json.tool

# 修正：
# ❌ "enabled": True
# ✅ "enabled": true

访问题2：网关启动失败

bash

# 错误：Gateway start blocked: set gateway.mode=local
# 解决：确保配置了 gateway.mode

{
  "gateway": {
    "mode": "local"
  }
}

访问题3：工作空间路径错误

bash

# 错误：ENOENT: no such file or directory, mkdir '/root'
# 原因：配置文件中使用了 Linux 路径，但实际是 macOS

# 修正（macOS）：
{
  "agents": {
    "defaults": {
      "workspace": "/Users/yourusername/clawd"
    }
  }
}

访问题4：插件未找到

bash

# 错误：plugin not found: qqbot
# 原因：配置文件中引用了未安装的插件

# 解决：只保留已安装的插件
{
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
      // 移除 qqbot, ddingtalk, wecom 等
    }
  }
}

配置检查清单

两个飞书应用已创建
App ID 和 App Secret 已获取
配置文件 JSON 语法正确
gateway.mode 已设置为 "local"
gateway.auth.token 已配置
workspace 路径正确（macOS/Linux）
只配置了已安装的插件
两个应用的权限已配置
两个应用的事件订阅已配置（长连接）
两个应用已发布布
网关已启动并运行正常
两个机器人都已配对批准
日志显示正常运行

成功标志

配置成功后，你应该看到：

bash

# 网关状态
$ openclaw gateway status
✅ Gateway: running (pid xxxxx, state active)
✅ Gateway target: ws://127.0.0.1:18789

# 日志输出
$ openclaw logs --follow
HEARTBEAT_OK
hi
connected | running
agent main | session main (heartbeat) | your-model-provider/your-model
tokens 25k/200k (13%)

两个机器人都可以正常接收和回复消息！🎉

9.4 QQ Bot配置

9.4.1 QQ机器人介绍

QQ的优势：

用户基础
- 用户量大
- 覆盖面广
- 使用习惯
社交属性
- 群聊活跃
- 互动性强
- 娱乐功能
开放平台
- QQ频道
- QQ群机器人
- API支持
免费使用
- 基础功能免费
- 易于上手

9.4.2 创建QQ机器人

⚠️ 重要提示：QQ开放平台需要先注册账号，不是直接用QQ登录！请务必先完成注册。

步骤1：注册QQ开放平台账号

访问QQ开放平台：
https://q.qq.com/
text
注册新账号：
- ⚠️ 不是QQ登录，需要单独注册
- 点击"注册"按钮
- 填写注册信息
- 完成邮箱/手机验证
登录平台：
- 使用刚注册的账号登录
- 不要使用QQ扫码登录

步骤2：创建机器人

进入机器人管理：
- 登录后点击"机器人"
- 点击"创建机器人"
填写机器人信息：
- 机器人名称：自定义（如：我的AI助手）
- 机器人头像：上传图片
- 机器人简介：简单描述功能
- 点击"创建"
等待审核：
- 提交后等待审核（通常几分钟）
- 审核通过后即可使用

步骤3：配置机器人

获取机器人凭证：
- 进入机器人详情页
- 点击"开发布管理"
- 记附录以下信息：
  - 机器人ID（BotAppID）
  - 机器人密钥（Bot Secret）
配置IP白名单：
- 在"开发布管理"页面
- 找到"IP白名单"设置
- 添加你的服务器公网IP地址
- 点击"保存"
添加测试用户：
- 在"管理" → "成员管理"
- 点击"添加成员"
- 输入你的QQ号
- 将自己添加为测试用户
扫码添加机器人好友：
- 在机器人详情页找到二维码
- 用手机QQ扫码
- 添加机器人为好友

步骤4：配置 OpenClaw连接

获取服务器IP地址：
- 如果使用腾讯云，在控制台查看公网IP
- 记附录这个IP地址
在腾讯云Lighthouse配置（如果使用腾讯云）：
- 登录腾讯云：https://console.cloud.tencent.com/lighthouse
- 进入实例详情
- 点击"应用管理"标签
- 找到"QQ机器人配置"区域
- 填入：
  - 机器人ID（BotAppID）
  - 机器人密钥（Bot Secret）
- 点击"应用配置"

本地配置方式：

bash

# 运行配置向导
openclaw onboard

# 选择 QuickStart
# 选择模型（如 Kimi 2.5）
# 输入模型 API Key
# 选择通道：QQ
# 输入机器人ID和密钥

9.4.3 配置 OpenClaw

💡 前置要求：请先完成 OpenClaw 的基础安装和配置，详见第2章节：环境搭建。

方式一：使用腾讯云Lighthouse（推荐）

如果你使用腾讯云Lighthouse部署OpenClaw，配置非常简单：

进入应用管理：
- 登录腾讯云控制台
- 进入轻量应用服务器
- 点击实例 → "应用管理"
配置QQ机器人：
- 找到"QQ机器人配置"区域
- 填入机器人ID和密钥
- 点击"应用配置"
- 等待配置生效
验证连接：
- 打开手机QQ
- 给机器人发布送消息："你好"
- 如果收到回复，说明配置成功

方式二：本地配置

如果你是本地部署或其他云服务器，使用命令行配置：

bash

# 1. 运行配置向导
openclaw onboard

# 2. 选择配置选项
# - 选择 Yes 接受风险
# - 选择 QuickStart（快速开始）

# 3. 配置模型
# - 选择模型供应商（如 Moonshot AI）
# - 输入 API Key
# - 选择默认模型（如 kimi-code/kimi-for-codi）

# 4. 配置通道
# - 选择通道：QQ
# - 输入机器人ID（BotAppID）
# - 输入机器人密钥（Bot Secret）

# 5. 配置Skills和Hooks
# - Skills：选择 Yes，可以先不安装
# - Hooks：选择 session-memory

# 6. 重启服务
# - 选择 Yes 重启 gateway 服务

# 7. 测试连接
# - 选择打开 TUI（终端界面）
# - 或直接在QQ中测试

方式三：手动编辑配置文件

bash

# 编辑配置文件
nano ~/.openclaw/config.json

# 添加QQ配置
{
  "channels": {
    "qq": {
      "enabled": true,
      "botAppId": "你的机器人ID",
      "botSecret": "你的机器人密钥",
      "profiles": ["default"]
    }
  }
}

# 重启服务
systemctl --user restart openclaw-gateway.service

启动Gateway服务

bash

# 方式1：前台运行（用于测试）
openclaw gateway --port 18789 --verbose

# 方式2：后台运行（推荐）
nohup openclaw gateway --port 18789 --verbose > /dev/null 2>&1 &

# 方式3：使用systemd（最稳定）
systemctl --user enable openclaw-gateway.service
systemctl --user start openclaw-gateway.service

验证配置

bash

# 查看服务状态
systemctl --user status openclaw-gateway.service

# 查看日志
journalctl --user -u openclaw-gateway.service -f

# 测试连接
# 在QQ中给机器人发布送消息："你好"

9.4.4 实战案例

案例1：个人助手
功能：

日常对话
信息查询
任务提醒
娱乐互动

使用示例：
你：今天天气怎么样？
OpenClaw：今天晴天，15-25°C

你：提醒我明天交作业
OpenClaw：已设置提醒 ✅
案例2：群管理
功能：

群公告
成员管理
消息统计
自动回复

使用示例：
管理员：@OpenClaw 发布布公告
OpenClaw：公告已发布布 ✅

成员：@OpenClaw 查询群规
OpenClaw：群规如下...
案例3：娱乐互动
功能：

聊天对话
讲笑话
猜谜语
玩游戏

使用示例：
你：讲个笑话
OpenClaw：好的，听我说...

你：猜谜语
OpenClaw：什么东西...

9.4.5 限制和注意事项

功能限制：
⚠️ QQ机器人有以下限制：

消息频率限制
功能权限限制
审核要求严格
部分API需要申请
目前不支持主动发布送消息（2026.2.6测试）
注意事项：
✅ 遵守平台规则
✅ 不发布送违规内内容
✅ 合理使用API
✅ 及时响应用户
✅ 定期检查服务状态
常见访问题：

机器人不回复消息：
- 检查IP白名单是否正确
- 检查机器人ID和密钥是否正确
- 查看Gateway服务是否运行
- 检查服务器日志
配置后无法连接：
- 确认已添加为测试用户
- 确认已添加机器人好友
- 重启Gateway服务
- 检查防火墙设置
消息延迟：
- 检查网络连接
- 检查服务器负载
- 考虑升级服务器配置

9.6 Discord Bot配置（参考）

⚠️ 过时提示：本节内内容编写于2026年1月，当时OpenClaw还叫Clawbot/Moltbot。虽然部分命令已过时，但配置流程仍可作为参考。

9.5.1 Discord机器人介绍

Discord的优势：

国际化平台
- 全球用户基础
- 多语言支持
- 社区活跃
开发布友好
- API完善
- 文档详细
- 权限灵活
功能丰富
- 支持语音频道
- 支持富文本
- 支持自定义表情

适用场景：

✅ 国际团队协作
✅ 游戏社区
✅ 开源项目
✅ 技术交流

9.5.2 创建Discord机器人

步骤1：访问开发布者门户

https://discord.com/developers/applications
步骤2：创建应用

点击"New Application"
输入应用名称（如：My OpenClaw Bot）
点击"Create"

步骤3：创建Bot

在左侧菜单选择"Bot"
点击"Add Bot"
点击"Reset Token" → "Copy"
⚠️ 保存Token，后续无法再查看

步骤4：配置Bot权限

在Bot页面下滑
开启"Message Content Intent"
点击"Save Changes"

步骤5：生成邀请链接

在左侧菜单选择"OAuth2" → "URL Generator"
在"Scopes"中勾选：bot
在"Bot Permissions"中勾选：
- Send Messages
- Read Message History
复制生成的URL

步骤6：邀请Bot到服务器

在浏览器中打开刚才复制的URL
选择你的Discord服务器
点击"授权"
完成验证

9.5.3 配置 OpenClaw（旧版命令参考）

⚠️ 注意：以下命令使用的是旧版本的clawdbot命令，新版本应使用openclaw。

配置步骤（需要更新为新命令）：

bash

# 旧版命令（仅供参考）
clawdbot onboard

# 新版命令（推荐）
openclaw onboard

# 配置流程：
# 1. 选择 Yes 接受风险
# 2. 选择 QuickStart
# 3. 配置模型（如 GLM 4.7）
# 4. 选择通道：Discord
# 5. 输入 Bot Token
# 6. 配置 Skills 和 Hooks

启动服务：

bash

# 旧版命令
clawdbot gateway --port 18789 --verbose

# 新版命令
openclaw gateway --port 18789 --verbose

# 后台运行
nohup openclaw gateway --port 18789 --verbose > /dev/null 2>&1 &

配对连接：

bash

# 1. 在Discord中私聊Bot，获取配对码
# 2. 停止Gateway服务（Ctrl+C）
# 3. 运行配对命令（旧版）
clawdbot pairing approve discord 

# 新版命令（需要确认）
openclaw pairing approve discord 

# 4. 重新启动Gateway
openclaw gateway --port 18789 --verbose

9.5.4 使用Discord Bot

私聊模式：

在Discord中找到你的Bot
点击Bot头像
点击"发布送消息"
直接发布送消息即可
群聊模式：
在频道中@Bot
输入你的访问题
Bot会回复你

示例：
@MyBot 今天天气怎么样？

9.5.5 注意事项

命令更新：

本节使用的clawdbot命令已过时
新版本统一使用openclaw命令
配置流程基本相同，但命令需要更新

配置参考：

Discord的配置流程仍然有效
Bot创建步骤没有变化
主要是OpenClaw 命令需要更新

推荐做法：

优先使用国内平台（飞书、QQ、企微）
Discord适合国际团队
如需使用Discord，请参考最新官方文档

9.5 微信接入（ClawBot 官方方案）

💡 状态：公测中（2026年3月随橙皮书 v1.4 发布），基于 WeChatFerry 开源项目。

9.5.1 ClawBot 是什么

ClawBot 是 OpenClaw 官方提供的微信接入插件，让你可以在个人微信中直接与 OpenClaw 智能体对话。

核心特点：

官方维护：由 OpenClaw 团队开发和维护，质量有保障
基于 WeChatFerry：使用成熟的 WeChatFerry 开源 hook 方案
插件式安装：一行命令即可安装，无需手动编译
实时收发消息：支持私聊和群聊消息的监听与回复

适用人群：

微信重度用户，希望在微信中使用 AI 助手
需要微信群自动化运营（如客户群自动回复）
已有 OpenClaw 部署环境，想扩展微信渠道

9.5.2 安装步骤

前提条件：

已完成 OpenClaw 基础安装（参考第2章）
Windows 系统已登录微信 PC 客户端
微信版本需与 WeChatFerry 兼容（查看官方文档获取支持的版本列表）

第一步：安装 ClawBot 插件

bash

# 安装官方微信插件
openclaw plugins install @openclaw/wechat-clawbot

# 验证安装
openclaw plugins list | grep wechat

第二步：配置微信连接

bash

# 编辑配置文件
openclaw config edit

# 或直接设置
openclaw config set channels.wechat.enabled true

第三步：启动并测试

bash

# 启动 Gateway（会自动加载已安装的插件）
openclaw gateway --port 18789

# 在另一个终端查看日志
openclaw gateway logs --follow

启动成功后，在微信中给"文件传输助手"发送测试消息，确认 ClawBot 正常工作。

9.5.3 工作原理

text

微信PC客户端
    │
    ↓ （WeChatFerry Hook）
┌──────────────┐
│  ClawBot 插件  │ ← 监听微信消息事件
└──────┬───────┘
       │
       ↓ （WebSocket）
┌──────────────┐
│ OpenClaw核心  │ ← AI推理 + Skills处理
└──────┬───────┘
       │
       ↓ （消息回复）
┌──────────────┐
│  ClawBot 插件  │ ← 通过微信API发送回复
└──────┬───────┘
       │
       ↓
微信PC客户端

流程说明：

ClawBot 通过 WeChatFerry 库 hook 微信 PC 客户端的消息接口
当收到新消息时，ClawBot 将消息转发给 OpenClaw 核心
OpenClaw 核心调用 AI 模型生成回复（支持所有已配置的模型）
回复通过 ClawBot 发送回微信

9.5.4 与第三方方案对比

特性	ClawBot（官方）	WeChatFerry（原始）	ComWeChatBot	wxbot
维护方	OpenClaw 官方	社区	社区	社区
安装难度	⭐（一行命令）	⭐⭐⭐（手动编译）	⭐⭐⭐	⭐⭐
与 OpenClaw 集成	✅ 原生集成	❌ 需自行开发	❌ 需自行开发	❌ 需自行开发
Skills 支持	✅ 完整支持	❌	❌	❌
稳定性	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐⭐
更新频率	跟随 OpenClaw	社区驱动	较低	社区驱动
推荐度	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐⭐

推荐使用 ClawBot 的理由：

原生集成，无需额外开发
完整支持 OpenClaw 的 Skills 和 Agent 能力
官方维护，更新及时
一行命令安装，配置简单

9.5.5 配置与使用

基本配置：

yaml

# config.yaml 中的微信渠道配置
channels:
  wechat:
    enabled: true
    # 监听的群聊（留空则监听所有群）
    groups:
      - "群名称1"
      - "群名称2"
    # 是否响应私聊
    private_chat: true
    # 自动回复的前缀（用于区分AI回复）
    reply_prefix: "[AI] "

使用技巧：

群聊场景：在群聊中 @机器人或使用特定关键词触发回复
私聊场景：直接发送消息即可获得 AI 回复
多群管理：可以为不同群配置不同的 Agent 人设（通过 SOUL.md）
消息格式：支持 Markdown 格式回复，包含代码块、表格等

9.5.6 注意事项

⚠️ 重要风险提示

个人微信风险
- ClawBot 基于 hook 方案，本质上是对微信客户端的逆向操作
- 虽然基于成熟的开源项目，但仍存在被封号的风险
- 强烈建议使用小号或专用微信号，不要使用主力微信号
封号风险
- 频繁自动回复可能触发微信的风控机制
- 建议设置回复频率限制（如每分钟最多回复 10 条）
- 避免在群聊中发送大量相同内容
合规建议
- 仅用于个人学习和研究用途
- 不要用于商业营销、垃圾消息发送等违规用途
- 遵守微信平台的使用条款
技术限制
- 目前仅支持 Windows 平台（依赖微信 PC 客户端）
- 微信版本更新可能导致兼容性问题，需及时关注更新

9.6 浏览器渠道（Dashboard v2）

💡 状态：稳定可用，随橙皮书 v1.3 发布 Dashboard v2 全新管理后台。

9.6.1 什么是浏览器渠道

浏览器渠道是 OpenClaw 提供的最简单的使用方式——直接在浏览器中使用 OpenClaw，无需安装任何客户端或 IM 平台。

只需在浏览器中打开 Dashboard 地址，就可以：

与 AI 智能体对话
管理理 Skills 和配置
查看运行日志和状态
上传文件和知识库

9.6.2 适用场景

场景	说明
临时使用	在别人电脑或公共电脑上临时使用，不想安装软件
公司电脑受限	公司电脑无法安装新软件，但浏览器可以上网
多设备切换	在不同电脑上通过浏览器统一访问
团队演示	通过浏览器向同事演示 OpenClaw 的功能
快速体验	想快速体验 OpenClaw，不想折腾客户端安装

9.6.3 访问方式与功能

访问地址：

text

http://127.0.0.1:18789/

如果是远程服务器部署，将 127.0.0.1 替换为服务器 IP：

text

http://你的服务器IP:18789/?token=你的访问令牌

Dashboard v2 新功能（橙皮书 v1.3 发布）：

全新 UI 设计：更直观的数据展示和配置界面
实时对话：支持流式输出，体验更流畅
Skills 管理：直接在浏览器中安装、启用、禁用 Skills
模型切换：可视化切换不同 AI 模型
知识库管理：上传和管理知识库文件
日志查看：实时查看 Gateway 运行日志
多用户支持：支持多用户同时在线使用

安全建议：

本地使用无需特别配置
远程访问务必设置 token 认证
生产环境建议配置 HTTPS
使用防火墙限制访问来源 IP

9.7 平台对比与选择

9.7.1 功能对比

功能	飞书	企业微信	钉钉	QQ	微信（ClawBot）
企业怎么办公	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐	⭐
即时通讯	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
文档协作	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐	⭐
开发布友好	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐
用户基础	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
免费额度	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐

9.7.2 使用场景推荐

飞书：
✅ 适合场景：

现代化怎么办公
文档协作
知识管理
团队协作
技术团队

❌ 不适合：

传统企业
简单需求
企业微信：
✅ 适合场景：
企业内部使用
需要与微信互通
客户服务
营销推广

❌ 不适合：

纯个人使用
需要复杂文档协作
钉钉：
✅ 适合场景：
企业怎么办公
考勤管理
审批流程
项目管理

❌ 不适合：

个人娱乐
社交互动
QQ：
✅ 适合场景：
个人使用
社交互动
娱乐功能
学生群体

❌ 不适合：

企业怎么办公
正式场合
微信（ClawBot）：
✅ 适合场景：
个人微信自动化
微信群智能回复
客户群运营
微信重度用户

❌ 不适合：

企业正式办公
大规模商业运营（有封号风险）
对稳定性要求极高的场景

9.7.3 多平台组合策略

策略1：工作+生活分离
工作：飞书/企业微信/钉钉
生活：QQ

优势：

工作生活分离
专注度更高
管理更方便
策略2：全平台覆盖
同时接入所有平台

优势：

覆盖所有用户
随时随地使用
功能互补

劣势：

维护成本高
消息分散
策略3：主次搭配（推荐）
主平台：飞书（日常使用）
辅平台：企业微信（客户沟通）

优势：

重点突出
成本可控
易于管理

📝 本章节小结

本章节学习了OpenClaw的多平台集成功能：

核心内内容

飞书Bot配置
- 创建飞书应用
- 配置 OpenClaw
- 实战案例（个人助手、项目管理）
- 与飞书生态集成
- 高级功能（流式输出、多Agent路由）
企业微信Bot配置
- 注册和创建应用
- 配置 OpenClaw
- 实战案例（个人助手、团队协作、客户服务）
- 手机端使用技巧
钉钉Bot配置
- 创建钉钉应用
- 配置 OpenClaw
- 实战案例（工作助手、审批流程）
QQ Bot配置
- 创建QQ机器人
- 配置 OpenClaw
- 实战案例（个人助手、群管理、娱乐互动）
- 限制和注意事项
微信接入（ClawBot 官方方案）
- 官方插件安装与配置
- 基于 WeChatFerry 的工作原理
- 与第三方方案对比
- 风险提示与注意事项
浏览器渠道（Dashboard v2）
- 零安装使用 OpenClaw
- Dashboard v2 全新功能
- 适用场景与安全建议

平台选择

飞书：现代化怎么办公、文档协作、技术团队（推荐优先）
企业微信：企业怎么办公、客户服务
钉钉：考勤管理、审批流程
QQ：个人使用、社交互动
微信：微信重度用户、群自动化（注意封号风险）
浏览器：临时使用、受限环境、快速体验

实战技巧

✅ 选择合适的平台
✅ 合理配置权限
✅ 优化使用体验
✅ 多平台组合使用
✅ 遵守平台规则

下一步

学习第10章节：API服务封装
掌握Banana绘图、Notion同步等
构建多功能AI工具箱

🎯 实战练习

练习1：配置飞书Bot

注册飞书开放平台
创建应用
配置 OpenClaw
测试文档集成

练习2：配置企业微信Bot

注册企业微信
创建应用
配置 OpenClaw
测试基本功能

练习3：多平台对比

分别体验4个平台
对比功能差异
选择适合自己的平台

💡 常见访问题

Q1：哪个平台最好用？
A：看使用场景。技术团队推荐飞书（开发布友好、功能强大），企业用飞书/钉钉，个人用QQ，客户服务用企业微信。

Q2：可以同时接入多个平台吗？
A：可以，OpenClaw支持同时接入多个平台。

Q3：配置复杂吗？
A：云端部署很简单，参考官方教程即可。飞书配置最简单，支持WebSocket长连接。

Q4：免费吗？
A：平台基础功能都免费，OpenClaw也免费。

Q5：手机上能用吗？
A：可以，所有平台都支持手机端。飞书的移动端体验最好。

📚 参考资源

官方教程

飞书：

快速接入指南：https://cloud.tencent.com/developer/article/2626151
视频教程：https://cloud.tencent.com/developer/video/85055

企业微信：

快速接入指南：https://cloud.tencent.com/developer/article/2625147
视频教程：https://cloud.tencent.com/developer/video/85003

钉钉：

快速接入指南：https://cloud.tencent.com/developer/article/2626553
视频教程：https://cloud.tencent.com/developer/video/85055

QQ：

快速接入指南：https://cloud.tencent.com/developer/article/2626045
视频教程：https://cloud.tencent.com/developer/video/85003

社区资源

OpenClaw社区：https://docs.openclaw.ai
交流群：扫码加入
访问题反馈：GitHub Issues

下一章节预告：第10章节将学习API服务封装，包括Banana绘图集成、Notion数据同步、视频生成服务、语音合成接入等内内容。

9.1.16 多机器人多 Agent 模式：打造你的 AI 助手团队

💡 完整教程：本节详细介绍如何使用多 Gateway + 多飞书机器人架构，打造专业的 AI 助手团队。

9.1.16.1 为什么需要多 Agent？

作为超级个体创业者，你可能需要不同类型的 AI 助手来处理不同的工作：

主助理：使用最强大的模型（Claude Opus）处理复杂任务
内内容创作助手：专注于文章节写作、文案创作
技术开发布助手：处理代码开发布、技术访问题
AI 资讯助手：快速获取和整理 AI 行业动态

传统的单 Agent 模式需要频繁切换模型和上下文，效率低下。多 Agent 模式让你可以同时拥有多个专业助手，各司其职。

9.1.16.2 实现方案对比

方案一：单 Gateway + Bindings（不推荐）

json

{
  "bindings": [
    {
      "agentId": "main-agent",
      "match": {
        "channel": "feishu",
        "peer": {
          "kind": "group",
          "id": "oc_xxx"
        }
      }
    }
  ]
}

访问题：

❌ OpenClaw 2026.3.2 的 bindings 功能不稳定
❌ peer.id 匹配经常失败
❌ 所有群组都路由到同一个 agent
❌ 需要 /reset + /agent 命令手动切换

方案二：多 Gateway + 多飞书机器人（推荐）✅

核心思路：

创建 4 个飞书机器人应用
启动 4 个独立的 OpenClaw Gateway
每个 Gateway 连接一个飞书机器人
每个 Gateway 使用不同的 Agent 和模型

优势：

✅ 完全独立，互不干扰
✅ 直接私聊不同机器人即可切换 agent
✅ 不需要群组配置
✅ 不需要手动切换命令
✅ 配置清晰，易于管理
✅ 可以独立重启某个 Gateway

9.1.16.3 架构设计

整体架构

┌─────────────────────────────────────────────────────────┐
│ 飞书 (Feishu) │
├─────────────────────────────────────────────────────────┤
│ 机器人1: 主助理机器人2: 内内容创作助手 │
│ 机器人3: 技术开发布助手机器人4: AI资讯助手 │
└─────────────────────────────────────────────────────────┘
↓ WebSocket
┌─────────────────────────────────────────────────────────┐
│ OpenClaw Gateway 层 │
├──────────────┬──────────────┬──────────────┬────────────┤
│ Gateway 1 │ Gateway 2 │ Gateway 3 │ Gateway 4 │
│ 端口: 18789 │ 端口: 18790 │ 端口: 18791 │ 端口: 18792│
│ Profile: │ Profile: │ Profile: │ Profile: │
│ main- │ content- │ tech-dev │ ai-news │
│ assistant │ creator │ │ │
└──────────────┴──────────────┴──────────────┴────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Agent 层 │
├──────────────┬──────────────┬──────────────┬────────────┤
│ main-agent │ content-agent│ tech-agent │ainews-agent│
│ Claude Opus │ Claude Sonnet│ Claude Sonnet│ Gemini 2.5 │
│ 4.6 Thinking │ 4.5 │ 4.5 Thinking │ Flash │
└──────────────┴──────────────┴──────────────┴────────────┘

Profile 隔离机制

使用 --profile <name> 参数，OpenClaw 会：

配置文件：~/.openclaw-<name>/openclaw.json
状态数据：~/.openclaw-<name>/
独立端口：18789, 18790, 18791, 18792
独立会话：完全隔离的上下文

9.1.16.4 配置步骤

第一步：创建飞书机器人应用

在飞书开放平台创建 4 个机器人应用：

主助理
- 应用名称：主助理
- 描述：处理复杂任务的主力助手
- 获取 App ID 和 App Secret
内内容创作助手
- 应用名称：内内容创作助手
- 描述：专注内内容创作和文案写作
- 获取 App ID 和 App Secret
技术开发布助手
- 应用名称：技术开发布助手
- 描述：处理代码开发布和技术访问题
- 获取 App ID 和 App Secret
AI资讯助手
- 应用名称：AI资讯助手
- 描述：快速获取 AI 行业资讯
- 获取 App ID 和 App Secret

重要配置：

启用机器人能力
配置事件订阅：选择"长连接"模式
添加权限：消息接收、消息发布送

第二步：配置 Agent

创建 4 个 Agent 配置目附录：

bash

mkdir -p agent-configs/{main-agent,content-agent,tech-agent,ainews-agent}

为每个 Agent 创建配置文件：

agent-configs/main-agent/USER.md：

markdown

# 用户信息

- 姓名：Maynor
- 职业：超级个体创业者
- 工作领域：AI 技术、内内容创作、技术开发布

agent-configs/main-agent/SOUL.md：

markdown

# Agent 身份

你是 Maynor 的主助理，负责处理各类复杂任务。使用 Claude Opus 4.6 Thinking 模型，提供最高质量的服务。

类似地为其他 3 个 Agent 创建配置文件。

第三步：运行配置脚本

使用自动化脚本创建多 Gateway 配置：

bash

# 下载配置脚本
curl -O https://example.com/setup-multi-gateway.sh
chmod +x setup-multi-gateway.sh

# 运行配置脚本
./setup-multi-gateway.sh

脚本会自动：

停止当前 Gateway
备份现有配置
创建 4 个独立的 Profile 配置
生成管理脚本

第四步：启动所有 Gateway

bash

# 启动所有 Gateway
./start-all-gateways.sh

# 检查状态
./check-gateways.sh

# 验证配置
./verify-setup.sh

9.1.16.5 使用方法

直接私聊机器人

这是最简单的使用方式：

处理复杂任务
- 在飞书中搜索"主助理"机器人
- 直接发布送消息
- 自动使用 Claude Opus 4.6 Thinking
创作内内容
- 搜索"内内容创作助手"机器人
- 发布送写作需求
- 自动使用 Claude Sonnet 4.5
开发布代码
- 搜索"技术开发布助手"机器人
- 发布送技术访问题
- 自动使用 Claude Sonnet 4.5 Thinking
获取资讯
- 搜索"AI资讯助手"机器人
- 请求最新动态
- 自动使用 Gemini 2.5 Flash（快速响应）

在群组中使用（可选）

如果需要在群组中使用：

将对应的机器人添加到群组
@ 机器人发布送消息
每个群组可以添加多个机器人，灵活切换

建议：

工作群：添加主助理 + 技术开发布助手
内内容创作群：添加内内容创作助手
资讯群：添加 AI资讯助手

9.1.16.6 管理和维护

日常管理

bash

# 查看所有 Gateway 状态
./check-gateways.sh

# 查看实时日志
tail -f logs-main-assistant.log
tail -f logs-content-creator.log
tail -f logs-tech-dev.log
tail -f logs-ai-news.log

# 查看所有日志
tail -f logs-*.log

重启 Gateway

bash

# 重启所有
./stop-all-gateways.sh
sleep 2
./start-all-gateways.sh

# 重启单个
ps aux | grep "openclaw.*--profile main-assistant"
kill 
./start-main-assistant.sh

修改配置

bash

# 编辑配置
vim ~/.openclaw-main-assistant/openclaw.json

# 验证配置
jq . ~/.openclaw-main-assistant/openclaw.json

# 重启生效
# (停止并重启对应的 Gateway)

监控资源

bash

# 查看内存占用
ps aux | grep openclaw-gateway | awk '{print $4, $11}'

# 查看 CPU 占用
ps aux | grep openclaw-gateway | awk '{print $3, $11}'

# 查看端口占用
lsof -i :18789
lsof -i :18790
lsof -i :18791
lsof -i :18792

9.1.16.7 实战案例

案例一：内内容创作工作流

场景：写一篇技术文章节

构思阶段
- 私聊"主助理"：讨论文章节主题和大纲
- 使用 Claude Opus 进行深度思考
写作阶段
- 私聊"内内容创作助手"：撰写文章节内内容
- 使用 Claude Sonnet 快速生成
代码示例
- 私聊"技术开发布助手"：编写代码示例
- 使用 Claude Sonnet Thinking 确保代码质量
资讯补充
- 私聊"AI资讯助手"：获取最新技术动态
- 使用 Gemini Flash 快速检索

案例二：技术开发布工作流

场景：开发布一个新功能

需求分析
- 主助理：分析需求，设计架构
代码实现
- 技术开发布助手：编写代码，调试访问题
文档编写
- 内内容创作助手：编写技术文档
技术调研
- AI资讯助手：查找相关技术资料

案例三：日常工作场景

上午 9:00 - 规划工作

主助理：制定今天的工作计划

上午 10:00 - 写作

内内容创作助手：撰写文章节

下午 2:00 - 开发布

技术开发布助手：编写代码

下午 4:00 - 学习

AI资讯助手：了解行业动态

晚上 8:00 - 总结

主助理：总结今天的工作

9.1.16.8 性能和成本

资源占用

内存：每个 Gateway 约 400MB
总内存：4 个 Gateway 约 1.6GB
CPU：空闲时几乎为 0，处理时根据任务而定
磁盘：配置文件和日志约 100MB

成本分析

假设使用自建 API 代理：

Agent	模型	用途	月使用量	月成本
main-agent	Claude Opus 4.6	复杂任务	100万 tokens	$15
content-agent	Claude Sonnet 4.5	内内容创作	200万 tokens	$6
tech-agent	Claude Sonnet 4.5	技术开发布	150万 tokens	$4.5
ainews-agent	Gemini 2.5 Flash	资讯获取	300万 tokens	$0
总计	-	-	750万 tokens	$25.5

成本优化建议：

简单任务使用 Gemini Flash（免费）
复杂任务才使用 Claude Opus
内内容创作使用 Claude Sonnet（性价比高）

9.1.16.9 故障排查

Gateway 启动失败

症状：运行 ./start-all-gateways.sh 后，./check-gateways.sh 显示进程未运行

排查步骤：

bash

# 1. 查看日志
tail -50 logs-main-assistant.log

# 2. 检查配置
jq . ~/.openclaw-main-assistant/openclaw.json

# 3. 检查端口占用
lsof -i :18789

# 4. 运行 doctor
openclaw --profile main-assistant doctor

常见访问题：

配置文件格式错误：运行 jq 验证
端口被占用：更换端口或停止占用进程
飞书配置错误：检查 App ID 和 App Secret

机器人无响应

症状：在飞书中 @ 机器人，没有回复

排查步骤：

bash

# 1. 检查 Gateway 是否运行
./check-gateways.sh

# 2. 查看实时日志
tail -f logs-main-assistant.log

# 3. 检查飞书连接
grep "WebSocket client started" logs-main-assistant.log

常见原因：

Gateway 未启动：运行 ./start-all-gateways.sh
飞书连接断开：检查网络，重启 Gateway
配置错误：验证飞书 App ID 和 Secret

使用了错误的 Agent

症状：私聊"内内容创作助手"，但使用的是 Claude Opus 模型

原因：配置文件中 Agent 设置错误

解决：

bash

# 检查配置
jq '.agents.list[0].id, .agents.list[0].model.primary' \
  ~/.openclaw-content-creator/openclaw.json

# 应该输出：
# "content-agent"
# "local-antigravity/claude-sonnet-4-5"

9.1.16.10 高级技巧

技巧一：使用 tmux 管理

bash

# 创建 tmux 会话
tmux new -s openclaw

# 分割窗口
Ctrl+b %  # 垂直分割
Ctrl+b "  # 水平分割

# 在不同窗口中运行不同的 Gateway
./start-main-assistant.sh
./start-content-creator.sh
./start-tech-dev.sh
./start-ai-news.sh

# 查看所有日志
tail -f logs-*.log

技巧二：配置开机自启动

使用 launchd（macOS）：

bash

# 创建 plist 文件
cat > ~/Library/LaunchAgents/com.openclaw.main-assistant.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<dict>
  <key>Label</key>
  <string>com.openclaw.main-assistant</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/openclaw</string>
    <string>--profile</string>
    <string>main-assistant</string>
    <string>gateway</string>
    <string>run</string>
  </array>
  <key>RunAtLoad</key>
  
  <key>KeepAlive</key>
  
</dict>

EOF

# 加载服务
launchctl load ~/Library/LaunchAgents/com.openclaw.main-assistant.plist

技巧三：日志轮转

bash

# 创建日志轮转脚本
cat > rotate-logs.sh << 'EOF'
#!/bin/zsh
for log in logs-*.log; do
  if [ -f "$log" ] && [ $(stat -f%z "$log") -gt 10485760 ]; then
    mv "$log" "$log.$(date +%Y%m%d_%H%M%S)"
    touch "$log"
  fi
done
EOF

chmod +x rotate-logs.sh

# 添加到 crontab（每小时执行）
crontab -e
# 添加：0 * * * * /path/to/rotate-logs.sh

9.1.16.11 总结

多 Gateway + 多飞书机器人的方案是目前最稳定、最简单的多 Agent 实现方式：

核心优势：

✅ 直接私聊不同机器人，自动使用对应 agent
✅ 完全独立，互不干扰
✅ 不需要复杂的 bindings 配置
✅ 不需要手动切换命令
✅ 配置清晰，易于管理

适用场景：

超级个体创业者
需要多个专业助手
不同任务使用不同模型
追求稳定性和可靠性

下一步：

创建飞书机器人应用
运行配置脚本
启动所有 Gateway
开始使用你的 AI 助手团队！

9.1.17 多 Agent 配置（传统方式）

⚠️ 注意：本节介绍的是传统的单 Gateway + Bindings 方式，推荐使用上面的多 Gateway 方案。

什么是多 Agent？

多 Agent 配置允许：

每个飞书机器人使用不同的 Agent
每个 Agent 使用不同的模型
每个 Agent 使用独立的工作空间
每个 Agent 有独立的配置和上下文

9.1.17.1 配置结构（传统方式）

json

{
  "agents": {
    "list": [
      {
        "id": "agent-id",
        "workspace": "/path/to/workspace",
        "model": {
          "primary": "provider/model"
        }
      }
    ],
    "defaults": {
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4
    }
  },
  "channels": {
    "feishu": {
      "accounts": {
        "bot-name": { ... }
      }
    }
  },
  "bindings": [
    {
      "agentId": "agent-id",
      "match": {
        "channel": "feishu",
        "peer": {
          "kind": "dm",
          "id": "ou_user_id"
        }
      }
    }
  ]
}

9.1.17.2 实战案例：4个专业助手（传统方式）

场景：一人公司，需要不同的专业助手处理不同任务。

配置示例：

text

/* Detailed source-code truncated for AI context efficiency. */

9.1.17.3 获取用户 ID（传统方式）

方法1：通过日志获取（推荐）

bash

# 1. 启动网关并查看日志
openclaw gateway restart
openclaw logs --follow

# 2. 在飞书中给每个机器人发布送消息

# 3. 在日志中查找 open_id
# 格式：ou_xxxxxxxxxxxxxxxx

日志示例：
[feishu] Received message from ou_18d36d8a49c010dfe20ace2a29250c04
[feishu] Bot: 主助理
方法2：通过配对请求获取

bash

openclaw pairing list feishu

# 输出示例：
# Pending pairing requests:
# - Code: ABC123, User: ou_xxx, Bot: 主助理

9.1.17.4 配置步骤（传统方式）

步骤1：创建工作空间目附录

bash

mkdir -p /Users/username/clawd/content
mkdir -p /Users/username/clawd/tech
mkdir -p /Users/username/clawd/ainews

步骤2：获取所有用户 ID

按照上面的方法，获取每个机器人对应的用户 ID。

步骤3：更新配置文件

将获取到的用户 ID 填入 bindings 部分。

步骤4：应用配置

bash

# 备份现有配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 应用新配置
cp your-config.json ~/.openclaw/openclaw.json

# 验证配置
openclaw doctor

# 重启网关
openclaw gateway restart

步骤5：验证运行

bash

# 查看 Agent 状态
openclaw doctor

# 应该看到：
# Agents: main-agent (default), content-agent, tech-agent, ainews-agent
# Session store: 4 entries

# 查看日志
openclaw logs --follow | grep bindings

# 应该看到：
# [bindings] Matched agent: main-agent for user ou_xxx

9.1.17.5 配置注意事项

⚠️ 重要：agents.list 配置限制

这是最常见的配置错误！agents.list 中的每个 Agent 只能包含以下字段：

json

{
  "id": "agent-id",           // ✅ Agent 标识符（必填）
  "workspace": "/path",       // ✅ 工作空间路径（必填）
  "model": { "primary": "" }  // ✅ 使用的模型（可选）
  // ❌ 不能包含 compaction
  // ❌ 不能包含 maxConcurrent
  // ❌ 不能包含 subagents
  // ❌ 不能包含 models
}

错误示例（会导致配置验证失败）：

json

{
  "agents": {
    "list": [
      {
        "id": "main-agent",
        "workspace": "/path",
        "compaction": { "mode": "safeguard" },  // ❌ 错误！
        "maxConcurrent": 4                       // ❌ 错误！
      }
    ]
  }
}

正确示例：

json

{
  "agents": {
    "list": [
      {
        "id": "main-agent",
        "workspace": "/path",
        "model": { "primary": "provider/model" }  // ✅ 正确
      }
    ],
    "defaults": {
      "compaction": { "mode": "safeguard" },  // ✅ 在这里配置
      "maxConcurrent": 4,                     // ✅ 在这里配置
      "subagents": { "maxConcurrent": 8 }     // ✅ 在这里配置
    }
  }
}

2. 通用配置必须放在 agents.defaults：

所有 Agent 共分享的配置项必须放在 agents.defaults 中，包括：

compaction - 上下文压缩策略
maxConcurrent - 最大并发布数
subagents - 子 Agent 配置
models - 额外的模型配置

json

{
  "defaults": {
    "model": {
      "primary": "default-provider/default-model"
    },
    "workspace": "/default/workspace",
    "compaction": { "mode": "safeguard" },
    "maxConcurrent": 4,
    "subagents": { "maxConcurrent": 8 }
  }
}

3. Bindings 顺序很重要：

OpenClaw 会按顺序匹配 bindings，第一个匹配的规则会被使用。

json

"bindings": [
  // 1. 最具体的匹配（特定用户）
  { "agentId": "main-agent", "match": { "peer": { "id": "ou_xxx" } } },
  // 2. 较具体的匹配（特定群组）
  { "agentId": "tech-agent", "match": { "peer": { "kind": "group" } } },
  // 3. 最后是默认匹配
  { "agentId": "default-agent", "match": { "channel": "feishu" } }
]

4. 用户 ID 是唯一的：

每个飞书用户只能绑定到一个 Agent。

故障排查

访问题1：配置验证失败 - agents.list 包含不支持的字段

bash

# 错误信息
Config invalid
File: ~/.openclaw/openclaw.json
Problem:
- agents.list.0: Unrecognized keys: "compaction", "maxConcurrent"
- agents.list.1: Unrecognized keys: "compaction", "maxConcurrent"
- agents.list.2: Unrecognized keys: "compaction", "maxConcurrent"
- agents.list.3: Unrecognized keys: "compaction", "maxConcurrent"
Run:
openclaw update repair
openclaw doctor

原因：agents.list 中的 Agent 配置包含了只能在 agents.defaults 中使用的字段。

解决方案：

bash

# 方法1：自动修复（推荐）
openclaw update repair
openclaw doctor

# 方法2：手动修复
# 编辑配置文件，将 compaction 和 maxConcurrent 从 agents.list 移到 agents.defaults

修复前：

json

{
  "agents": {
    "list": [
      {
        "id": "main-agent",
        "workspace": "/path",
        "compaction": { "mode": "safeguard" },  // ❌ 错误位置
        "maxConcurrent": 4                       // ❌ 错误位置
      }
    ]
  }
}

修复后：

json

{
  "agents": {
    "list": [
      {
        "id": "main-agent",
        "workspace": "/path",
        "model": { "primary": "provider/model" }
      }
    ],
    "defaults": {
      "compaction": { "mode": "safeguard" },  // ✅ 正确位置
      "maxConcurrent": 4                       // ✅ 正确位置
    }
  }
}

验证修复：

bash

# 验证配置
openclaw doctor

# 应该看到：
# ✅ Config valid
# ✅ 4 agents configured
# ✅ 4 bindings configured

访问题2：Bindings 不生效

bash

# 检查用户 ID 是否正确
openclaw logs --follow | grep "ou_"

# 查看 bindings 匹配情况
openclaw logs --follow | grep bindings

访问题3：找不到用户 ID

bash

# 使用 debug 级别日志
openclaw logs --follow --level debug

# 或查看配对请求
openclaw pairing list feishu

访问题4：配置修改后运行 openclaw doctor 报错

bash

# 错误信息
Unknown config keys:
- agents.list[0].compaction
- agents.list[0].maxConcurrent
- agents.list[1].compaction
- agents.list[1].maxConcurrent
...

Run `openclaw update repair` and then `openclaw doctor` to remove these keys.

解决方案：

bash

# 运行自动修复
openclaw update repair
openclaw doctor

# 验证配置
openclaw doctor

# 重启网关
openclaw gateway restart

# 查看状态
openclaw gateway status

访问题5：版本不匹配警告

bash

# 警告信息
Config was last written by a newer OpenClaw (2026.2.6-3); 
current version is 2026.2.1-zh.3.
Run `openclaw update repair` and then `openclaw doctor` to apply changes.

说明：这是正常的版本提示，不影响使用。如果想消除警告：

bash

openclaw update repair
openclaw doctor

9.1.17.6 配置对比

特性	单 Agent 模式	多 Agent 模式
配置复杂度	简单	复杂
模型选择	所有机器人相同	每个机器人不同
工作空间	共分享	隔离
需要 bindings	❌	✅
需要用户 ID	❌	✅
适用场景	简单使用	专业分工

9.1.17.7 使用建议

推荐使用多 Agent 的场景：

✅ 需要不同机器人使用不同模型
✅ 需要隔离工作空间
✅ 需要独立配置和上下文
✅ 专业分工明确

推荐使用单 Agent 的场景：

✅ 配置简单易维护
✅ 所有机器人使用相同模型
✅ 不需要隔离工作空间
✅ 快速开始使用

9.1.18 本地多 Agent 管理（无需绑定 IM 平台）

💡 重要提示：多 Agent 管理不仅可以用于飞书等 IM 平台，也完全支持本地使用。如果你不需要绑定飞书机器人，可以通过 Web UI、命令行或 TUI 界面直接使用多个 Agent。

本地使用方式

OpenClaw 提供了多种本地使用方式，无需配置任何 IM 平台：

方式一：Web UI（推荐）

bash

# 打开 Web 界面
openclaw dashboard

# 或直接访问
http://127.0.0.1:18789/?token=你的token

优势：

✅ 图形化界面，操作直观
✅ 支持文件上传和下载
✅ 实时显示 Token 消耗
✅ 支持多轮对话历史

方式二：命令行对话

bash

# 直接发布送消息
openclaw agent --message "你好，帮我分析一下这个项目"

# 使用管道输入
echo "帮我总结这个文件的内内容" | openclaw agent --message

# 指定输出文件（使用重定向）
openclaw agent --message "生成项目文档" > docs.md

优势：

✅ 快速执行单次任务
✅ 适合脚本自动化
✅ 可以集成到工作流中

方式三：TUI 终端界面

bash

# 启动终端交互界面
openclaw tui

优势：

✅ 终端内交互式对话
✅ 支持多轮对话
✅ 适合服务器环境使用

本地多 Agent 配置

配置文件位置：~/.openclaw/openclaw.json

配置示例：

json

{
  "agents": {
    "list": [
      {
        "id": "main-agent",
        "workspace": "/Users/username/work",
        "model": { "primary": "anthropic/claude-sonnet-4" }
      },
      {
        "id": "content-agent",
        "workspace": "/Users/username/content",
        "model": { "primary": "anthropic/claude-sonnet-4" }
      },
      {
        "id": "code-agent",
        "workspace": "/Users/username/code",
        "model": { "primary": "deepseek/deepseek-chat" }
      },
      {
        "id": "research-agent",
        "workspace": "/Users/username/research",
        "model": { "primary": "google/gemini-2-flash" }
      }
    ],
    "defaults": {
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 }
    }
  }
}

配置说明：

agents.list：定义所有可用的 Agent
- id：Agent 标识符（必填）
- workspace：工作空间路径（必填）
- model.primary：使用的模型（可选）
agents.defaults：所有 Agent 共分享的配置
- compaction：上下文压缩策略
- maxConcurrent：最大并发布数
- subagents：子 Agent 配置

Agent 管理命令

列出所有 Agent

bash

openclaw agents list

# 输出示例：
# Available agents:
# - main-agent (default)
#   Workspace: /Users/username/work
#   Model: anthropic/claude-sonnet-4
# - content-agent
#   Workspace: /Users/username/content
#   Model: anthropic/claude-sonnet-4
# - code-agent
#   Workspace: /Users/username/code
#   Model: deepseek/deepseek-chat
# - research-agent
#   Workspace: /Users/username/research
#   Model: google/gemini-2-flash

切换 Agent

bash

# 切换到指定 Agent
openclaw agents switch content-agent

# 输出：
# Switched to agent: content-agent
# Workspace: /Users/username/content
# Model: anthropic/claude-sonnet-4

查看当前 Agent

bash

# 查看当前使用的 Agent
openclaw agents current

# 输出：
# Current agent: content-agent
# Workspace: /Users/username/content
# Model: anthropic/claude-sonnet-4

查看 Agent 配置

bash

# 查看指定 Agent 的配置
openclaw agents config content-agent

# 查看当前 Agent 的配置
openclaw agents config

查看 Agent 状态

bash

# 查看所有 Agent 的状态
openclaw doctor

# 输出示例：
# ✅ Config valid
# ✅ 4 agents configured
# ✅ Gateway running
# ✅ Session store: 12 entries

实战案例：4个专业助手

场景：个人开发布者，需要不同的专业助手处理不同任务。

配置步骤：

步骤1：创建工作空间目附录

bash

mkdir -p ~/work/main
mkdir -p ~/work/content
mkdir -p ~/work/code
mkdir -p ~/work/research

步骤2：编辑配置文件

bash

# 备份现有配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 编辑配置
nano ~/.openclaw/openclaw.json

将上面的配置示例粘贴进去，修改路径为你的实际路径。

步骤3：验证配置

bash

# 验证配置是否正确
openclaw doctor

# 应该看到：
# ✅ Config valid
# ✅ 4 agents configured

步骤4：重启网关

bash

# 重启网关使配置生效
openclaw gateway restart

# 查看状态
openclaw gateway status

步骤5：使用不同的 Agent

bash

# 使用主助手处理通用任务
openclaw agents switch main-agent
openclaw agent --message "帮我整理今天的待怎么办事项"

# 使用内内容助手创作文章节
openclaw agents switch content-agent
openclaw agent --message "帮我写一篇关于 AI 的文章节"

# 使用代码助手开发布项目
openclaw agents switch code-agent
openclaw agent --message "帮我优化这段 Python 代码"

# 使用研究助手搜集资料
openclaw agents switch research-agent
openclaw agent --message "帮我搜集关于量子计算的最新研究"

使用场景对比

场景	推荐方式	Agent 配置	优势
个人本地使用	Web UI + 多 Agent	不同任务用不同 Agent	工作空间隔离，模型灵活
团队协作	飞书 + 多 Agent	不同机器人绑定不同 Agent	团队成员各用各的助手
快速测试	命令行 + 单 Agent	使用默认 Agent	配置简单，快速上手
服务器环境	TUI + 多 Agent	不同项目用不同 Agent	终端内交互，资源隔离

典型工作流

场景：一人公司的日常工作流

bash

# 早上：使用主助手查看日程
openclaw agents switch main-agent
openclaw agent --message "显示今天的日程安排"

# 上午：使用代码助手开发布项目
openclaw agents switch code-agent
openclaw agent --message "帮我实现用户登录功能"

# 中午：使用研究助手学习新技术
openclaw agents switch research-agent
openclaw agent --message "搜集 Rust 语言的学习资料"

# 下午：使用内内容助手写文章节
openclaw agents switch content-agent
openclaw agent --message "写一篇关于今天开发布经验的博客"

# 晚上：使用主助手总结一天
openclaw agents switch main-agent
openclaw agent --message "生成今日工作总结"

配置技巧

技巧1：为不同任务使用不同模型

json

{
  "agents": {
    "list": [
      {
        "id": "chat-agent",
        "workspace": "/Users/username/chat",
        "model": { "primary": "anthropic/claude-sonnet-4" }
      },
      {
        "id": "code-agent",
        "workspace": "/Users/username/code",
        "model": { "primary": "deepseek/deepseek-chat" }
      },
      {
        "id": "fast-agent",
        "workspace": "/Users/username/fast",
        "model": { "primary": "google/gemini-2-flash" }
      }
    ]
  }
}

说明：

Claude Sonnet 4：通用对话和复杂任务
DeepSeek：代码生成和技术访问题
Gemini Flash：快速响应和简单任务

技巧2：使用别名简化切换

bash

# 在 ~/.zshrc 或 ~/.bashrc 中添加别名
alias oc-main='openclaw agents switch main-agent'
alias oc-code='openclaw agents switch code-agent'
alias oc-content='openclaw agents switch content-agent'
alias oc-research='openclaw agents switch research-agent'

# 使用别名快速切换
oc-code
openclaw agent --message "帮我写一个排序算法"

技巧3：为每个 Agent 配置独立的 Skills

bash

# 为代码助手安装开发布相关的 Skills
openclaw agents switch code-agent
clawhub install github-integration
clawhub install code-review

# 为内内容助手安装写作相关的 Skills
openclaw agents switch content-agent
clawhub install grammar-check
clawhub install seo-optimizer

常见访问题

访问题1：切换 Agent 后工作空间没变

bash

# 检查当前 Agent
openclaw agents current

# 检查配置
openclaw agents config

# 重启网关
openclaw gateway restart

访问题2：找不到 Agent

bash

# 列出所有 Agent
openclaw agents list

# 检查配置文件
cat ~/.openclaw/openclaw.json | grep -A 5 "agents"

访问题3：Agent 配置验证失败

bash

# 运行诊断
openclaw doctor

# 自动修复
openclaw update repair
openclaw doctor

最佳实践

工作空间隔离
- 为每个 Agent 创建独立的工作空间
- 避免不同任务的文件混在一起
模型选择
- 根据任务类型选择合适的模型
- 代码任务用 DeepSeek，通用任务用 Claude
定期备份
- 定期备份配置文件
- 使用版本控制管理配置
命名规范
- Agent ID 使用有意义的名称
- 工作空间路径清晰明确
资源管理
- 合理设置 maxConcurrent
- 定期清理不用的会话

9.12 OpenClaw Manager - 可视化管理工具

💡 现代化管理界面：OpenClaw Manager 是一个基于 React + Tailwind CSS 的 Web 管理界面，用于可视化管理多个 OpenClaw Gateway 实例。

9.12.1 为什么需要 OpenClaw Manager？

当你使用多 Gateway 架构（每个飞书机器人对应一个独立的 Gateway 实例）时，传统的命令行管理方式会变得繁琐。OpenClaw Manager 提供了：

核心价值：

📊 实时监控：一目了然查看所有 Gateway 的运行状态
🎮 一键控制：启动/停止/重启服务，无需记忆命令
➕ 图形化创建：通过表单创建新 Gateway，无需手动编辑配置
✏️ 在线编辑：可视化编辑 Gateway 配置和 Agent 人格
⚙️ 保活配置：一键配置 launchd 保活服务
📝 日志查看：实时查看每个服务的运行日志
💻 美观界面：现代化设计，响应式布局

9.12.2 功能特性

1. 自动发布现 Gateway 实例 🔍

系统会自动扫描 ~/.openclaw-* 目附录，读取配置文件并显示所有 Gateway 实例。

特性：

自动读取端口、模型、Agent 信息
缓存机制（1分钟 TTL）提升性能
支持手动刷新发布现

2. 创建新 Gateway ➕

通过图形界面创建新的 Gateway 实例，无需手动编辑配置文件。

配置项：

基础信息：

Profile ID：唯一标识符（如 my-assistant）
机器人名称：显示名称（如 我的助手）
端口号：Gateway 监听端口（建议 18789-18799）

Agent 配置：

Agent ID：Agent 标识符（如 main-agent）
AI 模型：
- 预设模型：Claude Opus 4.6、Claude Sonnet 4.5、Gemini 2.5 Pro 等
- 自定义模型：输入任意模型 ID（如 gpt-4o, deepseek-chat）

飞书配置：

App ID：飞书应用 ID（cli_xxxxxxxxxxxxxxxx）
App Secret：飞书应用密钥

人格设定 📝：

SOUL.md 编辑器：使用 Markdown 定义 Agent 的角色、性格、专业领域、回答风格

示例 SOUL.md：

markdown

# 技术顾访问 Agent

## 角色定位
你是一个资深的技术顾访问，专注于软件架构和系统设计。

## 性格特点
- 严谨、专业
- 注重细节和最佳实践
- 善于分析复杂访问题

## 专业领域
- 微服务架构
- 云原生技术
- DevOps 实践
- 性能优化

## 回答风格
- 先理解需求，再提供方案
- 给出具体可行的建议
- 必要时提供代码示例和架构图
- 考虑可扩展性和维护性

3. 编辑 Gateway ✏️

修改现有 Gateway 的配置和人格设定。

可修改项：

机器人名称
端口号
Agent ID
AI 模型（预设或自定义）
飞书 App ID 和 Secret（可选）
SOUL.md 人格设定

注意事项：

Profile ID 不可修改
飞书密钥留空则不修改
修改后需要重启 Gateway 才能生效

4. 删除 Gateway 🗑️

完全移除 Gateway 实例及其所有配置。

删除内内容：

Gateway 配置文件
Agent 配置目附录
SOUL.md 人格文件
launchd 保活配置（如果存在）

⚠️ 警告：删除操作不可恢复，建议先备份重要配置。

5. 服务控制 🎮

批量操作：

⚙️ 配置保活：配置 launchd 保活服务（开机自启、崩溃重启）
▶️ 启动所有：启动所有 Gateway 实例
⏹️ 停止所有：停止所有 Gateway 实例
🔄 重启所有：重启所有 Gateway 实例

单个操作：

✏️ 编辑：编辑 Gateway 配置
🗑️ 删除：删除 Gateway
📝 日志：查看运行日志

6. 实时状态监控 📊

显示信息：

运行状态（运行中/已停止）
端口号
使用的 AI 模型
launchd 保活状态

状态指示：

🟢 绿色：运行中
🔴 红色：已停止
⚪ 灰色：未知

自动刷新：每 10 秒自动刷新状态，可手动点击"刷新状态"按钮。

9.12.3 安装和使用

安装步骤

bash

# 1. 克隆项目
git clone https://github.com/xianyu110/openclaw-manager.git
cd openclaw-manager

# 2. 安装依赖
npm install

# 3. 启动服务（前端 + 后端）
npm start

应用将在以下地址启动：

前端：http://localhost:3000
后端 API：http://localhost:3001

首次使用

启动应用
bash
```
npm start
```
打开浏览器
访问 http://localhost:3000
配置保活服务
- 点击"⚙️ 配置保活"按钮
- 等待配置完成
- 服务将自动开机启动并在崩溃后重启

日常操作

查看服务状态：

界面会自动每 10 秒刷新状态
点击"刷新状态"按钮手动刷新
绿色指示灯表示运行中，红色表示已停止

控制服务：

启动所有：一键启动所有 Gateway
停止所有：一键停止所有 Gateway
重启所有：一键重启所有 Gateway
单个控制：在服务卡片中点击"重启"按钮

查看日志：

点击服务卡片中的"查看日志"按钮
显示最近 100 行日志
支持实时刷新

9.12.4 使用场景

场景 1：创建专业领域助手

需求：创建一个专注于前端开发布的技术助手

步骤：

点击"➕ 新建 Gateway"
填写基础信息：
- Profile ID: frontend-expert
- 机器人名称: 前端专家
- 端口: 18793
配置 Agent：
- Agent ID: frontend-agent
- 模型: Claude Sonnet 4.5 Thinking
展开人格编辑器，定义专业领域：

markdown

# 前端开发布专家

## 角色定位
你是一个资深的前端开发布工程师，精通现代前端技术栈。

## 专业领域
- React / Vue / Angular
- TypeScript
- Webpack / Vite
- CSS-in-JS / Tailwind CSS
- 性能优化
- 浏览器兼内容性

## 回答风格
- 提供最新的最佳实践
- 给出可运行的代码示例
- 考虑性能和可维护性
- 推荐合适的工具和库

填写飞书配置
点击"创建"

场景 2：使用自定义模型

需求：使用 OpenAI 的 GPT-4o 模型

步骤：

在创建或编辑 Gateway 时
勾选"使用自定义模型"
输入模型 ID: gpt-4o
确保在 OpenClaw 主配置中已设置 OpenAI API Key

支持的自定义模型：

OpenAI: gpt-4o, gpt-4o-mini, gpt-4-turbo
Anthropic: claude-3-opus-20240229, claude-3-sonnet-20240229
Google: gemini-2.5-pro, gemini-2.5-flash
DeepSeek: deepseek-chat, deepseek-coder
其他兼内容 OpenAI API 的模型

场景 3：创建多个专业助手

需求：为不同团队创建专属助手

助手配置：

产品经理助手
- Profile: product-manager
- 模型: Claude Opus 4.6
- 人格: 注重用户体验、数据分析、产品规划
设计师助手
- Profile: designer
- 模型: Claude Sonnet 4.5
- 人格: 关注视觉设计、用户界面、交互体验
运维工程师助手
- Profile: devops-engineer
- 模型: Claude Sonnet 4.5 Thinking
- 人格: 专注系统稳定性、自动化、监控告警
数据分析师助手
- Profile: data-analyst
- 模型: Gemini 2.5 Pro
- 人格: 擅长数据处理、可视化、统计分析

9.12.5 高级技巧

1. 人格设定最佳实践

结构化定义：

markdown

# Agent 名称

## 角色定位
明确定义 Agent 的角色和定位

## 性格特点
- 列出 3-5 个核心性格特点
- 保支持一致性

## 专业领域
- 列出专业技能
- 明确擅长的领域

## 回答风格
- 描述回答的方式
- 设定语气和风格

## 工作流程
1. 步骤化的工作方式
2. 确保逻辑清晰
3. 提供可操作的建议

## 限制和边界
- 明确不擅长的领域
- 设定合理的期望

2. 模型选择建议

Claude Opus 4.6：

最强推理能力
适合复杂访问题分析
成本较高

Claude Sonnet 4.5：

平衡性能和成本
适合日常对话
推荐用于大多数场景

Claude Sonnet 4.5 Thinking：

增强的思考过程
适合需要深度分析的场景
会显示思考步骤

Gemini 2.5 Flash：

响应速度快
成本低
适合简单查询和快速响应

DeepSeek Chat：

国产模型，成本极低
中文能力强
适合日常对话和简单任务

3. 端口分配建议

推荐范围：18789-18799

示例分配：

18789: 主助理
18790: 内内容创作
18791: 技术开发布
18792: 数据分析
18793: 产品设计
18794: 运维支持
18795: 客户服务
18796-18799: 预留

9.12.6 故障排查

访问题 1：创建 Gateway 失败

可能原因：

Profile ID 已存在
端口已被占用
缺少必填字段

解决方法：

检查错误提示
使用不同的 Profile ID
选择未被占用的端口
确保所有必填字段已填写

访问题 2：Gateway 无法启动

可能原因：

配置文件格式错误
飞书账号配置错误
端口被其他程序占用

解决方法：

检查配置文件语法
验证飞书 App ID 和 Secret
使用 lsof -i :端口号 检查端口占用
查看日志文件件排查错误

访问题 3：人格设定不生效

可能原因：

SOUL.md 文件未保存
Gateway 未重启
Agent ID 不匹配

解决方法：

确认 SOUL.md 已保存
重启 Gateway 服务
检查 Agent ID 是否正确
查看 ~/.openclaw-{profile}/agent-configs/{agent}/SOUL.md

访问题 4：后端无法连接

bash

# 检查端口占用
lsof -i :3001

# 手动启动后端
npm run server

访问题 5：前端无法访问

bash

# 检查端口占用
lsof -i :3000

# 清除缓存重新启动
rm -rf node_modules/.vite
npm start

9.12.7 API 文档

状态查询

GET /api/status

获取所有服务的状态信息

响应示例：

json

{
  "services": [
    {
      "id": "main-assistant",
      "name": "主助理",
      "port": 18789,
      "status": "running",
      "model": "Claude Opus 4.6",
      "launchd": true
    }
  ]
}

批量操作

POST /api/start-all - 启动所有 Gateway 服务
POST /api/stop-all - 停止所有 Gateway 服务
POST /api/restart-all - 重启所有 Gateway 服务
POST /api/setup-launchd - 配置 launchd 保活服务

单个服务操作

POST /api/start/:serviceId - 启动指定的 Gateway 服务
POST /api/stop/:serviceId - 停止指定的 Gateway 服务
POST /api/restart/:serviceId - 重启指定的 Gateway 服务
GET /api/logs/:serviceId - 获取指定服务的日志（最近 100 行）

Gateway 管理

GET /api/gateways - 获取所有 Gateway 配置
POST /api/gateways - 创建新的 Gateway
PUT /api/gateways/:profileId - 更新 Gateway 配置
DELETE /api/gateways/:profileId - 删除 Gateway

9.12.8 最佳实践

1. 命名规范

Profile ID：

使用小写字母和连字符
描述性命名
例如: tech-support, content-writer

Agent ID：

与 Profile ID 保支持一致
添加 -agent 后缀
例如: tech-support-agent

2. 人格设定

清晰明确：

使用简洁的语言
避免模糊的描述
提供具体的例子

保支持一致：

人格特点要统一
回答风格要稳定
避免矛盾的设定

定期优化：

根据使用反馈调整
不断完善人格设定
测试不同的配置

3. 安全建议

保护敏感信息：

不要在 SOUL.md 中包含密钥
定期更换飞书 App Secret
限制 Gateway 的网络访问

备份配置：

定期备份 ~/.openclaw-* 目附录
保存重要的 SOUL.md 文件
记附录配置变更

9.12.9 项目信息

GitHub 仓库：https://github.com/xianyu110/openclaw-manager

技术栈：

前端：React 18 + Tailwind CSS + Vite
后端：Express + Node.js
状态管理：React Hooks
样式：Tailwind CSS

许可证：MIT

作者：Maynor (@xianyu110)

贡献：
欢迎提交 Issue 和 Pull Request！

9.13 更多 OpenClaw 可视化管理工具

除了 OpenClaw Manager，社区还有以下两款优秀的可视化工具可选：

9.13.1 ClawX —— 开源 AI 研究助手

项目地址：https://clawx.dev/ | GitHub：https://github.com/ValueCell-ai/ClawX

ClawX 是由 ValueCell 团队开发布的开源桌面应用，在本地运行，专注于 AI 自主任务执行和多平台通知推送。

核心功能：

功能	说明
24/7 自主运行	支持续监控和执行任务，无需人工干预
20+ 通讯平台通知	支持 WhatsApp、Telegram、Slack、Discord 等
数据聚合	跨多个来源进行网页抓取和数据收集
计划任务	基于 Cron 的定时监控功能
多 AI 供应商	兼内容 OpenAI、Anthropic、Google 等 10+ 个提供商

技术特点：

TypeScript + React 开发布，支持 macOS / Windows / Linux
本地优先存储，数据不上云
兼内容 OpenClaw 生态 55+ 扩展技能
MIT 开源，完全免费，只需支付 AI 提供商 API 费用

获取方式：访问 GitHub Releases 下载对应平台安装包。

9.13.2 ClawPanel —— OpenClaw 可视化管理面板

项目地址：https://claw.qt.cool/ | GitHub：https://github.com/qingchencloud/clawpanel

ClawPanel 是基于 Tauri v2 构建的跨平台桌面管理面板（当前版本 v0.7.0），专为 OpenClaw Gateway 和多 Agent 日常管理而设计。

核心功能：

功能	说明
Dashboard 监控	实时查看 Gateway 状态、服务状态、Agent 数量、模型池
AI 对话界面	多模型流式对话，WebSocket 连接 Gateway
模型配置	统一管理 OpenAI、DeepSeek、Kimi 等多个 AI 服务商
记忆管理	可视化编辑 Agent 工作记忆、归档、核心配置文件
多 Agent 管理	创建和管理多个 Agent，工作空间隔离
工具权限控制	细粒度工具权限管理，Token/密码认证
内置 AI 助手	一键安装 OpenClaw、配置诊断、自动化故障排查

平台支持：

macOS（Apple Silicon + Intel）
Windows（.exe / .msi）
Linux（AppImage / .deb）

获取方式：访问 GitHub Releases 下载，MIT 开源免费。

9.13.3 三款工具对比

工具	定位	适合场景
OpenClaw Manager	Web 管理界面，多 Gateway 管理	多飞书机器人、多 Gateway 场景
ClawX	桌面应用，自主任务 + 多平台通知	定时任务、数据监控、推送通知
ClawPanel	桌面管理面板，全功能可视化	日常管理 Gateway、多 Agent、模型配置

三款工具均免费开源，可以根据自己的使用场景选择或组合使用。

📝 本章节小结

通过本章节学习，你已经掌握：

飞书Bot配置：完整的飞书机器人创建和配置流程
企业微信Bot：企业微信机器人的配置方法
钉钉Bot配置：钉钉机器人的接入步骤
QQ Bot配置：QQ机器人的详细配置
Discord Bot：Discord机器人的参考配置
平台对比：各平台的功能对比和选择建议
多Agent配置：高级的多Agent管理和配置
本地多Agent：无需绑定IM平台的本地使用
OpenClaw Manager：可视化管理工具的使用
ClawX / ClawPanel：更多开源可视化管理工具选择

🎯 实战练习

配置一个飞书机器人并测试基本功能
尝试配置多个Agent，为不同场景使用不同模型
使用 OpenClaw Manager创建和管理多个Gateway
为每个Agent定制专属的人格设定
配置launchd保活服务，实现开机自启
试用 ClawPanel 或 ClawX，找到最适合自己的管理方式

💡 进阶建议

探索更多IM平台的集成方式
优化Agent的人格设定，提升使用体验
使用 OpenClaw Manager / ClawPanel 简化日常管理
为团队成员创建专属的AI助手
定期备份配置，避免数据丢失

下一章节预告：第10章节将学习API集成，包括如何对接各种第三方服务，实现更强大的自动化功能。

返回目附录：README

🌐 在线阅读

📖 想在线阅读此章节节？

🔗 在线阅读此章节节

访问网站获取更好的阅读体验：

📱 响应式设计，支持手机、平板、电脑
支持黑暗模式，保护眼睛
🔍 内置搜索功能，快速定位内内容
📋 目附录导航，轻松跳转章节节

🏠 访问完整教网站

03 Advanced 10 Api Integration (`docs/03-advanced/10-api-integration.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第10章节 API 与外部能力集成（Infer / Webhooks / 媒体工作流）

本章目标：按 OpenClaw 官方最新主线，把模型推理、媒体能力、Webhook 接入和外部系统联动这几件事讲清楚，并替换掉旧的第三方 Skill 默认路线。

版本基线（请先统一口径）

当前稳定版：v2026.9.3（2026 年 6 月 16 日发布）
本章默认按 v2026.9.3 稳定版 写；历史 beta / 旧模型路由只作为旧案例参考

如果你机器上还停在 v2026.4.12 或更早版本，先升级再看这一章，不然你会在命令名、能力入口和配置路径上反复踩坑。

先给小白的阅读说明

这章适合谁

你已经把 OpenClaw 装好，想让它调用模型、图片、音频、视频或网页能力
你想把 Notion、表单、Webhook、自动化平台接进 OpenClaw
你看过旧教程，发现很多 Skill 名称已经装不上，想知道现在到底该怎么做

开始前要先准备什么

在继续之前，至少先确认这 3 件事：

openclaw onboard 已跑过
openclaw models status 能看到你已经登录的 provider
你知道自己现在是在做哪一类事：命令行推理、会话内工具调用，还是外部系统触发

如果你只想先跑通，按这个顺序看

只想先让命令跑通：看 10.2 + 10.3
只想接外部系统：看 10.4
只想知道旧 Skill 为什么不该再照抄：看 10.1 + 10.5

先记住 3 句话

openclaw infer 负责无头、脚本化、命令行调用
agent 工具负责会话里自动调用能力
hooks / webhooks / Task Flow 负责外部事件接入和多步骤编排

10.1 2026.4 之后，API 集成的正确主线是什么？

旧版教程的主要问题，不是“不会接 API”，而是默认把很多已经过时的第三方 Skill 名称和不再是官方主路线的命令当成首选方案。现在更推荐的路径是：

需求	旧写法常见问题	现在推荐的官方路径
文本推理	零散脚本、手工拼 provider	`openclaw infer model run`
图片生成	依赖历史第三方 Skill	`openclaw infer image generate` 或 agent 工具 `image_generate`
视频生成	旧命令、旧 Skill 名称失效	`openclaw infer video generate` 或 agent 工具 `video_generate`
语音转写	手工脚本多、格式易错	`openclaw infer audio transcribe`
TTS 合成	旧命令路径不统一	`openclaw infer tts convert` 或 agent 工具 `tts`
Web 搜索 / 抓取	自己维护爬虫	`openclaw infer web search` / `openclaw infer web fetch`
Embedding	各 provider 自己写一套	`openclaw infer embedding create`
外部系统触发	靠 cron + shell 拼接	`hooks` / `webhooks` plugin / `Task Flow`
本地媒体工作流	零散脚本 + 图形界面切换	官方 `ComfyUI` provider/plugin

一句话总结：

“推理类”需求优先走 openclaw infer
**“会话内自动调用”**优先交给 agent 工具（image_generate、video_generate、music_generate、tts）
**“外部系统驱动”**优先走 hooks、webhooks plugin 和 Task Flow
只有这些都不满足时，再考虑自定义 plugin 或外部中间层

10.2 先把 provider 和模型能力配好

在开始接入任何 API 前，先确保 OpenClaw 自己已经能正常访问模型与媒体能力。最短路径：

bash

# 1) 推荐：先走引导向导
openclaw onboard

# 2) 查看模型与认证状态
openclaw models status
openclaw models list

# 3) 按 provider 登录
openclaw models auth login --provider openai --set-default
openclaw models auth login --provider anthropic --method cli --set-default

# 4) 设置主模型与图像理解兜底模型
openclaw models set openai/gpt-5.4
openclaw models set-image openai/gpt-4.1-mini

如果你是多 provider 环境，建议同时配好主模型和回退链：

bash

openclaw models set openai/gpt-5.4
openclaw models fallbacks add anthropic/claude-sonnet-4-5
openclaw models fallbacks add google/gemini-2.5-pro

什么时候需要 models status --probe？

你怀疑 token 已过期
provider 列表看着有，但实测不通
刚切换了 OAuth / API key，需要确认可用性

bash

openclaw models status --probe

看到什么算配置成功

如果下面这些都成立，说明你已经可以继续往下学：

openclaw models status 能看到主模型和已登录 provider
openclaw models status --probe 没有明显的 auth / token 错误
你已经知道自己默认要走哪条模型路线

如果这里都不通，先别急着接外部系统。先把模型认证和默认模型配通，再往后走。

10.3 `openclaw infer`：当前最重要的统一入口

官方文档已经明确：openclaw infer 是当前标准的无头能力入口。它覆盖：

文本推理
图片生成 / 编辑 / 描述
音频转写
语音合成
视频生成 / 描述
Web 搜索 / 抓取
Embedding 创建

10.3.1 常用命令速览

bash

openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
openclaw infer image generate --prompt "friendly lobster illustration" --json
openclaw infer audio transcribe --file ./memo.m4a --json
openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json
openclaw infer video generate --prompt "cinematic sunset over the ocean" --json
openclaw infer web search --query "OpenClaw docs" --json
openclaw infer embedding create --text "friendly lobster" --json

对小白来说，不要一口气全跑。最稳的顺序是：

先跑 model run，确认文本模型能用
再跑 web search，确认联网推理路径没问题
需要哪种媒体能力，再单独测哪一个

这样一旦失败，你更容易知道是模型认证问题、文件路径问题，还是媒体 provider 没配好。

10.3.2 文本推理：把零散脚本换成标准命令

bash

openclaw infer model run   --prompt "用 5 条 bullet 总结 OpenClaw v2026.9.3 的主要变化"   --json

适合：

shell 脚本里做一跳摘要
CI 里做 release note 总结
给下游自动化产出稳定 JSON

10.3.3 图片生成：默认走官方能力

bash

openclaw infer image generate   --prompt "一张手写白板风格的 OpenClaw 工作流示意图"   --json

如果你是从现有文件继续改图，用 image edit；如果你要读图说明内容，用 image describe：

bash

openclaw infer image describe   --file ./ui-screenshot.png   --model openai/gpt-4.1-mini   --json

注意：image describe 这类命令的 --model 必须写成完整的 <provider/model> 形式。

10.3.4 音频转写：不要再手写 whisper 脚本

bash

openclaw infer audio transcribe   --file ./team-sync.m4a   --language zh   --prompt "重点提取人名、决策与行动项"   --json

适合：

会议纪要
播客拆解
微信语音 / 飞书语音整理

10.3.5 TTS：统一走 `tts convert`

bash

openclaw infer tts convert   --text "今天的日报已经生成完成"   --output ./daily-report.mp3   --json

如果你是在 agent 对话里，需要回复直接带语音，优先让 agent 自动调用 tts 工具；如果你是在脚本、批处理或自动化流水线里，优先用 infer tts convert。

10.3.6 视频生成：现在是异步任务，不是同步截图脚本

bash

openclaw infer video generate   --prompt "一段 5 秒的电影感镜头：小龙虾在日落海边冲浪"   --json

需要注意两点：

视频生成通常是异步长任务，底层 provider 会先返回任务 id
OpenClaw 会把视频任务纳入 task ledger，必要时你可以配合 openclaw tasks list 查看进度

10.3.7 Web 搜索与抓取：先用官方再谈爬虫

bash

openclaw infer web search --query "OpenClaw v2026.9.3 release notes" --json
openclaw infer web fetch --url https://docs.openclaw.ai/cli/infer --json

这套命令特别适合：

自动化日报
竞品监控
资料初筛
内容采编前的资料抓取

10.3.8 Embedding：统一走 `embedding create`

bash

openclaw infer embedding create   --text "客户反馈：物流延迟、赔付说明不清晰"   --json

适合：

FAQ 聚类
工单语义归类
外部知识库入库前向量化

10.4 外部系统怎么接？用 Hooks、Webhooks Plugin 和 Task Flow

10.4.1 轻量触发：`hooks`

如果只是让外部系统“叫醒” OpenClaw 或启动一次 isolated agent run，最轻的方案是 hooks。

配置示例：

json

{
  "hooks": {
    "enabled": true,
    "token": "replace-with-dedicated-hook-token",
    "path": "/hooks"
  }
}

唤醒主会话：

bash

curl -X POST http://127.0.0.1:18789/hooks/wake   -H 'Authorization: Bearer SECRET'   -H 'Content-Type: application/json'   -d '{"text":"New email received","mode":"now"}'

启动一次 isolated agent run：

bash

curl -X POST http://127.0.0.1:18789/hooks/agent   -H 'Authorization: Bearer SECRET'   -H 'Content-Type: application/json'   -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}'

适合场景：

表单提交后触发摘要
新邮件 / 新工单到来后做初筛
CI 成功后让 OpenClaw 生成更新说明

10.4.2 复杂编排：`webhooks` plugin + Task Flow

如果你需要多步骤、可追踪、能继续推进的工作流，直接上 webhooks plugin。

官方配置示例：

json

{
  "plugins": {
    "entries": {
      "webhooks": {
        "enabled": true,
        "config": {
          "routes": {
            "zapier": {
              "path": "/plugins/webhooks/zapier",
              "sessionKey": "agent:main:main",
              "secret": {
                "source": "env",
                "provider": "default",
                "id": "OPENCLAW_WEBHOOK_SECRET"
              },
              "controllerId": "webhooks/zapier",
              "description": "Zapier TaskFlow bridge"
            }
          }
        }
      }
    }
  }
}

创建 flow：

bash

curl -X POST https://gateway.example.com/plugins/webhooks/zapier   -H 'Content-Type: application/json'   -H 'Authorization: Bearer YOUR_SHARED_SECRET'   -d '{"action":"create_flow","goal":"Review inbound queue"}'

在 flow 中再创建子任务：

json

{
  "action": "run_task",
  "flowId": "flow_123",
  "runtime": "acp",
  "childSessionKey": "agent:main:acp:worker",
  "task": "Inspect the next message batch"
}

适合场景：

Zapier / n8n / Make 触发多步任务
客服工单分诊
线索筛选 + 跟进 + 汇总
周报流水线、内容审核流水线

10.4.3 Notion 现在怎么接才对？

本章旧内容里那一大段“Notion Skill 全套配置”最大的问题，不是 Notion 不能接，而是默认路线已经不对了。

现在更稳的做法是：

如果只是把 OpenClaw 结果写入 Notion：优先用 Zapier / n8n / 自家中间层，通过 webhook 接入
如果要形成可持续的内部工作流：用 webhooks plugin 把外部事件绑定到 Task Flow
如果你需要深度定制：自己写 plugin，不要依赖历史第三方 Skill 名称

也就是说：

Notion 依然能接
但它不再应该占据“官方默认主线”的位置
现在的默认主线是 Infer + Hooks/Webhooks + Task Flow + Plugin

10.5 这一章最容易踩的坑

坑 1：继续照着旧 Skill 名称安装

处理方式：

先看官方 docs / release notes
优先确认能力是否已经内建到 infer 或 agent 工具中
只有官方路线没有时，才继续搜社区插件

坑 2：把媒体能力当同步脚本理解

图片和 TTS 多数是同步返回
视频和音乐常常是后台任务
这两类长任务最好配合 openclaw tasks list、openclaw tasks show 观察状态

坑 3：`--model` 没写 provider 前缀

下列命令场景里，建议始终写全：

image describe
audio transcribe
video describe
任何你明确指定 provider 的脚本

正确示例：

bash

openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json

坑 4：把 secret 直接写死在仓库里

官方文档已经明确支持 SecretRef。优先顺序：

env
file
exec

不要把 webhook secret、provider token、第三方 API key 直接写进公开仓库。

10.6 本章实践建议

如果你现在就要把 OpenClaw 接到业务里，推荐按下面的顺序走：

先跑通 openclaw onboard 与 openclaw infer
再配图片 / 视频 / TTS 的默认模型
轻量触发用 hooks
多步骤流程用 webhooks plugin + Task Flow
本地多媒体深度编排再上 ComfyUI

10.7 官方参考

GitHub Releases：https://github.com/openclaw/openclaw/releases
Inference CLI：https://docs.openclaw.ai/cli/infer
Models CLI：https://docs.openclaw.ai/cli/models
Webhooks Plugin：https://docs.openclaw.ai/plugins/webhooks
Scheduled Tasks：https://docs.openclaw.ai/automation/cron-jobs
Task Flow：https://docs.openclaw.ai/automation/taskflow

03 Advanced 11 Advanced Configuration (`docs/03-advanced/11-advanced-configuration.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第11章节高级配置（模型、记忆、审批与性能）

本章目标：把 OpenClaw 当前稳定版里最重要的高级配置讲清楚，包括模型选择、认证、媒体默认模型、Active Memory、Memory Wiki，以及执行审批与安全边界。

版本基线

当前稳定版：v2026.9.3（2026-09-08 发布）
本章默认按 v2026.9.3 写；遇到旧 openai-codex/* / OpenProse / clawhub install … 请先当历史参考

先给小白的阅读说明

这一章到底解决什么问题

很多新手一看到 openclaw.json、models.json、AGENTS.md、provider auth，就会马上开始手改配置。结果往往是：

不知道哪里才是当前生效值
改了配置却没改到真正的默认模型
认证、回退模型、媒体模型混在一起

这一章就是帮你把这些东西拆开。

如果你只想先把配置跑通，先看这几节

先看 11.1：知道推荐顺序
再看 11.2：把主模型、回退模型、认证配通
然后看 11.3：分清会话模型和媒体模型
最后看 11.6：知道安全边界，不要误配审批

开始前的最低前提

你不需要先懂所有 JSON 字段，但至少要满足：

已跑过 openclaw onboard
至少有一个 provider 能成功登录
愿意先用 CLI 看状态，再决定是否手改配置文件

小白最容易犯的 3 个错

一上来就手改 JSON，不先看 models status
把 imageModel 和 imageGenerationModel 当成同一个东西
看到配置项很多，就以为“全都配上才算完整”

11.1 推荐配置路径：先向导，后精调

OpenClaw 2026.4 之后，高级配置的推荐顺序不是“先手改 JSON”，而是：

openclaw onboard
openclaw models auth add|login
openclaw models status|list|set
需要时再手动改 openclaw.json / models.json

最短起步命令：

bash

openclaw onboard
openclaw models status
openclaw models list
openclaw models set openai/gpt-5.4

如果你不知道当前到底配成了什么，先看状态，不要猜：

bash

openclaw models status --probe
openclaw status

看到什么算当前配置已经健康

如果你看到下面这些现象，说明配置已经进入“可继续优化”的状态：

openclaw models status 能看到 primary 和 fallbacks
openclaw models status --probe 没报 provider 不可用或 token 失效
openclaw status 没有明显的 gateway / auth 阻塞错误

models status --probe 会做真实探测，可能消耗 token，但它最适合确认以下问题：

token 是不是过期了
provider 看起来已配置，但是否真能用
当前 primary / fallbacks 最终到底解析成了什么

11.2 模型与认证：当前该怎么配

11.2.1 先理解三层关系

OpenClaw 现在的模型配置可以简化成三层：

主模型：agents.defaults.model.primary
回退模型：agents.defaults.model.fallbacks
认证与 provider 状态：通过 models auth、环境变量和 auth profile 管理

11.2.2 常用命令

如果你是第一次接触这些命令，可以把它们理解成下面 4 类：

status / list：先看现状
set：设置主模型
fallbacks add：给主模型准备兜底
auth login：解决“为什么看得到 provider 却用不了”

bash

# 查看当前状态
openclaw models status
openclaw models list

# 设置主模型
openclaw models set openai/gpt-5.4

# 增加回退模型
openclaw models fallbacks add anthropic/claude-sonnet-4-5
openclaw models fallbacks add google/gemini-2.5-pro

# 设置图像理解兜底模型
openclaw models set-image openai/gpt-4.1-mini
openclaw models image-fallbacks add google/gemini-2.5-pro

11.2.3 当前值得注意的 provider 变化

根据官方 release notes（2026.8.1 OpenClaw 2.0 → v2026.9.3）：

2026.8.1 起：会话/转录迁入 SQLite；升级前务必备份 ~/.openclaw
OpenAI 路由迁移（Breaking）：旧的 codex/*、openai-codex/* 应迁移为规范的 openai/*；执行 openclaw doctor --fix
OpenProse 已移除（Breaking）：内置 OpenProse 插件与 /prose 已下线；清配置用 openclaw doctor --fix，需要时再按官方文档安装上游 Agent Skill
v2026.9.3：更新预演/恢复更稳；Skill Workshop 改为按 Agent 持久化集合；Node 要求提升到 24.16+ / 26.1+
具体可选模型 ID 请以 openclaw models list / Control UI 目录为准，不要照抄过期型号

如果你要做编程工作流，当前更推荐先走：

openai/...（ChatGPT/Codex 订阅或 API；用 models auth login --provider openai）
anthropic/...
google/...

11.2.4 认证方式建议

bash

# 交互式添加 provider 认证
openclaw models auth add

# 直接对某个 provider 发起登录
openclaw models auth login --provider openai --set-default
openclaw models auth login --provider anthropic --method cli --set-default

如果你是自托管 provider 或 OpenAI-compatible endpoint，优先保证：

baseUrl 可达
API key 已注入
仅在可信私网环境里启用 models.providers.*.request.allowPrivateNetwork

11.3 媒体默认模型：不要再把图片、视频、音乐混着配

官方现在把“会话模型”和“媒体生成模型”拆得很清楚。你至少要分清 5 类默认模型：

agents.defaults.model
agents.defaults.imageModel
agents.defaults.imageGenerationModel
agents.defaults.videoGenerationModel
agents.defaults.musicGenerationModel

推荐配置示例：

json

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-5.4",
        "fallbacks": [
          "anthropic/claude-sonnet-4-5",
          "google/gemini-2.5-pro"
        ]
      },
      "imageModel": {
        "primary": "openai/gpt-4.1-mini"
      },
      "imageGenerationModel": {
        "primary": "openai/gpt-image-1"
      },
      "videoGenerationModel": {
        "primary": "google/veo-3.1-fast-generate-preview",
        "fallbacks": [
          "qwen/wan2.6-r2v-flash"
        ]
      },
      "musicGenerationModel": {
        "primary": "google/lyria-3-clip-preview"
      }
    }
  }
}

几点说明：

imageModel 用于“主模型不能直接看图”时的图像理解兜底
imageGenerationModel 专门给 image_generate 用
videoGenerationModel 和 musicGenerationModel 只影响共享媒体工具
如果你没有显式配置，OpenClaw 也会尝试根据已认证 provider 自动推断默认值，但生产环境不建议完全依赖自动推断

11.4 Active Memory：让记忆在回复前主动介入

v2026.4.12 的一个核心变化，是 Active Memory plugin 进入主线能力：它会在主回复前先跑一次受限的记忆子代理，用 memory_search / memory_get 拉回和当前会话相关的偏好、上下文和历史事实。

11.4.1 推荐起步配置

json

{
  "plugins": {
    "entries": {
      "active-memory": {
        "enabled": true,
        "config": {
          "agents": ["main"],
          "allowedChatTypes": ["direct"],
          "modelFallbackPolicy": "default-remote",
          "queryMode": "recent",
          "promptStyle": "balanced",
          "timeoutMs": 15000,
          "maxSummaryChars": 220,
          "persistTranscripts": false,
          "logging": true
        }
      }
    }
  }
}

11.4.2 什么时候该开，什么时候别开

适合开启：

私聊型、长期关系型助手
高频重复协作
需要记住偏好、习惯、上下文的场景

不适合默认开启：

纯自动化 worker
一次性 API 任务
强确定性流水线
你不希望隐藏个性化影响输出的场景

11.4.3 调试方法

bash

openclaw memory status --deep

在聊天里可以用 /verbose on 看 Active Memory 的状态行。调优优先从这几个参数入手：

queryMode
promptStyle
timeoutMs
maxSummaryChars

11.5 Memory Wiki：把长期记忆变成“可维护的知识层”

memory-wiki 是官方内建 plugin，它不是用来替代 memory-core 的，而是把长期记忆编译成结构化 wiki 层，适合：

项目知识沉淀
客户画像 / 产品知识整理
知识冲突排查
长周期研究类任务

11.5.1 官方推荐理解方式

memory-core / QMD / dreaming：负责 recall、promotion、search、dreaming
memory-wiki：负责把 durable memory 编译成可导航的 wiki 页面与结构化 claim/evidence

11.5.2 推荐配置示例

json

{
  "plugins": {
    "entries": {
      "memory-wiki": {
        "enabled": true,
        "config": {
          "vaultMode": "isolated",
          "vault": {
            "path": "~/.openclaw/wiki/main",
            "renderMode": "obsidian"
          },
          "bridge": {
            "enabled": false,
            "readMemoryArtifacts": true,
            "indexDreamReports": true,
            "indexDailyNotes": true,
            "indexMemoryRoot": true,
            "followMemoryEvents": true
          },
          "ingest": {
            "autoCompile": true,
            "maxConcurrentJobs": 1,
            "allowUrlIngest": true
          },
          "search": {
            "backend": "shared",
            "corpus": "wiki"
          },
          "context": {
            "includeCompiledDigestPrompt": false
          },
          "render": {
            "preserveHumanBlocks": true,
            "createBacklinks": true,
            "createDashboards": true
          }
        }
      }
    }
  }
}

11.5.3 常用命令

bash

openclaw wiki init
openclaw wiki status
openclaw wiki compile
openclaw wiki lint
openclaw wiki search "customer onboarding"
openclaw wiki get entity.alpha

推荐工作流：

先让 memory-core 跑稳
再开 memory-wiki
默认优先 isolated 模式
如果你明确需要从现有 memory artifact 构建 wiki，再启用 bridge

11.6 执行审批、安全与自托管边界

11.6.1 不要只看 `exec`，要同时看 approval 文件与 tool policy

v2026.4.12 增加了本地 exec-policy 命令，目标是把 tools.exec.* 配置和本机审批文件同步起来。但实际落地时，你仍然要同时理解三层东西：

tools.exec.*
~/.openclaw/exec-approvals.json
agent 的 tool policy / allowlist

最实用的检查命令：

bash

openclaw exec-policy show
openclaw approvals get
openclaw approvals get --gateway

如果你要给某些命令做 allowlist：

bash

openclaw approvals allowlist add "~/Projects/**/bin/rg"
openclaw approvals allowlist add --agent main "/usr/bin/uname"

11.6.2 Hook / Webhook 的安全底线

Hook token 和 gateway token 分开
不要把 hook 暴露在根路径 /
hooks.path 保持独立子路径
Webhook 路由尽量绑定最小 sessionKey
Secret 优先走 env / file / exec，不要写死到仓库里

11.6.3 自托管 provider 的私网配置

v2026.4.12 官方加入了 models.providers.*.request.allowPrivateNetwork，用于你明确知道自己在访问可信私网 provider 时放开限制。这个开关非常有用，但也只应该用于你完全控制的私网服务。

适用场景：

自己的 LM Studio / OpenAI-compatible endpoint
内网部署的代理层
VPN / Tailnet 内的推理网关

不适用场景：

公网随便开的代理地址
不明来源共享网关
混合代理环境里没有明确边界的 endpoint

11.7 性能调优：2026.4 值得关注的点

11.7.1 先做“结构性调优”，再做“参数性调优”

最有效的顺序通常是：

先把主模型 / 回退链配清楚
再把媒体模型单独拆开
再开 Active Memory / Memory Wiki
最后才调 thinking、context、fallback 数量

11.7.2 本地模型用户的新补充

历史 v2026.4.15-beta.1 里曾新增过一个本地模型实验参数：

json

{
  "agents": {
    "defaults": {
      "experimental": {
        "localModelLean": true
      }
    }
  }
}

它会在弱本地模型场景下去掉一些重量级默认工具，降低提示词体积。注意这是历史 beta 能力，在 v2026.9.3 环境里请先查官方配置文档和 openclaw config schema，不要直接照抄到生产主环境。

11.7.3 本章推荐的检查顺序

bash

openclaw status
openclaw models status --probe
openclaw memory status --deep
openclaw wiki status
openclaw approvals get
openclaw security audit

11.8 本章实践建议

如果你正在配一套长期可用的 OpenClaw 环境，最稳的顺序是：

先配好 models auth、主模型和回退链
再单独配图片 / 视频 / 音乐模型
需要长期关系型助手时再开 Active Memory
需要“可维护知识层”时再开 Memory Wiki
最后再收紧 exec approvals、hook token 和私网 provider 边界

11.9 官方参考

GitHub Releases：https://github.com/openclaw/openclaw/releases
Models CLI：https://docs.openclaw.ai/cli/models
Model Concepts：https://docs.openclaw.ai/concepts/models
Inference CLI：https://docs.openclaw.ai/cli/infer
Active Memory：https://docs.openclaw.ai/concepts/active-memory
Memory Wiki：https://docs.openclaw.ai/plugins/memory-wiki
Exec Approvals：https://docs.openclaw.ai/cli/approvals

03 Advanced Feishu Checklist (`docs/03-advanced/feishu-checklist.md`)

飞书Bot配置检查清单

✅ 使用本清单确保飞书Bot配置完整，避免常见问题

📋 配置前准备

已安装 OpenClaw（版本 2026.3.2+）
已注册飞书开放平台账号
已创建企业/团队（个人也可以）
网络可以访问飞书开放平台

🔧 应用创建（飞书开放平台）

1. 创建应用

登录飞书开放平台：https://open.feishu.cn
点击"创建企业自建应用"
填写应用信息：
- 应用名称（如：OpenClaw助手）
- 应用描述
- 应用图标
记录 App ID 和 App Secret

2. 配置机器人

进入"应用功能" → "机器人"
启用机器人功能
设置机器人名称
设置机器人描述
上传机器人头像

3. 配置权限（⭐ 重要）

在"权限管理"页面，添加以下权限：

必需权限（缺一不可）

im:message - 获取与发送单聊、群组消息
im:message:send_as_bot - 以应用身份发消息
contact:contact.base:readonly - 获取通讯录基本信息 ⭐

⚠️ 特别注意：contact:contact.base:readonly 是最容易遗漏的权限！

如果缺少此权限：

❌ 机器人无法识别用户

❌ 无法响应任何消息

❌ 日志中会出现 "User not found" 错误

可选权限（根据需要添加）

im:message:group_at_msg:readonly - 获取群组中@机器人的消息
im:message:group_msg:readonly - 获取群组消息
im:chat - 获取群组信息
contact:user.base:readonly - 获取用户详细信息

4. 配置事件订阅

在"事件订阅"页面：

选择"使用长连接接收事件"（WebSocket 模式）
添加事件：im.message.receive_v1（接收消息）
确认长连接状态显示"已连接"

💡 提示：如果长连接无法建立，请先完成下面的 OpenClaw 配置步骤

5. 发布应用

点击"版本管理与发布"
创建版本
填写版本说明
提交审核（企业自建应用通常自动通过）
确认应用状态为"已发布"

6. 设置可用范围

在"可用性"页面设置可用范围
添加可使用的部门或成员
或选择"全员可用"

💻 OpenClaw 配置

1. 添加飞书渠道

bash

# 运行添加渠道命令
openclaw channels add

# 选择 Feishu
# 输入 App ID
# 输入 App Secret
```text
**检查配置**：
```bash
# 查看渠道列表
openclaw channels list

# 应该看到 feishu 渠道
```text
### 2. 启动网关

```bash
# 启动网关
openclaw gateway start

# 检查状态
openclaw gateway status

# 应该显示 "running"
```text
### 3. 验证配置

```bash
# 测试飞书连接
openclaw channels test feishu

# 应该显示连接成功
```text
---

## 🧪 测试验证

### 1. 基础测试

- [ ] 在飞书中搜索并添加机器人
- [ ] 发送消息："你好"
- [ ] 机器人应该回复

### 2. 功能测试

- [ ] 测试文本消息
- [ ] 测试文件发送（如果需要）
- [ ] 测试图片发送（如果需要）
- [ ] 测试群组消息（需要@机器人）

### 3. 权限测试

- [ ] 机器人能识别用户名
- [ ] 机器人能正常回复
- [ ] 访问控制正常工作（如果配置了）

---

## 🔍 故障排查

### 机器人不回复？

按以下顺序检查：

1. **检查权限（最常见问题）**
   ```text
   ✅ im:message
   ✅ im:message:send_as_bot
   ✅ contact:contact.base:readonly ⭐ 必需

检查事件订阅

text

✅ 已选择"长连接"模式
✅ 已添加 im.message.receive_v1
✅ 长连接状态"已连接"

检查应用状态

text

✅ 应用已发布
✅ 应用已通过审核
✅ 用户在可用范围内

检查 OpenClaw

bash

# 检查网关状态
openclaw gateway status

# 查看日志
openclaw logs --follow

# 检查渠道配置
openclaw channels list

查看详细日志

bash

# 实时查看日志
openclaw logs --follow

# 过滤飞书相关日志
openclaw logs --follow | grep feishu

# 查看最近100行日志
openclaw logs --tail 100

常见错误及解决

错误信息	原因	解决方案
`Permission denied`	缺少权限	添加所有必需权限
`User not found`	缺少通讯录权限	添加 `contact:contact.base:readonly`
`Connection failed`	网关未启动	运行 `openclaw gateway start`
`Invalid app_id`	AppID错误	检查配置
`Long connection failed`	长连接失败	确保网关已启动再配置事件订阅

📚 相关文档

💡 最佳实践

开发建议

先测试后发布
- 在测试环境完成配置
- 充分测试后再发布到生产环境
权限最小化
- 只添加必需的权限
- 定期审查权限使用情况
日志监控
- 定期查看日志
- 及时发现和解决问题
备份配置
- 定期备份 OpenClaw 配置
- 记录飞书应用的配置信息

安全建议

保护密钥
- 不要将 App Secret 提交到代码仓库
- 使用环境变量存储敏感信息
访问控制
- 配置 allowlist 限制可访问用户
- 定期审查访问日志
定期更新
- 保持 OpenClaw 版本最新
- 关注飞书平台的更新公告

最后更新：2026年2月14日
适用版本：OpenClaw 2026.3.2+

04 Practical Cases 12 Personal Productivity (`docs/04-practical-cases/12-personal-productivity.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第12章节个人效率实战（知识工作、编程、创作、学习、个人运营）

本章目标：不再用一堆失效 Skill 名称堆案例，而是基于 OpenClaw v2026.9.3 的官方能力，给出 5 类高频个人效率工作流。

版本基线

当前稳定版：v2026.9.3（2026-09-08 发布）
本章默认按 v2026.9.3 稳定版写

先给小白的阅读说明

这一章不要整章硬啃

这章不是让你把 5 类场景一次全搭完，而是让你先选一个最贴近自己工作的身份，先跑通一个小工作流。

怎么选自己应该先看哪一节

你做运营、产品、咨询、项目管理：先看 12.1
你主要写代码：先看 12.2
你是内容创作者：先看 12.3
你是学生或研究者：先看 12.4
你只是想先把系统跑稳定：先看 12.5

小白第一周最推荐做的事

不要一上来追求“自动化闭环”，而是先做 3 件立刻有回报的事：

做一个晨间 Brief
跑一次会议录音转纪要
把一份常用资料写进 Memory Wiki

这样你很快就能判断：OpenClaw 到底值不值得继续投入。

12.1 知识工作者：早报、资料整理、会议纪要

12.1.1 最值得先搭的不是“超大系统”，而是晨间 Brief

对于咨询、运营、产品、项目管理这类工作，OpenClaw 最先带来收益的不是复杂 agent 编排，而是：

固定时间自动收集信息
统一整理成结构化摘要
通过已配置渠道投递给你

推荐直接用 cron。对小白来说，你可以先把它理解成：每天固定时间，让 OpenClaw 帮你发一份日报。

推荐直接用 cron：

bash

openclaw cron add   --name "Morning brief"   --cron "0 7 * * *"   --tz "Asia/Shanghai"   --session isolated   --message "Summarize overnight updates, open tasks, and calendar priorities for today."   --announce

配合：

bash

openclaw infer web search --query "OpenClaw v2026.9.3 release notes" --json
openclaw infer web fetch --url https://docs.openclaw.ai/cli/infer --json

12.1.2 会议纪要的正确打法

旧教程里大量“手写模板 + 第三方 Skill”式会让读者先配一堆东西再开始。现在更简单：

把音频文件丢给 audio transcribe
再让主模型做结构化摘要
需要长期沉淀时写入 Memory Wiki

bash

openclaw infer audio transcribe   --file ./meeting.m4a   --language zh   --prompt "只保留决策、负责人和截止日期"   --json

看到什么算这条流程跑通

你能拿到一份完整转写结果
你能再让模型把它整理成结构化纪要
你知道哪些内容值得长期沉淀进 Wiki，哪些只需要临时看一眼

然后把转写结果交给 OpenClaw：

text

请把这段会议转写整理成：背景、结论、行动项、风险点、需复盘的问题。

12.1.3 这类人最适合开的配置

Active Memory：开
Memory Wiki：看情况开
cron：一定要用
Task Flow：有多步骤交付流程时再上

12.2 程序员：代码协作、调试跟踪、知识沉淀

12.2.1 模型建议

如果你是以“代码交付”为主，优先把编程模型路线配清楚：

bash

openclaw models auth login --provider openai --set-default
openclaw models set openai/gpt-5.4
openclaw models fallbacks add anthropic/claude-sonnet-4-5

12.2.2 日常最有价值的 3 件事

如果你是程序员，不要把 OpenClaw 只当聊天机器人。更实用的方式是把它当成：

调试信息整理器
代码知识沉淀器
重复任务自动化助手

1）仓库级检索与整理

text

帮我先读 AGENTS.md、README 和 package.json，然后列出这个仓库最关键的 5 个约束。

2）长任务可追踪

比如测试、生成、子任务调度，这类 detached work 现在都能进入任务账本：

bash

openclaw tasks list
openclaw tasks audit
openclaw tasks show <task-id>

3）知识沉淀到 Wiki

你会发现“已踩过的坑”比“新文档”更值钱。推荐把下面这些内容放进 wiki：

项目结构说明
环境依赖
常见报错和处理路径
发布流程
不要碰的历史包袱

bash

openclaw wiki init
openclaw wiki search "build pipeline"
openclaw wiki lint

12.2.3 推荐的程序员工作流

AGENTS.md 写清仓库约束与 review 规则
cron 跑健康检查 / 每周依赖审计
tasks audit 看长任务是否卡住
wiki_apply / wiki_compile 维护工程知识层

12.3 内容创作者：研究、配图、配音、版本复用

12.3.1 研究不要再靠手动搜 20 个标签页

推荐流程：

infer web search 抓方向
infer web fetch 拿关键页面
让主模型输出：观点框架、内容提纲、脚本骨架

bash

openclaw infer web search --query "OpenClaw Active Memory plugin use cases" --json
openclaw infer web fetch --url https://docs.openclaw.ai/concepts/active-memory --json

12.3.2 配图、视频、语音现在都走官方入口

bash

openclaw infer image generate --prompt "一张手写白板风格的知识管理工作流图" --json
openclaw infer tts convert --text "今天的视频脚本已经完成" --output ./notify.mp3 --json
openclaw infer video generate --prompt "5 秒产品演示镜头：桌面上的 OpenClaw 仪表盘" --json

要点：

图片与 TTS 更适合脚本内直接调用
视频通常是后台任务，适合交给 agent + tasks ledger 追踪
音乐生成走 music_generate，不是旧教程里的零散外部脚本

12.3.3 创作者最实用的配置

imageGenerationModel
videoGenerationModel
musicGenerationModel
tts provider
Task Flow（当你要把“研究 → 写作 → 生成素材 → 投递”串起来时）

12.4 学生 / 研究者：论文、课程、复习、长期记忆

12.4.1 论文阅读的正确分层

不要一上来就追求“自动读完所有 PDF”。更稳的路径是：

搜索与筛选
摘要与术语解释
结构化记忆沉淀
周期性回顾

你可以这样做：

bash

openclaw infer web search --query "multimodal memory retrieval benchmark 2026" --json

然后让 OpenClaw 输出：

摘要
方法对比
值得深读的 3 篇
应该记住的术语

12.4.2 课程与项目资料怎么长期可用

这类场景最适合 Memory Wiki：

entities/ 放课程、项目、导师、数据集
concepts/ 放概念、方法、术语
reports/ 看低置信度、冲突、待补证据条目

推荐习惯：

bash

openclaw wiki search "transformer"
openclaw wiki get concept.transformer
openclaw wiki lint

12.4.3 学生场景下不建议开的东西

默认对所有会话都开 Active Memory
没有边界就让 agent 自动执行 shell
把作业生成当作“全自动答案系统”

更稳妥的方式是：

用它做资料整理、理解辅助、复习计划和项目追踪
高风险输出（作业、论文结论）必须人工复核

12.5 个人运营：用最少维护成本盯住系统状态

不管你是哪种用户，最后都建议留一套“个人运维面板”：

bash

openclaw status
openclaw models status --probe
openclaw cron list
openclaw tasks audit
openclaw memory status --deep
openclaw wiki status

建议每周固定检查 5 件事：

主模型和回退链是否仍可用
定时任务有没有失效或跑偏
长任务是否有 stale_running / lost
记忆搜索是否仍能命中有效信息
wiki 是否出现大量 low-confidence / stale-pages

12.6 本章落地顺序建议

如果你是第一次认真把 OpenClaw 用进日常工作，推荐顺序：

先做一个晨间 Brief
再做一个自己最痛的单点流程（会议纪要 / 代码审查 / 资料整理）
之后再开 Active Memory
稳定后再上 Memory Wiki
真正多步骤、跨系统的时候再引入 Task Flow

这比一开始就追求“全自动超级系统”成功率高得多。

12.7 官方参考

GitHub Releases：https://github.com/openclaw/openclaw/releases
Scheduled Tasks：https://docs.openclaw.ai/automation/cron-jobs
Background Tasks：https://docs.openclaw.ai/automation/tasks
Task Flow：https://docs.openclaw.ai/automation/taskflow
Active Memory：https://docs.openclaw.ai/concepts/active-memory
Memory Wiki：https://docs.openclaw.ai/plugins/memory-wiki
Inference CLI：https://docs.openclaw.ai/cli/infer

04 Practical Cases 13 Advanced Automation (`docs/04-practical-cases/13-advanced-automation.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第13章节高级自动化工作流（Cron / Tasks / Task Flow / Hooks / Standing Orders）

本章目标：建立一套符合 OpenClaw 当前官方设计的自动化观念，不再混淆 cron、heartbeat、tasks、Task Flow、hooks 和 standing orders 的职责边界。

版本基线

当前稳定版：v2026.9.3（2026-09-08 发布）
自动化章节默认按 v2026.9.3 稳定版行为说明；升级后先 openclaw doctor --fix

先给小白的阅读说明

这章最重要的不是命令，而是顺序

很多人一上来就学 Task Flow，最后反而越学越乱。更适合小白的顺序是：

先学 cron
再学怎么看 tasks
最后再上 Task Flow、hooks、standing orders

如果你只想先做一个能用的自动化

请先完成这一条最小路径：

用 cron 建一个每天早上跑的任务
用 tasks list 看它有没有进入后台账本
用 tasks show 看一次任务详情

如果这 3 步你都能完成，再往后看多步骤编排。

这章适合谁

已经能稳定使用 OpenClaw，但想把重复工作交给它
想把“提醒、报表、扫描、汇总”变成固定流程
想接外部触发，但还分不清 hooks 和 webhooks

13.1 先把 6 个概念分清楚

机制	适合什么	什么时候用
`cron`	精确时间触发	每天、每周、一次性提醒、定时报表
`heartbeat`	近似定期检查	需要持续“巡检主会话”而不是严格时刻
`tasks`	记录后台工作	看 detached work 跑了什么、卡在哪
`Task Flow`	多步骤可恢复编排	A→B→C 这类 durable 流程
`hooks`	外部轻量触发	外部系统来一个事件，叫醒主会话或跑 isolated job
`standing orders`	长期授权规则	把“你拥有哪些固定职责”写进 `AGENTS.md`

官方文档的核心观点非常一致：

cron 是调度器
tasks 是后台工作账本
Task Flow 是位于 tasks 之上的耐久编排层
standing orders 是 agent 的长期运营授权，不是调度器本身

13.2 `cron`：时间驱动自动化的第一选择

13.2.1 一次性提醒

这是最适合新手先练手的例子，因为它结构最简单：到了某个时间点，发一次提醒，然后结束。

bash

openclaw cron add   --name "Reminder"   --at "2026-05-01T16:00:00Z"   --session main   --system-event "Reminder: review the launch checklist"   --wake now   --delete-after-run

13.2.2 每日定时报表

bash

openclaw cron add   --name "Morning brief"   --cron "0 7 * * *"   --tz "Asia/Shanghai"   --session isolated   --message "Summarize overnight updates, key tasks, and calendar priorities."   --announce

13.2.3 运维常用命令

看到什么算 `cron` 已经跑通

你至少要会检查这 3 件事：

openclaw cron list 里能看到你刚创建的任务
openclaw cron runs --id <job-id> 能看到实际运行记录
如果任务是长时间运行的，tasks list 里也能看到对应后台任务

bash

openclaw cron list
openclaw cron runs --id <job-id>
openclaw cron run <job-id>
openclaw cron edit <job-id> --message "Updated prompt"
openclaw cron remove <job-id>

13.2.4 现在应该怎么选 session 模式

main：适合提醒、系统事件、继续主会话上下文
isolated：适合日报、扫描、报告、批处理
current：适合绑定当前会话的重复任务
session:custom-id：适合每天都延续同一份上下文的固定流程

13.3 `tasks`：先学会看账本，再谈复杂编排

很多人把自动化做复杂了，最后却不知道“到底什么在跑、哪里失败了”。这就是 tasks 的意义。

13.3.1 你最该会的命令

bash

openclaw tasks list
openclaw tasks show <task-id>
openclaw tasks cancel <task-id>
openclaw tasks audit

13.3.2 `tasks audit` 最有价值的地方

它会直接告诉你是否存在：

stale_queued
stale_running
lost
delivery_failed
missing_cleanup
inconsistent_timestamps

如果你已经在用：

视频生成
音乐生成
isolated cron
subagent / ACP 子任务

那 tasks audit 应该成为你的固定巡检动作。

13.4 `Task Flow`：多步骤流程的标准编排层

Task Flow 适合：

多步骤串行或分支流程
要求持久化状态
需要在 gateway 重启后继续
需要统一查看流程进度

13.4.1 两种模式

Managed mode：Task Flow 自己驱动每一步任务

适合：

周报流水线
内容生产流水线
审批后自动交付

Mirrored mode：Task Flow 只观察外部任务并同步状态

适合：

已经有 cron / CLI / 外部系统在生成任务
你只是想把多个任务收敛成一个流程视图

13.4.2 CLI 命令

bash

openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>

13.4.3 什么时候不要上 Task Flow

以下情况先别急着上：

只是单次后台任务
只是每天一个固定提醒
你还不会看 tasks list / tasks audit
工作流步骤还没稳定，今天改一版、明天改一版

这时先用 cron 或 isolated job 更稳。

13.5 `hooks` 与 `webhooks` plugin：把外部系统接进来

13.5.1 轻量触发：`hooks`

官方 hooks 适合外部事件进来后：

唤醒主会话
触发一次 isolated agent run

配置：

json

{
  "hooks": {
    "enabled": true,
    "token": "replace-with-dedicated-hook-token",
    "path": "/hooks"
  }
}

调用 wake：

bash

curl -X POST http://127.0.0.1:18789/hooks/wake   -H 'Authorization: Bearer SECRET'   -H 'Content-Type: application/json'   -d '{"text":"New invoice received","mode":"now"}'

调用 agent：

bash

curl -X POST http://127.0.0.1:18789/hooks/agent   -H 'Authorization: Bearer SECRET'   -H 'Content-Type: application/json'   -d '{"message":"Summarize the new invoice and extract payable date","name":"Finance","model":"openai/gpt-5.4-mini"}'

13.5.2 多步骤编排：`webhooks` plugin

如果你是 Zapier、n8n、CI、表单系统来驱动复杂流程，直接用 webhooks plugin 绑定 Task Flow。官方配置形态：

json

{
  "plugins": {
    "entries": {
      "webhooks": {
        "enabled": true,
        "config": {
          "routes": {
            "ops": {
              "path": "/plugins/webhooks/ops",
              "sessionKey": "agent:main:main",
              "secret": {
                "source": "env",
                "provider": "default",
                "id": "OPENCLAW_WEBHOOK_SECRET"
              },
              "controllerId": "webhooks/ops",
              "description": "Ops TaskFlow bridge"
            }
          }
        }
      }
    }
  }
}

最常用两个动作：

create_flow
run_task

这比旧教程里一堆 shell glue code 更稳定，也更方便排障。

13.6 `standing orders`：自动化不是“计划”，而是“长期授权”

OpenClaw 官方现在把 standing orders 讲得很清楚：它们不是某个定时器，而是写在 agent workspace 里的长期授权规则。推荐直接放在 AGENTS.md 里，因为这个文件会自动注入到每次会话。

13.6.1 一个合格的 standing order 长什么样

## Program: Weekly Status Report

**Authority:** Compile data, generate report, deliver to stakeholders
**Trigger:** Every Friday at 4 PM (enforced via cron job)
**Approval gate:** None for standard reports. Flag anomalies for human review.
**Escalation:** If data source is unavailable or metrics look unusual

### Execution Steps

1. Pull metrics from configured sources
2. Compare to prior week and targets
3. Generate report in Reports/weekly/YYYY-MM-DD.md
4. Deliver summary via configured channel
5. Log completion to Agent/Logs/

### What NOT to Do

- Do not send reports to external parties
- Do not modify source data
- Do not skip delivery if metrics look bad

13.6.2 为什么它重要

没有 standing orders：

你每次都要重复下达同样的管理指令
agent 只能“被动等你叫”
routine work 很容易中断

有 standing orders：

责任边界更清楚
人工审批点更清楚
agent 的长期行为更可控
cron 只负责“何时跑”，AGENTS.md 负责“跑什么、什么时候停”

13.7 推荐的自动化组合，不推荐的自动化组合

不推荐组合

只用 shell while true + sleep 模拟调度
用一个超大 prompt 代替 standing orders
还不会看 tasks audit 就上很多 subagent 和 webhook
把外部系统 token 直接写进仓库

13.8 本章实践建议

如果你要从 0 到 1 搭一套稳定自动化，顺序应该是：

先用 cron 跑通一个固定任务
再学会看 tasks list 和 tasks audit
多步骤时再上 Task Flow
外部系统接入时再开 hooks / webhooks plugin
最后把长期职责沉淀进 AGENTS.md

13.9 官方参考

GitHub Releases：https://github.com/openclaw/openclaw/releases
Automation Overview：https://docs.openclaw.ai/automation/cron-vs-heartbeat
Scheduled Tasks：https://docs.openclaw.ai/automation/cron-jobs
Background Tasks：https://docs.openclaw.ai/automation/tasks
Task Flow：https://docs.openclaw.ai/automation/taskflow
Standing Orders：https://docs.openclaw.ai/automation/standing-orders
Webhooks Plugin：https://docs.openclaw.ai/plugins/webhooks

04 Practical Cases 14 Creative Applications (`docs/04-practical-cases/14-creative-applications.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第14章节创意应用实战（图片、视频、音乐、TTS、ComfyUI）

本章目标：把旧教程里零散的“画图 / 视频 / 语音 / 第三方 Skill”写法，收束成 OpenClaw 当前官方支持的媒体工作流。

版本基线

当前稳定版：v2026.9.3（2026-09-08 发布）
本章默认按 v2026.9.3 稳定版写；所有创意能力优先参考官方媒体能力矩阵

先给小白的阅读说明

如果你只是想先做出一个结果，别整章都看

想先出一张图：直接看 14.2
想先生成语音：直接看 14.4.2
想先试视频：直接看 14.3，但要知道视频是异步任务
想做本地可控工作流：最后再看 14.5 的 ComfyUI

开始前要先知道的 2 件事

图片和 TTS 通常是同步返回，比较适合新手先试
视频和音乐通常是后台异步任务，所以不要以为“命令没立刻吐文件就是失败”

小白最容易误会的地方

把“图片理解模型”当成“图片生成模型”
不知道视频生成要去 tasks 里看状态
看见 provider 很多，就误以为每个都必须配置

14.1 先记住这张官方媒体能力图谱

OpenClaw 当前的媒体能力不是零散插件，而是一套共享能力层：

能力	工具 / 命令	常见 provider	说明
图片生成	`image_generate` / `openclaw infer image generate`	ComfyUI、fal、Google、MiniMax、OpenAI、Vydra	文生图、参考图编辑
视频生成	`video_generate` / `openclaw infer video generate`	Alibaba、BytePlus、ComfyUI、fal、Google、MiniMax、OpenAI、Qwen、Runway、Together、Vydra、xAI	文生视频、图生视频、视频转视频
音乐生成	`music_generate`	ComfyUI、Google、MiniMax	生成音乐 / 音轨
TTS	`tts` / `openclaw infer tts convert`	ElevenLabs、Microsoft、MiniMax、OpenAI	把文本转成语音
媒体理解	`image describe` / `audio transcribe` / `video describe`	各类多模态 provider	读图、读音频、读视频

最重要的两点：

图片和 TTS 更偏同步
视频和音乐是异步后台任务，会进入 task ledger，完成后再唤醒 agent 把结果发回原会话

14.2 图片工作流：现在应该怎么做

14.2.1 命令行直出图

如果你是第一次试媒体能力，强烈建议从这里开始，因为它反馈最快，也最容易判断到底是提示词问题，还是 provider 没配好。

bash

openclaw infer image generate   --prompt "一张手写白板风格的 OpenClaw 自动化架构图"   --json

适合：

教程配图
封面图
白板图
社交媒体海报
结构示意图

看到什么算图片能力已经跑通

命令能返回 JSON 结果或文件输出信息
生成效果不满意时，你知道先改提示词，而不是先怀疑整套系统坏了
你已经能分清“命令行直出图”和“会话里让 agent 自动调工具”这两种方式

14.2.2 对话里直接让 agent 生成

text

帮我生成一张白板手写风格的配图，主题是“从 cron 到 Task Flow 的自动化升级路径”。

如果 image_generate 已可用，agent 会自动调用对应工具。相比旧教程里的历史 Skill 名称，这才是当前默认主线。

14.2.3 什么时候要单独配 `imageGenerationModel`

当你满足下面任一情况时，建议手动指定：

团队里统一使用某个 provider
你想严格控制成本
你不希望 OpenClaw 自动推断 provider

json

{
  "agents": {
    "defaults": {
      "imageGenerationModel": {
        "primary": "openai/gpt-image-1"
      }
    }
  }
}

14.3 视频工作流：理解“异步返回”很关键

14.3.1 最短可用示例

视频生成比图片慢很多，所以你第一次测视频时，目标不是“直接出大片”，而是先确认任务能成功入账并最终完成。

bash

openclaw infer video generate   --prompt "一段 5 秒的电影感镜头：桌面上的 OpenClaw 仪表盘正在更新任务状态"   --json

14.3.2 当前视频工作流的正确心智模型

视频生成不是“一条命令马上拿到 mp4”。更准确的过程是：

OpenClaw 把请求发给 provider
provider 返回任务 id
任务进入 background task ledger
完成后 OpenClaw 唤醒原会话，把视频回贴回来

所以你需要学会看：

bash

openclaw tasks list
openclaw tasks show <task-id>
openclaw tasks audit

14.3.3 推荐的视频默认模型写法

bash

openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"

如果你希望带回退链：

json

{
  "agents": {
    "defaults": {
      "videoGenerationModel": {
        "primary": "google/veo-3.1-fast-generate-preview",
        "fallbacks": [
          "qwen/wan2.6-r2v-flash"
        ]
      }
    }
  }
}

14.3.4 适合 OpenClaw 做的视频场景

产品演示短视频
课程片头 / 社交媒体短片
图生视频、视频转视频实验
自动化营销素材流水线中的“中短视频生成”步骤

14.4 音乐生成与 TTS：创意产出的最后两块拼图

14.4.1 音乐生成

当前推荐优先通过 agent 工具 music_generate 使用。根据官方文档，如果你看不到这个工具，优先检查：

provider API key 是否已配置
agents.defaults.musicGenerationModel 是否已配置

推荐配置示例：

json

{
  "agents": {
    "defaults": {
      "musicGenerationModel": {
        "primary": "google/lyria-3-clip-preview"
      }
    }
  }
}

典型 prompt：

text

生成一段 20 秒的轻电子 synthpop 背景音乐，节奏明快，不要人声，适合做 AI 产品介绍短视频配乐。

14.4.2 TTS：脚本里用 `infer`，会话里用 `tts`

bash

openclaw infer tts convert   --text "欢迎来到今天的 OpenClaw 自动化教程。"   --output ./intro.mp3   --json

适合：

视频旁白草稿
日报语音播报
课程试音
产品播报提醒

14.5 ComfyUI：本地 / 可控工作流的官方连接点

旧教程里很多“本地媒体工作流”写法，是靠零散脚本或第三方桥接完成的。现在更推荐：

OpenClaw 继续做调度与对话入口
ComfyUI 负责本地媒体图形工作流
两者通过官方 provider/plugin 接起来

这套组合非常适合：

固定模板的海报 / 封面量产
统一风格的视频片头 / 片尾
音乐或图像的工作流固化
本地私有资产处理

如果你的目标是“生产级可重复工作流”，优先考虑 ComfyUI，而不是继续在旧 Skill 名称上做兼容。

14.6 四类值得直接照搬的创意工作流

工作流 1：教程配图流水线

infer web fetch 抓资料
主模型整理要点
infer image generate 生成白板图
保存到素材目录

工作流 2：短视频脚本 + 旁白草稿

主模型出脚本
infer tts convert 生成试音
video_generate 出镜头草案
人工二次剪辑

工作流 3：品牌一致的封面批量生成

统一 prompt 模板
统一图片尺寸和构图要求
指定 imageGenerationModel
批量脚本调用 infer image generate

工作流 4：音乐 / 视频异步生产

用 agent 发起 music_generate / video_generate
用 tasks list 看进度
完成后自动回传渠道

14.7 本章最容易踩的坑

坑 1：继续把历史第三方 Skill 当默认主线

现在不建议把这些当教程默认入口：

历史图像 Skill 名称
旧视频脚本命令
旧 TTS 子命令路径
零散中转站配置

坑 2：没区分“同步”和“异步”媒体任务

图片、TTS：更接近同步
视频、音乐：更接近异步后台任务

坑 3：没给媒体模型单独设默认值

主模型能聊天，不代表它就是最适合图片 / 视频 / 音乐的模型。请把这些能力拆开配置。

坑 4：直接把创意产物交付，不留人工审核

当前最稳的方式仍然是：

OpenClaw 负责起草、批处理、编排
你负责最终审美、品牌和法务风险判断

14.8 官方参考

GitHub Releases：https://github.com/openclaw/openclaw/releases
Media Overview：https://docs.openclaw.ai/tools/media-overview
Inference CLI：https://docs.openclaw.ai/cli/infer
Video Generation：https://docs.openclaw.ai/tools/video-generation
Music Generation：https://docs.openclaw.ai/tools/music-generation

04 Practical Cases 15 Solo Entrepreneur Cases (`docs/04-practical-cases/15-solo-entrepreneur-cases.md`)

📖 纸质书《OpenClaw超级个体实操手册》已上市！ 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 京东专属购买链接（¥42，原价¥59.8）

第15章节一人公司实战（选题、交付、分发、复盘）

本章目标：把“一个人做品牌、做产品、做分发”的工作流，改写成符合 OpenClaw 当前官方能力的版本：用 standing orders、cron、Task Flow、媒体能力和 Memory Wiki 形成闭环。

版本基线

当前稳定版：v2026.9.3（2026-09-08 发布）
本章一律按 v2026.9.3 稳定版主线展开，避免把历史 beta / 已移除插件写成默认商业流程

先给小白的阅读说明

这章不是“全自动赚钱教程”

这一章更准确的定位是：教你怎么把一个人的日常商业工作拆成可复用流程。它不会让你完全不审稿、不确认、不复核就自动对外发布。

谁适合先读这一章

你已经把第 13 章自动化和第 14 章媒体能力跑通过
你自己一个人做内容、产品、咨询、课程或服务交付
你想把“研究、起草、产出、分发、复盘”做成半自动流水线

小白怎么读最省力

只想做内容系统：先看 15.1
只想做线索跟进：先看 15.2
想理解一人公司的整体操作系统：再看 15.3 以后

最重要的原则

外部发布、对外报价、法律风险、品牌风险，默认都要保留人工审批。OpenClaw 擅长的是帮你提速，不是替你承担责任。

15.1 案例一：个人品牌内容流水线

15.1.1 目标

一个人完成下面这条链路：

每天自动发现值得写的题目
快速做素材研究
产出文章 / 推文 / 视频脚本草稿
自动生成配图、试音或短视频素材
人工审核后再分发

15.1.2 先写 Standing Orders，而不是先堆工具

把 agent 的长期职责写进 AGENTS.md：

## Program: Daily Content Desk

**Authority:** Research AI/productivity topics, draft content, prepare assets
**Trigger:** Daily 09:00 via cron, plus manual on-demand requests
**Approval gate:** External publishing always requires human approval
**Escalation:** If sources conflict, legal risk appears, or confidence is low

### Execution Steps

1. Search for the last 24h worth of relevant updates
2. Rank 3 content angles
3. Draft one article outline and one short-form script
4. Prepare image/video/audio asset suggestions
5. Save everything to the workspace and wait for approval

### What NOT to Do

- Do not auto-publish to external platforms
- Do not fabricate facts or quotes
- Do not reuse old claims when sources conflict

15.1.3 定时触发

这个例子最适合先跑，因为它能让你每天固定收到一批候选选题，你很容易判断系统有没有真正帮你省时间。

bash

openclaw cron add   --name "Daily content desk"   --cron "0 9 * * *"   --tz "Asia/Shanghai"   --session isolated   --message "Research AI/productivity topics from the last 24 hours, rank 3 angles, draft one article outline and one short-form script, then summarize what needs approval."   --announce

15.1.4 素材生成

研究阶段优先走官方搜索与抓取：

bash

openclaw infer web search --query "OpenClaw release notes April 2026" --json
openclaw infer web fetch --url https://github.com/openclaw/openclaw/releases --json

素材阶段优先走官方媒体能力：

bash

openclaw infer image generate --prompt "一张白板风格配图：AI 内容生产流水线" --json
openclaw infer tts convert --text "今天的选题已经准备完成" --output ./topic-brief.mp3 --json

如果是短视频素材，则让 agent 调用 video_generate，并在 tasks list 里看进度。

看到什么算这条内容流水线已经有价值

你每天都能稳定拿到候选题目和草稿
你不需要手动开十几个网页再拼素材
你保留最终审核权，而不是让系统自动外发

15.1.5 为什么这一套比旧教程稳

旧版一人公司案例里最大的问题，是默认把一大堆平台化发布工具、历史 Skill 名称和经验流写死在正文里。现在更稳的做法是：

OpenClaw 负责研究、起草、素材准备、状态追踪
外部分发放在人工审批后进行
如果确实要自动分发，走 hooks / webhooks plugin 或自家中间层，不把它写死成某个旧平台依赖

15.2 案例二：线索收集与跟进自动化

15.2.1 场景

你有：

官网表单
邮件咨询
Telegram / Slack / 飞书私信
产品试用申请

你想做到：

新线索进来立刻被识别
自动补齐基础画像
按优先级分级
生成跟进建议
需要时升级为人工处理

15.2.2 推荐架构

text

表单 / 邮件 / IM 事件
  -> hooks 或 webhooks plugin
  -> create_flow
  -> run_task（资格判断 / 摘要 / 回复建议）
  -> 写入 Memory Wiki / CRM
  -> 人工审批是否发送正式回复

15.2.3 外部触发最小实现

轻量场景直接用 hooks/agent：

bash

curl -X POST http://127.0.0.1:18789/hooks/agent   -H 'Authorization: Bearer SECRET'   -H 'Content-Type: application/json'   -d '{"message":"Classify this inbound lead, summarize intent, infer urgency, and draft a reply outline.","name":"Lead intake","model":"openai/gpt-5.4-mini"}'

复杂场景则用 webhooks plugin 创建 Task Flow：

create_flow：建立该线索的流程对象
run_task：拆出资格判断、资料补齐、回复建议等子任务

15.2.4 为什么要把线索写进 Memory Wiki

因为一人公司最怕的不是“回复慢”，而是：

前后说法不一致
客户背景记不住
承诺过的事没人记得
线索状态散落在多个地方

如果你把关键信息沉淀到 wiki，你会得到：

谁是这个人 / 公司
TA 来自哪里
TA 关注什么
之前谈到哪一步
还有哪些未决问题

这对小团队极其关键。

15.3 一人公司的 4 层操作系统

我更推荐把 OpenClaw 在一人公司里的角色拆成 4 层：

第一层：日常执行层

负责：

搜索资料
总结信息
生成图片 / 试音 / 视频素材
处理日常消息和待办

核心能力：

infer
image_generate
video_generate
music_generate
tts

第二层：调度层

负责：

定时执行
记录任务状态
处理长任务
跟踪多步骤流程

核心能力：

cron
tasks
Task Flow

第三层：长期授权层

负责：

规定 agent 长期负责什么
规定哪些事必须审批
规定何时升级给你处理

核心载体：

AGENTS.md
standing orders

第四层：知识层

负责：

沉淀客户、项目、产品、内容资产
记录 claim / evidence / contradiction
把经验变成可检索知识

核心能力：

memory-core
active-memory
memory-wiki

15.4 一人公司应该怎么设审批边界

这是本章最重要的一节。

可以自动做：

研究与摘要
选题建议
资料抓取
素材初稿生成
线索分级建议
周报和日报草稿

必须人工确认：

对外正式发布
对客户作出承诺
发价格、合同、结算信息
处理敏感舆情和公关风险
修改生产数据或关键配置

OpenClaw 很适合做“前 80% 的准备工作”，但最后那一跳商业责任，必须保留给人。

15.5 最小可落地栈（推荐）

如果你就是一个人，不要一开始就搞“全家桶”。下面这套最实用：

必备

openclaw onboard
主模型 + 回退链
一个 cron 日报 / 周报任务
一个 AGENTS.md standing order
一个 hooks 或 webhooks 接口

第二阶段再加

Active Memory
Memory Wiki
图片 / 视频 / 音乐默认模型
Task Flow

暂时别急着加

一堆历史 Skill 生态兼容层
平台强耦合脚本
没有审批边界的自动外发
没有任务观测能力的多 agent 编排

15.6 每周复盘清单

建议每周固定看一次：

bash

openclaw status
openclaw cron list
openclaw tasks audit
openclaw tasks flow list
openclaw memory status --deep
openclaw wiki status
openclaw wiki lint

重点看：

任务有没有堆积
哪些流程总是失败
哪些承诺没有进入知识层
哪些 standing orders 该收缩或扩权
哪些自动化还没有审批边界

15.7 本章结论

一人公司不是“让 AI 代替你”，而是：

让 OpenClaw 接管研究、整理、调度、素材准备和状态追踪
让你只把精力放在判断、选择、品牌、产品和最终责任上

换句话说：

把重复劳动交给系统，把最终判断留给你自己。

15.8 官方参考

GitHub Releases：https://github.com/openclaw/openclaw/releases
Automation Overview：https://docs.openclaw.ai/automation/cron-vs-heartbeat
Scheduled Tasks：https://docs.openclaw.ai/automation/cron-jobs
Task Flow：https://docs.openclaw.ai/automation/taskflow
Standing Orders：https://docs.openclaw.ai/automation/standing-orders
Webhooks Plugin：https://docs.openclaw.ai/plugins/webhooks
Memory Wiki：https://docs.openclaw.ai/plugins/memory-wiki
Inference CLI：https://docs.openclaw.ai/cli/infer

Images Upload Log.Json (`docs/images/upload-log.json`)

{
"upload_time": "2026-02-14T16:08:28Z",
"images": [
{
"filename": "installation-interface.png",
"url": "https://upload.maynor1024.live/file/1771085321300_installation-interface.png"
},
{
"filename": "service-disaster-recovery.png",
"url": "https://upload.maynor1024.live/file/1771085328347_service-disaster-recovery.png"
}
]
}

03 Advanced Images Upload Log.Json (`docs/03-advanced/images/upload-log.json`)

--- METRICS ---

Files Extracted: 27
Estimated Token Budget: ~72558 tokens
Canonical Reference: https://codewiki.google/github.com/xianyu110/awesome-openclaw-tutorial

Docker & Self-Hosted Deployment Verified OCI

Technical Documentation: xianyu110/awesome-openclaw-tutorial

Overview (`README.md`) Copy Section

🦞 Awesome OpenClaw Tutorial

🦞 一本书玩转OpenClaw：超级个体实战指南

🔥 2026 年 10 月 · 作者正在更新的新项目 Copy Chapter

📌 本教程与 OpenClaw 最新版差异说明 Copy Chapter

🚀 30秒快速选择：哪种部署方式适合你？ Copy Chapter

📊 教程导航（按学习路径） Copy Chapter

🎯 零基础入门（必读） Copy Section

🔥 核心功能（实战） Copy Section

💎 进阶技能（提升） Copy Section

🎯 实战案例（直接套用） Copy Section

📚 附录工具（速查） Copy Section

🆘 遇到问题？快速解决 Copy Chapter

安装配置问题 Copy Section

使用问题 Copy Section

成本优化 Copy Section

🚨 重要版本提示 Copy Chapter

⚠️ 2026.3.7版本：Gateway认证要求（Breaking Change） Copy Section

🔧 2026.3.2版本：AI变"哑巴"了？ Copy Section

🆕 v2026.3.12 重大更新（2026年3月） Copy Section

🆕 v2026.3.13 更新（2026年3月中旬） Copy Section

🆕 v2026.9.3 稳定版更新（2026年9月8日） Copy Section

📎 历史基线：v2026.6.8（2026年6月16日） Copy Section

📖 纸质书：《OpenClaw超级个体实操手册》 Copy Chapter

📖 关于本教程 Copy Section

🎯 教程特色 Copy Section

📊 教程规模 Copy Section

🎯 适合人群 Copy Section

📚 完整教程目录 Copy Chapter

第一部分：零基础入门（3章节） Copy Section

第二部分：核心功能（4章节） Copy Section

第三部分：进阶技能（4章节） Copy Section

第四部分：实战案例（4章节） Copy Section

🔗 官方资源 Copy Chapter

💡 实战案例精选 Copy Chapter

📦 配置示例（开箱即用） Copy Section

🎬 实战场景 Copy Section

📊 成本对比 Copy Chapter

🤝 贡献指南 Copy Chapter

📮 联系方式 Copy Chapter

社交媒体 Copy Section

项目链接 Copy Section

📈 项目进度 Copy Chapter

📄 许可证 Copy Chapter

⚠️ 重要声明：禁止倒卖 Copy Section

Overview (`examples/README.md`) Copy Section

OpenClaw 示例文件

📁 目录结构 Copy Chapter

📋 配置文件说明 Copy Chapter

basic-config.json Copy Section

multi-model-config.json Copy Section

multi-agent-config.json Copy Section

feishu-config.json Copy Section

🤖 自动化脚本说明 Copy Chapter

daily-report.sh Copy Section

backup-config.sh Copy Section

batch-process-files.sh Copy Section

website-monitor.sh Copy Section

🔧 Skills开发说明 Copy Chapter

custom-skill-template.js Copy Section

weather-skill-example.js Copy Section

⚠️ 注意事项 Copy Chapter

📚 更多资源 Copy Chapter

💡 贡献 Copy Chapter

Overview (`scripts/README.md`) Copy Section

CSDN 自动发文工具

📋 功能特性 Copy Chapter

🔧 环境要求 Copy Chapter

📦 安装步骤 Copy Chapter

1. 安装 Python 依赖 Copy Section

2. 安装 ChromeDriver Copy Section

🚀 使用方法 Copy Chapter

方式 1: 单篇发布 Copy Section

方式 2: 批量发布（推荐） Copy Section

📝 使用流程 Copy Chapter

1. 启动脚本 Copy Section

2. 扫码登录 Copy Section

3. 自动填写文章 Copy Section

Overview (`README.md`)

🔥 2026 年 10 月 · 作者正在更新的新项目

📌 本教程与 OpenClaw 最新版差异说明

🚀 30秒快速选择：哪种部署方式适合你？

📊 教程导航（按学习路径）

🎯 零基础入门（必读）

🔥 核心功能（实战）

💎 进阶技能（提升）

🎯 实战案例（直接套用）

📚 附录工具（速查）

🆘 遇到问题？快速解决

安装配置问题

使用问题

成本优化

🚨 重要版本提示

⚠️ 2026.3.7版本：Gateway认证要求（Breaking Change）

🔧 2026.3.2版本：AI变"哑巴"了？

🆕 v2026.3.12 重大更新（2026年3月）

🆕 v2026.3.13 更新（2026年3月中旬）

🆕 v2026.9.3 稳定版更新（2026年9月8日）

📎 历史基线：v2026.6.8（2026年6月16日）

📖 纸质书：《OpenClaw超级个体实操手册》

📖 关于本教程

🎯 教程特色

📊 教程规模

🎯 适合人群

📚 完整教程目录

第一部分：零基础入门（3章节）

第二部分：核心功能（4章节）

第三部分：进阶技能（4章节）

第四部分：实战案例（4章节）

🔗 官方资源

💡 实战案例精选

📦 配置示例（开箱即用）

🎬 实战场景

📊 成本对比

🤝 贡献指南

📮 联系方式

社交媒体

项目链接

📈 项目进度

📄 许可证

⚠️ 重要声明：禁止倒卖

Overview (`examples/README.md`)

📁 目录结构

📋 配置文件说明

basic-config.json

multi-model-config.json

multi-agent-config.json

feishu-config.json

🤖 自动化脚本说明

daily-report.sh

backup-config.sh

batch-process-files.sh

website-monitor.sh

🔧 Skills开发说明

custom-skill-template.js

weather-skill-example.js

⚠️ 注意事项

📚 更多资源

💡 贡献

Overview (`scripts/README.md`)

📋 功能特性

🔧 环境要求

📦 安装步骤

1. 安装 Python 依赖

2. 安装 ChromeDriver

🚀 使用方法

方式 1: 单篇发布

方式 2: 批量发布（推荐）

📝 使用流程

1. 启动脚本

2. 扫码登录

3. 自动填写文章

4. 人工确认发布

⚙️ 配置选项

修改分类和标签

无头模式（后台运行）

📂 文章列表

❓ 常见问题