如何安装与配置 OpenClaw？从零开始搭建专属 AI 智能体助手

一、OpenClaw 简介与核心架构解析

在人工智能技术飞速发展的今天，拥有一个能够自动处理邮件、操作浏览器、甚至与各类聊天软件无缝对接的 AI 助手，已经成为提升生产力的关键。OpenClaw 正是这样一个开源、可本地部署的 AI 智能体（Agent）框架。它通过自然语言指令自动执行复杂任务，是一款真正具备“行动力”的 AI 工具。

在开始安装之前，理解 OpenClaw 的核心架构有助于后续的配置与排错。根据 juejin.cn 的深入解析，OpenClaw 采用的是网关（Gateway）架构。这种架构主要包含以下几个核心组件：

• Gateway（网关）：整个系统的大脑中枢，负责管理会话上下文、调用 AI 模型生成回复，并接收来自不同聊天平台的消息。
• Channels（渠道）：消息的输入与输出通道，支持接入飞书、Telegram、Slack、Discord 等多种即时通讯工具。
• Agents（智能体）：负责执行具体的技能（Skills）和工具调用，处理对话记忆。
• Workspace（工作区）：本地数据存储中心，包含配置文件（openclaw.json）、记忆文件（MEMORY.md）以及日志。
• Skills（技能）：扩展模块，赋予 OpenClaw 联网搜索、控制智能家居、发布文章等具体能力。

这种设计不仅保证了数据的本地隐私安全，还提供了极强的可扩展性。

二、部署前置环境准备

OpenClaw 的运行需要特定的底层环境支持。如果环境不达标，后续安装过程中极易出现报错。请严格按照以下要求进行检查和准备。

1. 操作系统要求

OpenClaw 跨平台支持良好，但在不同系统上的最佳实践有所不同：

• Windows：强烈建议使用 WSL2（Windows Subsystem for Linux 2），并安装 Ubuntu 发行版。原生 Windows 环境（如 PowerShell）虽然可以通过特定脚本安装，但可能会遇到权限和路径兼容性问题。
• macOS：如果仅使用命令行和网关功能，安装 Node.js 即可。若需构建桌面应用，需额外安装 Xcode 或 Command Line Tools。
• Linux：原生支持极佳，适用于 Ubuntu、Debian、CentOS 等主流发行版。

2. Node.js 版本要求

这是最关键的一步。OpenClaw 强依赖于较新的 Node.js 环境。根据 xugj520.cn 的指南，Node.js 版本必须在 22 或以上。

打开终端或命令行，输入以下命令检查版本：

node -v

如果输出类似于 v22.x.x 的版本号，则说明环境合格。如果版本过低，请前往 Node.js 官方网站下载最新的 LTS 版本，或使用 nvm（Node Version Manager）进行版本升级与管理。

三、OpenClaw 安装指南

确认环境无误后，即可开始安装 OpenClaw。开发者提供了多种安装方式，以适应不同的使用习惯。

方法一：使用 NPM 全局安装（推荐）

这是最直接、最透明的安装方式。在终端中执行以下命令进行全局安装：

npm install -g openclaw@latest

安装完成后，可以通过以下命令验证是否安装成功：

openclaw --version

方法二：使用一键安装脚本

对于不熟悉 Node.js 环境配置的用户，官方提供了一键安装脚本，该脚本会自动处理依赖和环境问题。

Windows (PowerShell) 环境：

以管理员身份运行 PowerShell，输入以下指令：

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

macOS / Linux 环境：

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

提示：国内用户如果遇到网络超时问题，可以参考 juejin.cn 提供的中文社区版加速脚本：curl -fsSL https://clawd.org.cn/install.sh | bash，该版本已将依赖切换至国内镜像源。

四、快速启动与初始化向导 (Onboard)

安装完成后，需要通过交互式向导对 OpenClaw 进行初始配置。在终端中运行：

openclaw onboard

向导将引导完成以下核心配置：

1. 风险确认：系统会提示 I understand this is powerful and inherently risky. Continue?，输入 Yes 并回车。这是因为 AI 智能体拥有操作本地计算机的权限，需要用户明确授权。
2. 选择模式：建议新手选择 QuickStart，系统将自动应用最友好的默认设置。
3. 配置 AI 模型 (Model/auth provider)：选择希望使用的大语言模型（如 OpenAI、Anthropic、Moonshot、智谱 GLM 等）。如果暂时没有 API Key，可以选择 “Skip for now” 跳过，后续可以在配置文件中补充。
4. 配置通信渠道 (Channels)：选择期望接入的聊天软件（如飞书、Telegram）。初次安装建议先选择 “Skip for now”，优先保证本地网关运行正常。
5. 配置技能与钩子 (Skills & Hooks)：直接选择 “Skip for now” 即可。

五、本地网关 (Gateway) 配置与启动

网关是 OpenClaw 的核心服务，Web 控制台和第三方消息平台的通信都依赖于网关的正常运行。这一步是许多新手容易卡住的环节。

1. 设置网关模式

首先，必须明确告知系统网关的运行模式为本地模式：

openclaw config set gateway.mode local

2. 安装并启动网关服务

在 Windows 系统下，需要以管理员身份运行终端（如 PowerShell），执行以下命令安装网关服务：

openclaw gateway install

安装成功后，系统会提示 Installed Scheduled Task: OpenClaw Gateway。接着，手动触发网关启动：

schtasks /Run /TN "OpenClaw Gateway"

对于 macOS 和 Linux 用户，通常可以使用 openclaw gateway start 命令进行启动。

3. 验证网关状态与获取凭证

等待几秒钟后，检查网关是否可达：

openclaw gateway probe

如果输出 Reachable: yes，说明网关已成功运行。此时可以在浏览器中访问 http://127.0.0.1:18789/ 打开 Web 控制台。

首次访问 Web 控制台时，系统会要求输入 Token 验证身份（提示 unauthorized: gateway token missing）。在终端中运行以下命令获取 Token：

openclaw config get gateway.auth.token

将输出的字符串粘贴到浏览器的验证框中即可进入控制台。

六、进阶配置：接入自定义第三方大模型

虽然向导中可以配置主流模型，但许多开发者使用的是第三方中转 API 服务。这就需要手动修改 OpenClaw 的配置文件。

配置文件的默认路径位于本地用户目录下：

• Windows: C:\Users\用户名\.openclaw\openclaw.json
• macOS/Linux: ~/.openclaw/openclaw.json

使用文本编辑器打开该文件，找到 models 节点，按照以下模板添加自定义提供商（以兼容 OpenAI 格式的接口为例）：

{
  "models": {
    "mode": "merge",
    "providers": {
      "my-custom-provider": {
        "baseUrl": "https://api.your-provider.com/v1",
        "apiKey": "sk-your-api-key-here",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-3-5-sonnet",
            "name": "Claude 3.5 Sonnet",
            "reasoning": false,
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "reasoning": false,
            "input": ["text", "image"],
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

保存文件后，重启网关服务即可在控制台中选择这些自定义模型。

七、实战：将 OpenClaw 接入飞书机器人

将 AI 智能体接入日常办公软件，是释放生产力的最佳方式。以下是基于 umaax.com 提供的飞书接入流程。

第一步：在飞书开发者后台创建应用

1. 登录 飞书开放平台，进入“开发者后台”。
2. 点击“创建企业自建应用”，填写应用名称（如：OpenClaw Assistant）和描述。
3. 在应用详情页的左侧菜单中，找到“添加应用能力”，启用“机器人”功能。

第二步：配置权限与发布版本

1. 进入“权限管理”，搜索 im:，批量开通与消息、群组相关的权限。
2. 搜索并开通“通讯录”权限中的“通过手机号或邮箱获取用户ID信息”（确保机器人能识别对话用户）。
3. 进入“版本管理与发布”，创建一个新版本（如 1.0.0）并申请发布。

第三步：在 OpenClaw 中绑定飞书凭证

回到 OpenClaw 所在的终端，运行配置命令：

openclaw config

依次选择 local -> feishu -> Channels -> Link。系统若检测到缺少飞书插件，会提示 Install，按回车确认安装。

随后，系统会要求输入 App ID 和 App Secret。这两个凭证可以在飞书开发者后台的“凭证与基础信息”页面找到。将它们复制并粘贴到终端中。

第四步：配置事件订阅

回到飞书开放平台，进入“事件与回调”页面。在“事件配置”的订阅方式中，选择“使用长连接接收事件”。然后添加事件，勾选“接收消息”相关的事件类型。至此，飞书机器人已成功与本地的 OpenClaw 网关建立连接。在飞书中搜索该机器人并发送消息，即可获得 AI 的回复。

八、扩展能力：安装与使用 Skills（技能系统）

OpenClaw 的强大之处在于其丰富的 Skills 生态。通过安装不同的技能，AI 可以完成网页搜索、文件处理甚至在 CSDN 上自动发布文章等复杂任务（参考 github.com 的技能文档）。

官方提供了一个名为 Clawhub 的插件市场。要安装技能，首先需要安装 CLI 工具：

npm i -g clawhub

随后，可以通过命令行安装指定的技能。例如，安装网页搜索技能：

clawhub install "Tavily Web Search"

安装完成后，必须重启网关使技能生效：

openclaw gateway restart

在日常使用中，只需在对话中向 AI 下达类似“帮我搜索一下今天的人工智能新闻”的指令，OpenClaw 就会自动调用 Tavily 技能抓取网页信息并进行总结。

为了更直观地理解 AI Agent 的工作原理，可以参考以下介绍视频：