跳到主要内容

从零到一：完整学习路径

本指南提供一条从零开始掌握 OpenClaw 的学习路径，帮助你完成从安装到多通道、多 Agent 使用的全过程。每个阶段都包含目标、学习内容、实践任务与常见注意点，便于按步骤推进并查漏补缺。

学习路径概览​

建议总时长约 4–6 小时（含首次通道对接与多 Agent 配置）；若仅完成到阶段 4 的首次对话，约 2–3 小时。

阶段 1：了解 OpenClaw（约 30 分钟）​

目标​

理解 OpenClaw 的定位、架构与适用场景，建立整体认知。

学习内容​

  1. 阅读入门文档
    • 入门介绍：什么是 OpenClaw、系统架构概览、核心理念、关键特性（网关、多通道、多模型、多 Agent、记忆、安全）、适用场景、与其他技术关系。
  2. 理解核心概念
    • 网关：统一接收与分发各通道消息，管理连接与路由。
    • 通道：对接各消息平台（Telegram、微信、钉钉等），将平台协议归一化。
    • Agent：对话逻辑、调用大模型、使用工具与记忆；可配置多个并隔离。
    • 模型配置：多厂商、多模型切换与 API Key 管理。
    • 多 Agent 路由：按用户/群组/渠道将消息分发到不同 Agent。
    • 持久记忆与配对：上下文、长期记忆与私信安全控制。
  3. 明确使用场景
    • 个人多平台助手、团队/企业自建客服或内部助手、与 MCP/工作流等集成；结合自身目标选择后续实践重点。

实践任务​

  • 通读 入门介绍。
  • 弄清「网关 — 通道 — Agent — 模型」之间的关系，能用自己的话简述数据流。

常见注意点​

  • 若你已有 MCP/agent_skills 经验，可重点看「与其他技术的关系」，便于后续做集成规划。

阶段 2：环境与安装（约 20 分钟）​

目标​

准备好 Node.js 环境并成功安装 OpenClaw CLI，能执行基本命令。

学习内容​

  1. 安装 Node.js
    • 版本 >= 22，推荐 LTS（如 22.x）；使用 node -v 验证。
  2. 安装 openclaw-cn
    • 按 快速开始 使用 curl 或 npm install -g openclaw-cn；若命令找不到，将 npm global bin 加入 PATH 或使用 npx openclaw-cn。
  3. 验证安装
    • 执行 openclaw-cn --version 与 openclaw-cn --help 确认可用。

实践任务​

  • 安装并验证 CLI。
  • 可选：准备一个模型 API Key（如 OpenAI、MiniMax 等）和 Brave Search API Key（若需搜索能力），以及一个要接入的通道的 Bot/应用凭证（如 Telegram Bot Token）。

常见注意点​

  • 国内环境若安装慢，可配置 npm 镜像或代理；详见 常见问题。

阶段 3：入门向导与网关（约 30 分钟）​

目标​

跑通入门向导，启动网关并理解基本配置所在位置。

学习内容​

  1. 运行入门向导
    • 执行 openclaw-cn onboard --install-daemon，按提示配置模型与认证、网关端口、至少一个通道、以及（可选）守护进程。
  2. 启动网关
    • 执行 openclaw-cn gateway --port 18789（或你配置的端口），确认进程正常监听；若已安装守护进程，可用系统服务命令启动并设置开机自启。
  3. 理解配置
    • 知道配置文件或环境变量大致放在哪里，便于后续修改模型、通道或路由；敏感信息建议仅通过环境变量注入。

实践任务​

  • 完成向导并成功启动网关（前台或守护进程）。
  • 在日志中确认网关已就绪、无报错（通道尚未连通时可暂时忽略通道相关警告）。

常见注意点​

  • 若向导卡住，检查网络与权限；详见 常见问题 Q3。

阶段 4：第一个通道（约 1 小时）​

目标​

接入一个实际可用的消息通道（如 Telegram 或微信），并完成一次「用户发消息 → Agent 回复」的端到端验证。

学习内容​

  1. 选择通道
    • 选一个你熟悉的平台（如 Telegram Bot、微信测试号、钉钉/飞书应用等），并已在该平台创建 Bot 或应用、获取 Token 或凭证。
  2. 在 OpenClaw 中配置
    • 在向导或配置文件中填入该通道的 Token、Webhook URL（若需要）等；若通道要求公网回调，确保网关可通过 HTTPS 被访问（必要时使用内网穿透或反向代理）。
  3. 端到端验证
    • 在对应平台向你的 Bot 或应用发送一条消息，确认 OpenClaw 侧能收到并由 Agent 回复；若有问题，结合网关与通道日志排查连接、认证与路由。

实践任务​

  • 至少接入一个通道并完成一次完整对话。
  • 理解该通道的配置项与常见坑（如 Webhook 必须 HTTPS、Token 权限等）；可简单记录以便日后排查。

常见注意点​

  • 收不到消息时，优先检查：Token/凭证是否正确、Webhook/长连接是否可达、防火墙与安全组是否放行；详见 常见问题 Q5。

阶段 5：多 Agent 与路由（约 1 小时）​

目标​

配置多个 Agent，并将不同用户或群组路由到不同 Agent，验证路由符合预期。

学习内容​

  1. 阅读相关文档
  2. 配置多 Agent
    • 在配置中为每个 Agent 指定模型、系统提示词等，确保名称与路由规则中引用一致。
  3. 配置路由规则
    • 按用户 ID、群组 ID 或渠道类型将请求路由到对应 Agent；设置默认 Agent 以防未匹配到规则。
  4. 验证
    • 用不同账号或群组发消息，确认由预期 Agent 回复；若有误路由，检查规则顺序与匹配条件。

实践任务​

  • 配置 2 个及以上 Agent 并设置路由规则。
  • 通过实际消息验证路由符合预期，并能解释「某条消息为什么被分到某 Agent」。

常见注意点​

  • 路由规则通常按顺序匹配，先匹配到的先生效；避免规则重叠或遗漏，详见 最佳实践。

阶段 6：安全与运维（约 1 小时）​

目标​

掌握基本安全设置与长期运行方式，能备份配置并在异常时恢复或排错。

学习内容​

  1. 安全
    • 阅读 最佳实践 中「安全与隐私」「配置设计」：API Key 通过环境变量管理、私信开启配对审批、网关不直接暴露公网或做访问控制与 HTTPS。
  2. 运维
    • 使用守护进程或 systemd/supervisor 常驻运行网关；配置开机自启；了解日志位置与级别，便于排错；可选：健康检查与简单监控。
  3. 备份与升级
    • 定期备份配置文件与持久化数据；升级前阅读 Release Notes，在测试环境先验证再在生产执行；保留回滚方案。

实践任务​

  • 若使用私信，开启配对审批并验证通过/拒绝流程。
  • 以守护进程或服务方式部署网关，并确认重启后能自动拉起；可选：做一次配置备份与恢复演练。

常见注意点​

  • 生产环境务必分离敏感信息与配置、限制网关访问并定期轮换 Key；详见 最佳实践。

阶段 7：扩展与集成（持续）​

目标​

根据需求做二次开发或与现有系统集成，巩固并扩展 OpenClaw 能力。

学习内容​

  1. 扩展点
    • 开发指南 中「扩展开发方向」：新增通道适配器、自定义 Agent 逻辑或工具、与 MCP/agent_skills 等协议对接。
  2. 资源
  3. 问题排查
    • 常见问题 与官方文档、Issue；结合日志与配置做系统性排错。

实践任务​

  • 按需选做：接入一个新通道、更换/新增模型、或与 Dify/MCP 等做一次简单集成；可记录步骤与踩坑便于复用。

完成以上阶段后，你将能够独立安装、配置、运行 OpenClaw，并在此基础上进行多 Agent 配置与安全运维；后续可根据业务需要深入扩展与集成。若某阶段卡住，可优先查阅 常见问题 与对应文档的「常见注意点」。