← Back to Blog
EN中文

OpenClaw 全方位指南：从入门到精通

OpenClaw 不仅仅是一个命令行工具，它是一个驻留在你系统中的智能实体。它有记忆、能思考、会使用工具，甚至可以帮你自动执行复杂的任务流水线。它基于 Node.js 构建，作为本地消息路由器和 Agent 运行时，将主流 AI 模型（尤其是 Anthropic Claude 系列）与系统工具及 50+ 集成连接起来，在不将敏感数据发送到云端的前提下实现自主任务执行。

但这并不意味着它很难上手。事实上，OpenClaw 的设计理念是渐进式增强。你可以把它当作一个更聪明的 CLI，也可以把它配置成自动化运维的超级管家。

本文将带你从安装配置开始，逐步掌握工作区定制、多渠道集成、Cron 自动化、Skill 扩展，最终深入到自定义 Skill 开发与多 Agent 架构设计。

第一阶段：安装与配置

1. 环境要求

  • Node.js >= 22（推荐使用 nvm 管理版本）
  • 操作系统：macOS、Linux、Windows（WSL）均可
  • 一个 AI 模型的 API Key（Anthropic、OpenAI 或 Google）

2. 安装 Gateway

npm install -g openclaw
openclaw onboard --install-daemon

onboard 向导会引导你完成初始配置，包括安装 Gateway 守护进程（macOS 上是 launchd，Linux 上是 systemd user service），确保它在后台持续运行。

3. 配置 AI 模型

openclaw models auth setup-token   # 配置 Anthropic API Key（推荐）
openclaw models set <model>        # 设置主模型
openclaw models aliases add <alias> <model>  # 创建模型别名

OpenClaw 内置了自动故障转移机制：当主模型不可用时，会自动切换到备用模型，冷却时间从 1 分钟逐步递增到 5 分钟再到 1 小时。

第二阶段：建立连接（低阶篇）

刚接触 OpenClaw 时，最重要的是习惯与它"对话"，而不是"输入命令"。

1. 自然语言交互

忘掉复杂的参数。直接告诉它你想做什么：

"把这个文件夹里的 PNG 图片都压缩一下。" "去查一下最新的 Node.js LTS 版本是多少。"

2. 上下文感知

OpenClaw 记性很好。你不需要重复每一句话的主语：

User: "读取一下 README.md。" Agent: (读取文件...) User: "把第 5 行的拼写错误改一下。"（它知道你在说哪个文件）

3. 工作区文件全览

OpenClaw 的核心配置存放在工作区目录（~/.openclaw/workspace）中。以下是完整的文件清单：

文件 用途
AGENTS.md Agent 的操作指令，定义行为规则
SOUL.md 定义 Agent 的人格、语气和行为边界
USER.md 存储你的个人信息和偏好
IDENTITY.md Agent 的名字、Emoji 和主题设置
MEMORY.md 精选的长期记忆（仅在 DM 会话中加载）
memory/YYYY-MM-DD.md 每日追加日志；系统启动时读取当天和前一天的内容
TOOLS.md 本地工具文档
HEARTBEAT.md 自动心跳检查的任务清单
BOOT.md 启动初始化检查清单

其中，SOUL.md 是最有趣的——你想让你的 Agent 严肃、活泼，还是像个海盗？都可以。

4. 内置工具一览

OpenClaw 提供了一套丰富的内置工具，Agent 可以随时调用：

工具 功能
exec 在工作区中执行 shell 命令，支持超时和自动后台化
read / write / edit 文件系统操作
browser 控制专属浏览器实例，支持快照、截图、UI 交互
web_search 联网搜索（基于 Brave Search API）
web_fetch 抓取网页内容并转换为 Markdown
image 图像分析（需配置 imageModel）
pdf PDF 文档分析，支持页面范围和多文档
message 跨平台消息发送（Discord、Slack、Telegram、WhatsApp 等）
nodes 发现和操控配对设备
sessions_spawn 生成子 Agent 处理后台任务
cron 管理定时任务
canvas 驱动 Canvas 进行演示和 A2UI 交互

第三阶段：多渠道集成

OpenClaw 的一大亮点是它的多渠道收件箱——几乎你能想到的即时通讯平台它都支持：

支持的渠道： WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、BlueBubbles（iMessage）、IRC、Microsoft Teams、Matrix、飞书、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Twitch、WebChat 等。

连接渠道

openclaw channels login              # WhatsApp QR 码配对
openclaw channels add --token <TOKEN> # Telegram / Discord / Slack

会话作用域

对于多用户场景，建议配置 session.dmScope 防止上下文泄露：

模式 说明
main 默认，所有消息共享一个会话
per-peer 每个联系人独立会话
per-channel-peer 每个频道+联系人独立会话（推荐）
per-account-channel-peer 最细粒度隔离

会话重置模式支持 daily（每天凌晨 4 点）或 idle（空闲一定分钟后）。

第四阶段：自动化与分工（中阶篇）

当你熟悉了基本操作，就会发现：如果不让它主动干活，就太浪费了。

1. Cron 定时任务

让 Agent 变成你的 24 小时管家。

openclaw cron add     # 添加定时任务
openclaw cron list    # 查看所有任务
openclaw cron run <id>  # 手动触发

场景示例：每天早上 9 点检查 GitHub Trending，汇总发送到 Slack 频道。

2. Skill 系统

Skill 是 OpenClaw 的"技能包"——Skill 是教科书，Tool 是基本能力。Tool 赋予 Agent 读文件、执行命令、浏览网页的能力；Skill 则教它如何有纪律地组合这些能力来完成特定任务。

常用内置 Skill：

  • coding-agent：专门写代码，逻辑更严密
  • web_search：联网搜索，不再瞎编乱造
  • healthcheck：检查系统安全
  • gog：Google Workspace 集成（邮件、日历）
  • obsidian：笔记管理
  • github：仓库管理与 PR 操作

通过 ClawHub 可以获取社区贡献的 5400+ 个 Skill：

clawhub install <skill-slug>   # 安装社区 Skill
clawhub update --all           # 更新所有已安装 Skill

3. Sub-Agent（子 Agent）

当任务太复杂（比如"研究 10 个竞品并写报告"），主会话会被阻塞。

# 在对话中使用
sessions_spawn(task="研究 React vs Vue vs Svelte 的性能对比，写一份报告")

它会在后台静默工作，完成后再向你汇报，不占用你的主窗口。相关管理工具：

  • sessions_list — 查看所有会话
  • sessions_history — 查看会话历史
  • sessions_send — 向其他会话发消息
  • agents_list — 列出可用 Agent ID

4. Hooks（事件钩子）

Hooks 让你在特定事件发生时自动触发操作：

事件 说明
command:new 新会话开始
command:reset 会话重置
command:stop 会话停止
gateway:startup Gateway 启动
agent:bootstrap Agent 初始化 
openclaw hooks enable <name>   # 启用 Hook

内置的 session-memory Hook 会在每次 /new 时自动保存会话上下文。

第五阶段：自定义 Skill 开发（高阶篇）

当你开始编写自己的 Skill 时，你就进入了高阶领域。

1. 为什么需要自定义 Skill？

当你发现自己反复在做同一件事——按特定格式写博客、自动化部署、调用特定 API——就是时候把它封装成 Skill 了。

Skill 的好处：

  • 标准化：避免手动操作的疏漏
  • 可复用：Agent 可以随时调用
  • 上下文清晰：Skill 的 Description 和 Prompt 能引导 Agent 正确使用它

2. Skill 加载优先级

Skill 从三个位置加载，优先级从高到低：

  1. 工作区 Skill（<workspace>/skills/）— 最高优先级
  2. 托管 Skill（~/.openclaw/skills/）— 所有 Agent 共享
  3. 内置 Skill — 随安装附带
  4. 额外目录（通过 skills.load.extraDirs 配置）— 最低优先级

名称冲突时，高优先级覆盖低优先级。

3. SKILL.md 详解

一个 Skill 的核心就是 SKILL.md 文件。OpenClaw 只认 YAML Frontmatter。

最小结构：

---
name: my-awesome-skill
description: This skill does awesome things.
---

# My Awesome Skill

详细的使用说明和 Prompt...

完整的 Frontmatter 字段：

字段 说明
name Skill 标识符
description 人类可读的描述
homepage 可选的网站 URL
user-invocable 布尔值；是否暴露为斜杠命令（默认 true）
disable-model-invocation 布尔值；从模型提示中排除（默认 false）
command-dispatch 设为 tool 可绕过模型路由
command-tool 直接分发的工具名
metadata 单行 JSON，用于环境门控和配置

4. Metadata 门控

通过 metadata 字段控制 Skill 的加载条件：

metadata: {"openclaw":{"emoji":"📊","requires":{"bins":["bash","date"],"env":["MY_API_KEY"],"os":["linux","darwin"]}}}

门控选项：

  • always: true — 无条件加载
  • os — 限制操作系统（darwin、linux、win32）
  • requires.bins — 必须存在的命令行工具
  • requires.env — 必须存在的环境变量
  • requires.config — 必须为真的 openclaw.json 配置路径
  • primaryEnv — 关联到 skills.entries.<name>.apiKey 的环境变量

5. 编写高质量 Skill 的要素

一个合格的 Skill 应该像"凌晨 3 点交给值班工程师的操作手册"——精确、防御性强、可执行。它应当包含：

  • 适用场景：什么时候使用这个 Skill
  • 输入要求：需要的路径、URL、凭证
  • 工作流程：带有确切命令的编号步骤
  • 输出格式：一致的结果结构
  • 防护栏：安全约束和防幻觉措施
  • 失败处理：错误恢复步骤
  • 示例：典型查询和预期输出

6. 开发流程

三种创建方式：

  1. 对话式起草：描述你的自动化需求，让 Agent 生成 SKILL.md 框架，然后打磨成正式版本
  2. 手动创建：创建文件夹，直接编写 SKILL.md，用 openclaw skills list 验证
  3. Fork + 收窄：复制社区已有的 Skill，添加自己的防护栏（通常是最快的方式）
# 验证 Skill 是否被正确加载
openclaw skills list --verbose
openclaw skills info my-skill

7. 在 openclaw.json 中配置 Skill

{
  skills: {
    entries: {
      "my-skill": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "MY_API_KEY" },
        env: { MY_API_KEY: "your-key-here" }
      }
    },
    load: {
      watch: true,          // 监听 SKILL.md 变更，自动刷新
      watchDebounceMs: 250
    }
  }
}

8. Token 开销

每个激活的 Skill 都会注入到系统提示中。开销估算：

  • 基础开销（至少有 1 个 Skill 时）：约 195 字符
  • 每个 Skill：约 97 字符 + name/description 长度
  • 粗略估计：每个 Skill 约 24 tokens

建议：保持 description 精练，禁用不用的 Skill，用 disable-model-invocation 标记仅手动触发的 Skill。

第六阶段：多 Agent 与安全

1. 多 Agent 架构

每个 Agent 拥有独立的状态空间，存放在 ~/.openclaw/agents/<id>/ 下。

openclaw agents list           # 列出所有 Agent
openclaw agents add            # 添加新 Agent
openclaw agents list --bindings  # 查看路由绑定

消息路由可基于 peer、guildId（Discord）、teamId（Slack）、accountId 或 channel 进行分配。

2. 沙箱模式

OpenClaw 使用 Docker 容器提供执行隔离：

模式 说明
off 直接在宿主机执行
non-main 非主会话使用沙箱（默认）
all 所有会话都在沙箱中运行

作用域选项：session（每会话隔离）、agent（每 Agent 隔离）、shared（共享容器）。

3. 心跳系统

配置 heartbeat.every（默认 30 分钟），Agent 会定期执行 HEARTBEAT.md 中定义的检查清单并报告状态。

4. 复杂流水线（Pipeline）

利用 Cron 的 payload 参数，你可以设计出一套自动化流：

  1. Trigger：Cron 定时触发
  2. Action：唤醒一个专门的 Writer Agent
  3. Delivery：写完文章后，自动推送到 Git 仓库，并触发构建脚本

5. 安全最佳实践

  • 审查第三方 Skill：像 Code Review 一样对待每个 SKILL.md
  • 不要信任混淆的 shell 命令：社区中已出现过伪装成 Skill 的恶意软件
  • 使用环境变量门控：不要在对话中粘贴密钥
  • 限制权限范围：只声明必要的工具和网络调用

6. 诊断命令

遇到问题时，这几个命令是你的救星：

openclaw doctor --deep --yes    # 全面诊断
openclaw status --all --deep    # 系统状态
openclaw security audit --fix   # 安全审计并自动修复
openclaw logs --follow          # 实时日志

总结

OpenClaw 的强大之处在于它的可塑性。

  • 新手用它做加强版 CLI
  • 中级用户用它连接多渠道、跑定时任务
  • 老手用它做自动化运维、开发自定义 Skill
  • 极客用它构建多 Agent 协作的 JARVIS

无论你处于哪个阶段，记得多看文档（openclaw help）、多逛 ClawHub 发现新 Skill，多尝试自己动手写。

Happy Hacking with OpenClaw!

参考资料：

官方资源：

中文社区与教程：