手把手教你5分钟搭私人助理，小白也能搞定

本文介绍了开源项目OpenClaw的安装配置与使用，旨在帮助用户搭建私人助理。内容涵盖前置组件（Node.js、Git、PowerShell等）的安装验证、源码安装步骤（克隆、构建、全局链接）、初始化配置（包括安全设置、网关参数、模型选择），以及飞书集成配置。重点包括Skill技能的配置与调用，以PPT制作为案例，并涉及量化相关技能（如akshare-kline、talib、backtrader）的自定义实现。文章还提及大厂衍生产品及生态应用，并强调工作空间核心文件与加载逻辑。

AI大模型应用开发OpenClaw安装配置Skill技能飞书集成量化

手把手教你5分钟搭私人助理，小白也能搞定

一、目标

  1. 掌握 OpenClaw 安装配置流程：前置要求、源码安装、初始化、飞书集成
  2. 学会 Skill 技能配置与使用，以 PPT 制作为核心案例掌握调用逻辑
  3. 独立搭建自定义 Skill，重点掌握量化技能（akshare-kline、talib、backtrader）
  4. 了解大厂基于 OpenClaw 的衍生产品及生态应用
  5. 掌握工作空间核心文件与加载逻辑

二、OpenClaw 安装配置

2.1 安装前置要求

需安装并配置以下组件：

组件要求验证命令核心作用
Node.js含 npm 和 node，建议 LTS 版 v20.x/v22.xnode -v / npm -v运行代码、管理依赖、构建项目、注册全局命令
Git for Windows完整安装，含 Git Bashwhere.exe git下载源码、运行 Bash 构建脚本、为 npm 提供 bash 环境
PowerShellWindows 自带版本无执行安装命令、设置环境变量、运行 openclaw 命令
Git Bash配置系统路径，供 npm 调用Test-Path "安装路径 /bin/bash.exe"执行.sh 构建脚本、作为 npm 的 script-shell

2.1.1 Node.js 安装要点

  1. 官网下载：https://nodejs.org/，优先选择 LTS 长期支持版
  2. 安装必选：勾选Add to PATH自动添加环境变量
  3. 验证标准：node -v 显示版本（如 v22.12.0）、npm -v 显示版本（如 11.3.0）

2.1.2 Git for Windows 安装要点

  1. 下载渠道：官网https://git-scm.com/download/win 或国内镜像https://registry.npmmirror.com/binary.html?path=git-for-windows/
  2. 核心配置：安装后需为 npm 指定 Git Bash 路径：
# 默认路径
npm config set script-shell "C:\\Program Files\\Git\\bin\\bash.exe"
# 自定义路径需替换为实际安装位置
npm config set script-shell "D:\\Program Files\\Git\\bin\\bash.exe"
  1. 路径验证：Test-Path "对应路径"返回 True 即为配置成功

2.1.3 前置安装快速检查清单

# 1. 检查Node.js版本
node -v
# 2. 检查npm版本
npm -v
# 3. 检查Git版本
git --version
# 4. 检查Git Bash路径（替换为实际安装路径）
Test-Path "D:\\Program Files\\Git\\bin\\bash.exe"
# 5. 若路径未知，查找bash.exe位置
where.exe bash

2.2 源码安装步骤

核心要求：所有命令均在 PowerShell 中执行，确保 Git Bash 路径已配置完成

克隆源码并进入项目目录：

git clone https://github.com/openclaw/openclaw.git
cd openclaw

再次校验 Git Bash 路径：

Test-Path "D:\\Program Files\\Git\\bin\\bash.exe"

安装项目依赖（约 1000+ 包，耗时数分钟，建议网络稳定时执行）：

npm install
  1. 构建项目（生成 dist 目录，包含编译后的核心文件）：
npm run build
  1. 全局链接（将 openclaw 注册为全局命令，支持任意目录调用）：
npm link
  1. 验证安装结果（显示版本如 2026.3.3 即为成功）：
openclaw --version

2.3 初始化配置（Onboarding）

  1. 启动配置向导（--install-daemon 为守护进程安装，实现后台运行）：
openclaw onboard --install-daemon

  1. 交互配置选项选择（按提示依次确认，核心选项如下）：

    • Security：Yes（确认理解安全警告，开启工具权限）
    • Onboarding mode：Manual（手动配置，灵活度更高）
    • Setup：Local gateway (this machine)（本地网关，仅本机访问）
    • Workspace：D:.openclaw\workspace（自定义路径需确保目录存在）
    • Model/auth provider：Qwen（通义千问，可后续更换）

  2. 网关基础配置（向导自动生成，默认参数如下）：

    • Port：18789（默认端口，避免冲突）
    • Bind：Loopback (127.0.0.1)（仅本地回环，保证安全性）
    • Auth：Token（自动生成访问令牌，用于控制面板登录）

2.4 飞书集成配置

2.4.1 飞书插件安装

若向导中出现Error: spawn npm ENOENT，手动全局安装插件：

npm install -g @openclaw/feishu

2.4.2 飞书凭证配置

  1. 启动配置向导：
openclaw configure
  1. 按层级选择配置项：Channels → Feishu/Lark → Use local plugin path（自动检测插件路径）
  2. 输入飞书应用信息：
    • App ID：飞书开放平台创建应用的唯一 ID
    • App Secret：飞书应用的密钥（需妥善保管）
    • Domain：Feishu (feishu.cn)（国内版飞书，国际版为larksuite.com）
    • Group policy：Open（需在群组中 @机器人才能响应，避免刷屏）

2.4.3 飞书后台配置要求（飞书开放平台端）

  1. 开启机器人能力（核心权限，无此权限无法接收消息）
  2. 订阅方式设置为：长连接接收事件（保证消息实时性）
  3. 配置必要权限：im:message、im:chat、contact:user.base:readonly（消息读取、聊天管理、用户基础信息读取）

2.5 构建 Control UI（网页界面）

若运行时提示Control UI assets missing，说明网页界面未构建，手动执行：

# 进入UI目录
cd ui
# 安装UI依赖
npm install
# 构建生产版本（生成可直接访问的网页文件）
npm run build
# 返回上级目录
cd ..

构建结果：dist/control-ui/ 目录下生成网页文件，为控制面板的前端资源

2.6 配置阿里云模型（OpenAI 兼容模式）

OpenClaw 支持阿里云通义千问模型，需通过 OpenAI 兼容接口配置，有配置文件和环境变量两种方式，推荐配置文件方式（持久化生效）。

2.6.1 配置文件方式（核心）

  1. 打开配置文件：C:\Users{用户名}.openclaw\openclaw.json
  2. 写入以下配置（替换 apiKey 为实际的阿里云 DashScope 密钥）：
{
  "models": {
    "providers": {
      "dashscope": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-xxx",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen-max-latest",
            "name": "Qwen Max Latest"
          }
        ]
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "quant-analyst",
        "model": "dashscope/qwen-max-latest",
        "workspace": "~/.openclaw/workspace",
        "skills": ["akshare-kline", "talib", "backtrader"]
      }
    ]
  }
}
  1. 配置项说明：
    • models.providers.dashscope：接入阿里云百炼 Qwen 模型的核心配置
    • agents.list[0].id：Agent 唯一标识，命令行用--agent quant-analyst指定
    • agents.list[0].model：Agent 使用的 LLM 模型，格式为provider/model-id（固定格式）
    • agents.list[0].skills：Agent 加载的技能列表，对应 skills/ 下的文件夹名

2.6.2 环境变量方式（临时生效）

启动网关前在 PowerShell 中设置，关闭窗口后失效：

$env:OPENAI_API_KEY="sk-你的API_KEY"
$env:OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
$env:OPENCLAW_MODEL="openai:qwen-turbo"

2.7 运行与使用

2.7.1 启动网关服务

openclaw gateway --port 18789

启动成功标识：控制台显示listening on ws://127.0.0.1:18789

2.7.2 打开控制面板

新开启一个 PowerShell 窗口，执行以下命令，自动打开浏览器并跳转到控制面板：

openclaw dashboard

访问地址：http://127.0.0.1:18789/#token=xxx（token 为初始化时自动生成）

2.7.3 三种使用方式

  1. 网页聊天：在 Control UI 的聊天界面直接发送消息，适合本地测试
  2. 飞书聊天：在飞书群组中 @机器人发送消息，适合办公场景
  3. API 调用：通过 WebSocket 协议连接ws://127.0.0.1:18789，适合二次开发集成

2.8 环境变量与配置文件常见问题

2.8.1 API KEY Error 解决

若页面提示 API KEY Error，按以下步骤排查：

检查环境变量设置是否正确：

$env:OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
$env:OPENCLAW_PROVIDER="openai"
$env:OPENAI_API_KEY="sk-your_api_key"
  1. 确认.env 文件加载优先级（从高到低）：
    • 当前工作目录（CWD）下的.env
    • 全局～/.openclaw/.env（即 $OPENCLAW_STATE_DIR/.env）
  2. 解决方案：
    • 方案 A：设置 Windows 用户级持久环境变量（推荐，永久生效）
    • 方案 B：在 C:\Users<用户名>.openclaw.env 中写入变量，作为全局备选

2.8.2 openclaw.json 配置格式错误

常见报错：启动 gateway 时提示Invalid config at openclaw.json，原因是配置格式未更新为最新版本。

核心修改点：

  1. models：改为models.providers，每个 provider 包含 baseUrl、apiKey、api、models 数组（不再支持扁平结构）
  2. agents：改为agents.list数组，每个 agent 包含 id、model、skills 等（不再支持agents.quant-analyst对象形式）

正确配置模板：

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "auth": {
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "dashscope/qwen-turbo"
      },
      "workspace": "~/.openclaw/workspace"
    },
    "mode": "merge",
    "list": [
      {
        "id": "quant-analyst",
        "model": "dashscope/qwen-turbo-latest",
        "workspace": "~/.openclaw/workspace",
        "skills": ["akshare-kline", "talib", "backtrader"]
      }
    ]
  },
  "models": {
    "providers": {
      "dashscope": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "${OPENAI_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen-turbo",
            "name": "Qwen Turbo"
          },
          {
            "id": "qwen-turbo-latest",
            "name": "Qwen Turbo Latest"
          },
          {
            "id": "qwen-max-latest",
            "name": "Qwen Max Latest"
          }
        ]
      }
    }
  }
}

2.8.3 常见问题解决汇总

问题解决方法
openclaw 命令未识别确保已运行npm link，若仍失效，重新执行 npm link 并检查环境变量
spawn npm ENOENT手动全局安装对应插件：npm install -g @openclaw/xxx
Control UI assets missing进入 ui 目录执行npm install + npm run build
agents.defaults.model: Invalid input检查模型 ID 格式是否为provider/model（如 dashscope/qwen-turbo）
JSON5 parse failed检查配置文件 JSON 格式，重点排查逗号、括号是否匹配
HTTP 403 forbidden检查阿里云 DashScope 控制台，确认 API Key 有效且模型已授权

2.9 配置文件目录结构

C:\Users\{用户名}\.openclaw\
├── openclaw.json          # 主配置文件（核心，所有配置均在此定义）
├── openclaw.json.bak      # 自动备份文件（配置出错时可恢复）
├── workspace\             # 工作目录（Agent运行目录，Skills优先从这里加载）
├── canvas\                # 画布文件（可视化相关资源）

相关文章

AgentAI大模型应用开发 · Agent从古诗词到智能投顾，5个案例手把手教你Agent进阶AI大模型应用开发 · Agent掌握Harness Engineering，让你的Agent不再失控AI大模型应用开发 · AICursor Rules配置后，AI编程效率翻倍了？试试这4种模式AI大模型应用开发 · Cursor手把手教你用API调教AI，4个实战案例直接复制AI大模型应用开发 · AI