🦞

OpenClaw 从零入门指南

搭建技能型AI助手的完整手册

创建人：XSkill.dev

一、从零安装与环境准备

OpenClaw 是一个开源的 AI 智能体框架，允许您通过即时通讯工具与部署在本地电脑上的 AI 助手交互，并执行文件操作、代码编写等复杂任务。要开始使用，首先需要确保您的系统环境满足要求，并完成核心软件的安装与配置。

1. 环境要求与前置检查

在安装 OpenClaw 之前，您的系统必须满足以下硬性条件：

  • 操作系统：支持 macOS、Linux 或 Windows。对于 Windows 用户，强烈建议使用 WSL2（Windows Subsystem for Linux 2），OpenClaw 不支持原生 Windows 环境。
  • Node.js：必须安装 Node.js 22 或更高版本。这是 OpenClaw 的核心运行时依赖，版本过低将导致安装失败。您可以在终端中运行以下命令来检查当前版本： 
    node --version

2. 获取官方资源与文档

在安装过程中，以下官方资源将为您提供重要参考和后续支持：

资源类型 地址 主要用途
GitHub 仓库 https://github.com/openclaw/openclaw 获取最新源代码、参与开发。该仓库是项目的核心。
官方主站 https://openclaw.ai/ 提供版本下载、架构概览和多语言支持。
官方文档中心 https://docs.openclaw.ai/ 最权威的指南，涵盖从安装、配置到开发的完整教程。支持中文访问。
技能市场 (ClawHub) https://clawhub.com/ 浏览和安装由社区开发的各类实用技能模块。
Discord 社区 https://discord.com/invite/clawd 拥有超过8900名成员，是获取实时技术支持的主要社区。

注意：OpenClaw 是 Clawdbot 和 Moltbot 的最终品牌名称。原官网现已自动跳转至最新页面。

3. 安装步骤详解（二选一）

官方推荐两种安装方式，您可以根据操作系统任选其一。

方案A：使用官方一键安装脚本（强烈推荐）

此脚本会自动检测并处理 Node.js 等依赖，是最简单快捷的方式。

  • macOS / Linux / WSL2 用户： 
    curl -fsSL https://openclaw.ai/install.sh | bash
  • Windows (PowerShell) 用户： 
    iwr -useb https://openclaw.ai/install.ps1 | iex

    如果遇到执行策略报错，可以先执行 Set-ExecutionPolicy RemoteSigned，再重新运行安装命令。

方案B：通过 npm 全局安装

如果您已熟练管理 Node.js 环境，可以使用此方法。

npm install -g openclaw@latest

在某些极端情况下，如果因为系统已安装 libvips 导致 sharp 库构建失败，可以尝试使用以下命令强制使用预编译的二进制文件：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

安装验证：安装完成后，在终端中运行以下命令，如果成功显示版本号，则表明安装成功。

openclaw --version

4. 初始配置向导：完成核心设置

首次安装后，必须运行配置向导来完成基础设置。建议使用以下命令启动向导，它会引导您完成关键配置并安装后台服务（守护进程），以便 OpenClaw 能开机自启、持续运行。

openclaw onboard --install-daemon

向导会引导您完成以下关键步骤：

  1. 同意用户协议。
  2. 选择安装模式：推荐选择 QuickStart（快速开始）模式。
  3. 配置AI模型：您可以选择接入阿里云百炼（Dashscope/通义千问）、OpenAI、Claude 等云端 API，或稍后配置。国内用户常推荐选择 Dashscope，速度快且成本较低。
  4. 输入API Key：根据上一步选择的模型提供商，输入对应的 API Key。
  5. 选择消息渠道：可以连接 WhatsApp、Telegram、飞书等聊天工具。新手建议先选择 Skip for now 跳过，后续再配置。
  6. 安装守护进程：建议选择 Yes，让 OpenClaw 在后台自动运行。

5. 验证安装与快速体验

配置完成后，您可以通过以下方式验证安装并立即开始体验：

  1. 检查网关状态：守护进程安装后，网关通常会自动启动。您可以通过以下命令检查其运行状态： 
    openclaw gateway status
  2. 打开 Web 控制台（最快体验方式）：运行以下命令，浏览器会自动打开本地 Web 控制台（默认地址为 http://127.0.0.1:18789）。您可以直接在网页上与 AI 助手对话，无需配置任何外部聊天软件。 
    openclaw dashboard
  3. 通过命令行对话：在终端中运行以下命令即可开始与 AI 交互： 
    openclaw agent --message "你好"
  4. 后续配置消息渠道：当您准备好连接微信、Telegram 等平台时，可以使用 openclaw channels add 或 openclaw channels login 命令按指引进行配置。

6. 常见问题与故障排查

  • 命令未找到 (command not found: openclaw)：这可能是因为安装不成功，或 Node.js 的全局 bin 目录未加入系统 PATH。请检查安装，并确保 $(npm prefix -g)/bin 路径已在您的 PATH 环境变量中。此外，在项目更名过渡期，也可以尝试使用旧命令 moltbot 或 clawdbot 替代。
  • 网关未运行：如果未安装守护进程，可以执行 openclaw gateway 在前台临时启动，或重新运行 openclaw onboard --install-daemon 来安装服务。
  • 对于更详细的模型配置、技能开发或 Docker 部署指南，您可以随时访问 OpenClaw 官方文档中心 获取完整信息。

完成以上步骤，您的 OpenClaw 环境就已经准备就绪。接下来，您可以通过 Web 控制台或命令行开始探索 AI 助手的基础功能。

二、快速入门指南：5分钟上手你的第一个AI任务

在完成基础安装后，本节将带领你在 5 分钟内完成从启动到实际执行任务的完整流程。通过三个渐进式练习，你将快速掌握 OpenClaw 的核心交互模式。

1. 启动与连接验证

在正式开始之前，请确保以下服务正常运行：

步骤 1：检查网关状态

openclaw gateway status

预期输出应显示 running 或 active 状态。如果未运行，请执行：

openclaw gateway

步骤 2：验证模型连接

openclaw agent --message "你好，请确认连接正常"

如果收到 AI 助手的回复，说明模型配置正确，可以开始任务。

💡 提示：首次连接可能需要 3-5 秒初始化时间，请耐心等待。

2. 练习一：文件系统操作（难度 ⭐）

任务目标：让 AI 助手帮你查看当前目录结构。

执行命令：

openclaw agent --message "请列出当前目录下的所有文件和文件夹，并说明每个项目的用途"

预期结果：

  • AI 助手会调用文件系统技能
  • 返回格式化的目录列表
  • 尝试分析每个文件/文件夹的用途

学习要点：

  • 理解 Agent 如何调用 filesystem 技能
  • 观察自然语言指令如何转化为具体操作

3. 练习二：代码生成与保存（难度 ⭐⭐）

任务目标：生成一段代码并保存到本地文件。

执行命令：

openclaw agent --message "请编写一个 Python 函数，用于计算斐波那契数列的前 N 项，并将代码保存到 fibonacci.py 文件中"

验证结果：

cat fibonacci.py

学习要点：

  • 观察 Agent 如何分解任务（生成代码 + 文件操作）
  • 理解技能链式调用的概念
  • 体验 AI 助手作为"数字员工"的协作模式

4. 练习三：多轮对话任务（难度 ⭐⭐⭐）

任务目标：通过 Web 控制台完成一个需要上下文理解的任务。

操作步骤：

  1. 启动 Web 控制台： 
    openclaw dashboard
  2. 在浏览器对话框中输入： 
    我想学习 Python 数据分析，请为我制定一个 7 天学习计划
  3. 根据 AI 回复，继续追问： 
    第一天能否重点讲解 Pandas 的基础操作？
  4. 进一步细化： 
    请把第一天的学习内容保存到 learning_plan.md 文件中

学习要点：

  • 体验 Memory 系统如何保持对话上下文
  • 理解多轮交互中的意图继承
  • 掌握 Web 控制台的完整工作流

5. 快速上手检查清单

完成以上练习后，请确认你已掌握以下能力：

能力项 验证方式 状态
网关启动与检查 能独立执行 gateway status ⬜
CLI 基础对话 能通过命令行发送消息并接收回复 ⬜
文件操作技能 能成功创建、读取、列出文件 ⬜
Web 控制台使用 能启动 dashboard 并进行多轮对话 ⬜
任务分解理解 能理解复杂指令的自动分解过程 ⬜

6. 下一步学习路径

完成快速入门后，你可以根据兴趣选择以下方向深入：

方向 A：系统配置深化

  • 学习第五章「Web 控制台可视化操作全览」
  • 配置更多 AI 模型提供商
  • 设置消息渠道（Telegram、Discord、飞书）

方向 B：技能生态探索

  • 访问 ClawHub 浏览社区技能
  • 安装并使用 3-5 个实用技能
  • 理解技能的组合使用模式

方向 C：核心概念理解

  • 精读第四章「核心概念速通」
  • 理解 Gateway、Agent、Skill、Memory 的协作机制
  • 学习故障排查与性能优化

🎯 建议：新手推荐按 A → B → C 的顺序学习，循序渐进建立完整认知。

通过本节的三步练习，你已经从一个"旁观者"转变为 OpenClaw 的"实际使用者"。接下来，让我们深入探索更多高级功能与配置选项。

三、首次配置向导：CLI 与 Web 控制台

安装并完成首次 onboard 向导后，你的 OpenClaw AI 助手已经准备就绪。现在，你有两种立即开始交互的便捷入口，终端命令行 (CLI) 和可视化 Web 控制台。本节将引导你熟悉这两种方式，完成你的首次 AI 任务交互。

🖥️ 通过命令行 (CLI) 与 Agent 即时对话

这是最直接、快速的体验方式。你无需打开任何额外界面，在终端中输入指令即可与你的 AI 助手对话。

核心命令格式：

openclaw agent --message "你的问题或指令"

运行此命令后，OpenClaw 的 "大脑"（Agent）将调用你已配置的 AI 模型（如通义千问、GPT等），理解你的指令，并调用相关技能来执行任务，最后将结果返回至终端。

🌐 使用 Web 控制台进行可视化交互与管理

除了 CLI，OpenClaw 提供了一个功能更为丰富的本地 Web 控制台（Dashboard），用于对话、监控和配置。

在终端中执行以下命令：

openclaw dashboard

执行后，你的默认浏览器将自动打开并访问 http://127.0.0.1:18789。这就是你的 OpenClaw Web 控制台主页。

提示：如果浏览器没有自动打开，你可以手动在浏览器地址栏输入 http://127.0.0.1:18789 进行访问。

四、核心概念速通：Gateway·Agent·Skill·Memory

在成功安装并启动 OpenClaw 后，你或许会好奇：这个系统究竟是如何运作，将一句简单的指令变成实际执行的复杂任务？理解其核心架构，是高效使用和驾驭它的关键。

🌉 Gateway：系统的神经中枢与统一入口

Gateway（网关） 是整个系统的神经中枢和统一接入层。它的核心职责是"连接"与"转换"。

  • 职责：负责连接 Telegram、Discord、飞书等外部聊天平台，以及你正在使用的 CLI 和 Web 控制台。它将不同渠道格式各异的用户消息，统一转换为 OpenClaw 内部能理解的标准化格式。
  • 你的体验：无论你是在 Telegram 里发消息，还是在浏览器里打字，Gateway 确保了所有入口的指令都能被系统接收，所有回复都能准确返回。

🤖 Agent：驱动思考的"大脑"

Agent（智能体） 是系统的"大脑"，负责驱动所有的思考、理解和规划过程。

  • 职责：它接入你所配置的大语言模型（如通义千问、GPT-4），专门处理自然语言理解、上下文逻辑推理与任务规划。
  • 你的体验：你所感知到的 AI 的"智慧"——理解你的意图、进行多轮对话、记住之前聊过什么——主要来源于 Agent 的能力。

🛠️ Skill：赋予执行力的"双手"

Skill（技能） 是系统的"双手"，是一切实际执行能力的载体。如果 Agent 决定了"要做什么"，那么 Skill 就是具体"怎么做"的实现。

  • 职责：所有对本地文件、操作系统、网络浏览器或其他工具的操作，都封装在一个个独立的 Skill（技能插件） 中。
  • 核心创新：当面对一个没有现成技能的全新任务时，OpenClaw 的 Agent 能够自主尝试编写代码、调试执行，并将成功的解决方案自动封装成一个新的、可复用的标准化技能。

🗃️ Memory：持续成长的"档案柜"

Memory（记忆） 是系统的"档案柜"，采用短期上下文 + 长期持久化的双模架构，旨在实现"越用越聪明"的个性化服务。

  • 短期记忆：保留当前对话的上下文，确保 AI 能理解你上一句话的意思，实现连贯的多轮对话。
  • 长期记忆：将所有对话历史、你的个人偏好、任务执行记录等，以 Markdown 文件等形式持久化存储在本地电脑上。

总结来说，OpenClaw 通过 Gateway 统一接入，由 Agent 进行思考规划，调用具体的 Skill 去执行操作，并将整个过程与结果存入 Memory 以实现持续学习和个性化。

五、Web 控制台可视化操作全览

完成初次配置并启动你的AI助手后，你已通过 openclaw dashboard 命令访问了位于 http://127.0.0.1:18789 的Web控制台。现在，让我们深入探索这个控制面板，解锁其完整的可视化管理和控制能力。

🚪 安全的远程访问（适用于云服务器部署）

如果你的OpenClaw运行在阿里云、腾讯云等远程服务器上，直接暴露控制台端口存在安全风险。强烈建议通过SSH隧道进行安全访问。

  1. 在本地终端建立隧道： 
    ssh -N -L 18789:127.0.0.1:18789 root@你的服务器公网IP
  2. 在本地浏览器访问 http://localhost:18789
  3. 获取并输入网关令牌： 
    cat /root/.openclaw/openclaw.json | grep -A2 token

⚠️ 请注意：此令牌是最高权限密钥，请务必妥善保管，切勿泄露。

🧭 控制台核心功能区全解

登录控制台后，左侧导航栏是你管理AI助手的中枢。以下是功能模块概览：

功能模块 核心用途 关键操作示例
Channels（渠道集成） 管理外部通讯平台连接。 查看Telegram、WhatsApp、飞书等渠道的在线状态、机器人二维码登录、以及配置信息。
Instances（实例监控） 监控在线工作节点。 查看所有已连接的OpenClaw工作实例列表及其状态。
Cron Jobs（定时任务） 设置自动化调度任务。 添加、启用或禁用Cron定时任务，并查看历史执行记录。
Agents（智能体） 管理AI智能体的行为模式。 对会话进行更精细的配置，调整其思考模式与详细参数。
Skills（技能管理） 管理扩展AI能力的插件。 浏览、启用/禁用已安装技能，或从官方市场（ClawHub）安装新技能。
Config（配置编辑） 可视化修改所有配置。 通过表单视图或Raw（原始JSON）编辑器查看并修改配置文件。
Debug（调试与日志） 系统监控与问题排查。 查看系统健康状态、模型快照、事件日志，并支持实时日志流跟踪与导出。

十、常见问题排查与社区资源索引

作为一名"数字员工"，您的 OpenClaw 助手在为您高效工作的过程中，难免会遇到一些小问题或需要寻求社区的帮助。本章节将汇总最常见的故障场景及其解决方法，并提供完整的官方与社区资源导航。

🛠️ 常见问题排查指南

当遇到问题时，首先尝试运行全面的健康检查命令，它将自动诊断并尝试修复多数常见问题：

openclaw doctor

1. 「安装失败」或「命令未找到」

  • 检查 Node.js 版本：OpenClaw 必须运行在 Node.js 22 或更高版本上。请在终端执行 node --version 确认。
  • 重新运行官方一键脚本（最推荐）： 
    curl -fsSL https://openclaw.ai/install.sh | bash
  • 排查 npm 安装路径：检查 Node.js 的全局 bin 目录是否已加入系统的 PATH 环境变量。
  • 尝试旧命令（过渡期）：由于项目曾更名，在个别环境下可以尝试使用其前身命令 moltbot 或 clawdbot。

2. 「OpenClaw 网关未运行」

  • 检查状态：openclaw gateway status
  • 启动网关：
    • 前台启动（关闭终端即停止）：openclaw gateway
    • 安装为守护进程（推荐）：openclaw onboard --install-daemon

3. 「无法访问 Web 控制台 (Dashboard)」

  • 确认网关运行：首先执行 openclaw gateway status
  • 手动打开：运行 openclaw dashboard，浏览器通常会自行打开。
  • 远程服务器访问：建立 SSH 隧道进行安全访问： 
    ssh -N -L 18789:127.0.0.1:18789 username@您的服务器公网IP

4. 「AI 模型无响应或接入错误」

  • 检查配置：模型接入信息存储在 ~/.openclaw/openclaw.json。可通过 Dashboard 的 Config > Authentication > Raw 页面进行可视化编辑。
  • 验证 API 密钥：确认您填入的 API Key 有效且有余额。
  • 特别注意阿里云百炼配置：
    • baseUrl、apiKey、model 三者必须对应同一服务区域（如北京或新加坡）。
    • 在模型配置中，必须将 "reasoning" 参数设置为 false，否则可能导致对话无响应。

📚 官方与社区资源索引

资源类型 地址与说明 主要用途
项目仓库 GitHub: https://github.com/openclaw/openclaw 获取最新源代码、提交 Issue、参与开发。
官方文档 文档中心: https://docs.openclaw.ai/ 最权威的安装、配置、开发、API 参考指南。
技能市场 ClawHub: https://clawhub.ai/ 浏览和获取社区验证的 100+ 个实用技能模块。
实时社区 Discord: https://discord.com/invite/clawd 获取实时技术帮助、参与功能讨论、分享案例。
官方网站 https://openclaw.ai/ 项目概览、版本发布、一键安装入口。

通过本章的排查方法与资源索引，您已经具备了独立解决大多数运行问题和自主探索进阶功能的能力。OpenClaw 的强大之处在于其活跃的社区和不断增长的技能生态，祝您在打造专属"数字员工"的道路上探索愉快！