banner
约 4,500 字
15 分钟

OpenClaw搭建私人助理实践

摘要

本文整理 OpenClaw 私人助理的本地安装、模型配置、飞书集成、控制台运行、Skills 安装与自定义量化技能开发流程。重点说明 OpenClaw 的工作区、配置文件、技能匹配机制和常见问题,方便后续搭建自己的 AI 助理或领域 Agent。

OpenClaw搭建私人助理实践

写在前面

OpenClaw 可以理解为一个本地运行的 AI Agent 框架。它把模型、工具、工作区、记忆文件和 Skills 组织在一起,让大模型不只是聊天,而是可以根据用户意图调用脚本、读写文件、连接飞书或网页控制台,完成相对完整的任务。

这篇文章的目标是搭建一个可运行的私人助理,并进一步扩展成一个量化交易 AI 同事。整体思路是先把 OpenClaw 本地网关跑起来,再配置模型和工作区,最后通过 Skills 把数据获取、技术指标计算和策略回测封装成可调用能力。

OpenClaw 本地助理架构(图由AI辅助绘制)
OpenClaw 本地助理架构(图由AI辅助绘制)

从工程角度看,OpenClaw 的关键不是界面,而是工作流。用户发出自然语言请求后,Gateway 把消息转给 Agent;Agent 根据系统提示、工具列表和 Skill 描述决定下一步;如果需要执行能力,就通过 exec 调用工作区中的脚本;脚本返回 JSON 后,再由模型整理成自然语言。

一、安装前准备

OpenClaw 在 Windows 上运行时,最容易出问题的是 Node、npm、Git Bash 和环境变量。因此安装前先检查基础环境。

组件

作用

验证命令

Node.js

运行 OpenClaw、安装依赖、构建项目

node -v

npm

安装 Node 依赖、执行构建命令

npm -v

Git for Windows

克隆源码,并提供 Git Bash

git --version

Git Bash

执行项目中的 Bash 构建脚本

where.exe bash

PowerShell

执行安装、配置、启动命令

Windows 默认提供

Node.js 建议安装 LTS 版本。安装时需要勾选添加到 PATH,否则后续 npm install 和 npm link 可能失败。

Git for Windows 的重点不是版本控制本身,而是它附带的 bash.exe。OpenClaw 的部分构建脚本依赖 Bash 环境,如果 npm 不知道用哪个 shell 执行脚本,就容易出现构建失败。

安装完成后,用下面的命令做一次快速检查。

powershell
node -v
npm -v
git --version
where.exe bash

# 如果知道 Git Bash 安装位置,也可以直接检查
Test-Path "D:\Program Files\Git\bin\bash.exe"

如果 where.exe bash 找不到路径,需要确认 Git for Windows 是否安装完整,或者手动把 Git Bash 加入环境变量。

二、源码安装 OpenClaw

2.1 克隆源码

进入准备放置项目的目录,执行:

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

2.2 配置 npm 使用 Git Bash

这是 Windows 环境下比较关键的一步。OpenClaw 构建过程会执行 .sh 脚本,因此需要让 npm 使用 Git Bash。

powershell
# 先确认你的 bash.exe 路径
Test-Path "D:\Program Files\Git\bin\bash.exe"

# 配置 npm 的 script-shell
npm config set script-shell "D:\Program Files\Git\bin\bash.exe"

如果 Git 安装在默认路径,可以改成:

powershell
npm config set script-shell "C:\Program Files\Git\bin\bash.exe"

2.3 安装依赖、构建、全局链接

powershell
npm install
npm run build
npm link

npm install 会安装大量依赖,第一次执行需要等待。npm run build 会生成运行所需的构建文件。npm link 的作用是把 openclaw 注册成全局命令,后续才能直接在 PowerShell 中使用。

验证安装:

powershell
openclaw --version

如果提示 openclaw 命令无法识别,优先检查 npm link 是否执行成功。

三、初始化配置

3.1 启动 Onboarding

OpenClaw 第一次运行需要初始化网关、工作区、模型和认证方式。

powershell
openclaw onboard --install-daemon

建议选择:

配置项

建议值

说明

Security

Yes

确认理解安全提示

Onboarding mode

Manual

手动配置,便于理解每个参数

Setup

Local gateway

在本机运行网关

Workspace

D:\.openclaw\workspace 或 ~/.openclaw/workspace

Agent 实际工作目录

Model/auth provider

Qwen

使用通义千问或 DashScope 兼容接口

3.2 网关基础配置

本地个人助理建议先使用回环地址,只允许本机访问。

配置项

建议值

Port

18789

Bind

127.0.0.1

Auth

Token

启动后如果看到类似下面的输出,说明网关已经监听成功。

纯文本
listening on ws://127.0.0.1:18789

四、模型配置

OpenClaw 可以通过 OpenAI 兼容接口接入 DashScope。主配置文件通常位于:

纯文本
C:\Users\<用户名>\.openclaw\openclaw.json

新版配置不再使用 models.default、models.flash、agents.quant-analyst 这类扁平结构,而是使用 models.providers 和 agents.list。

一个更清晰的配置结构如下。

JSON
{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "auth": {
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  "models": {
    "mode": "merge",
    "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" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "dashscope/qwen-turbo"
      },
      "workspace": "~/.openclaw/workspace"
    },
    "list": [
      {
        "id": "quant-analyst",
        "model": "dashscope/qwen-turbo-latest",
        "workspace": "~/.openclaw/workspace",
        "skills": ["akshare-kline", "talib", "backtrader"]
      }
    ]
  }
}

这里有三个点需要注意。

配置项

含义

models.providers.dashscope

定义 DashScope 作为模型供应商

agents.list[0].id

Agent 的唯一标识,例如 quant-analyst

agents.list[0].skills

当前 Agent 需要加载的技能名

如果页面或网关报 API Key 错误,可以先在当前 PowerShell 中临时设置环境变量。

powershell
$env:OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
$env:OPENCLAW_PROVIDER="openai"
$env:OPENAI_API_KEY="sk-your_api_key"

更稳定的方式是写入用户级环境变量,或者在:

纯文本
C:\Users\<用户名>\.openclaw\.env

中保存全局环境变量。需要注意,OpenClaw 会优先读取当前工作目录下的 .env,然后读取全局 ~/.openclaw/.env。如果启动目录不对,项目根目录 .env 可能不会被加载。

五、飞书与 Control UI

5.1 飞书集成

如果需要在飞书群里使用助理,需要安装飞书插件。

powershell
npm install -g @openclaw/feishu
openclaw configure

配置时重点填写:

配置项

说明

Channels

选择 Feishu/Lark

App ID

飞书开放平台应用 ID

App Secret

飞书应用密钥

Domain

国内版选择 feishu.cn

Group policy

一般选择 Open,群里 @ 机器人后响应

飞书开放平台需要开启机器人能力,事件订阅方式选择长连接,并授予消息和基础用户信息权限,例如 im:message、im:chat、contact:user.base:readonly。

5.2 构建 Control UI

如果启动时提示 Control UI assets missing,说明网页控制台没有构建好。进入 ui 目录手动构建。

powershell
cd ui
npm install
npm run build
cd ..

构建完成后,网页文件会出现在:

纯文本
dist/control-ui/

5.3 启动和使用

启动网关:

powershell
openclaw gateway --port 18789

打开控制面板:

powershell
openclaw dashboard

浏览器会打开类似地址:

纯文本
http://127.0.0.1:18789/#token=...

常见使用方式有三种。

方式

场景

Control UI

本地网页聊天和调试

飞书群聊

把私人助理接入日常 IM

WebSocket API

通过 ws://127.0.0.1:18789 集成到其他系统

六、常见安装问题

安装和配置阶段常见问题如下。

OpenClaw 常见安装问题
OpenClaw 常见安装问题

我实际更关注下面几类问题。

问题

根因

处理方式

openclaw 命令未识别

未执行或未成功执行 npm link

重新执行 npm link

spawn npm ENOENT

插件安装时找不到 npm

手动执行 npm install -g @openclaw/xxx

Control UI assets missing

UI 没有构建

进入 ui 目录执行 npm install 和 npm run build

agents.defaults.model: Invalid input

模型 ID 格式错误

使用 provider/model 格式

JSON5 parse failed

配置文件逗号或括号错误

检查 openclaw.json

HTTP 403 forbidden

API Key 无效或模型未授权

检查 DashScope 控制台

七、Skills 的基本概念

OpenClaw 中的 Skills 是模块化能力包。它不是单纯的函数,而是“能力说明 + 执行脚本 + 资源文件”的组合。它的作用是把通用模型变成某个领域的助手。

一个标准 Skill 通常长这样。

纯文本
my-skill/
├── SKILL.md
├── scripts/
│   └── run.py
├── templates/
└── resources/

SKILL.md 是核心文件。它包含 YAML 元数据和 Markdown 执行说明。

markdown
---
name: "skill-name"
description: "这个技能能做什么,在什么情况下触发,应该如何调用。"
version: "1.0.0"
---

# 技能指令

这里写执行流程、参数说明、禁止事项和输出格式。

Skills 的关键机制是渐进式披露。系统启动时不会把所有技能正文都塞进上下文,而是先加载很短的元数据和描述。当模型判断某个技能可能有用时,再读取完整 SKILL.md。这样可以节省 Token,也方便维护复杂能力。

Skills 和 Tools 的区别在于:

类型

本质

作用

Skill

专业能力包

告诉 Agent 如何处理某类任务

Tool

可执行函数或系统能力

提供明确输入输出和副作用

简单说,Skill 更像岗位 SOP,Tool 更像具体按钮或接口。

八、Skills 的安装、查找和加载

8.1 工作区很重要

OpenClaw 涉及三个目录。

目录

作用

C:\Users\<用户名>\.openclaw\

系统目录,存放全局配置、日志、内置资源

~/.openclaw/workspace

Agent 工作区,Skills 通常从这里加载

启动目录

执行 openclaw gateway 的目录,会影响配置读取

最容易踩坑的是:Skill 不是从下载位置直接加载,而是从 Agent 配置的 workspace 加载。也就是说,即使你已经用 clawhub 安装了技能,如果它没有出现在当前 Agent 的工作区,Agent 仍然可能看不到。

8.2 安装 Skill

先安装 clawhub。

powershell
npm install -g clawhub

搜索技能:

powershell
clawhub search "PPT"
clawhub search "股票"

安装到全局:

powershell
clawhub install ppt-generator

默认路径通常是:

纯文本
C:\Users\<用户名>\.openclaw\skills\ppt-generator

如果 Agent 实际工作区是 ~/.openclaw/workspace,需要复制到:

powershell
mkdir C:\Users\$env:USERNAME\.openclaw\workspace\skills

Copy-Item -Path "C:\Users\$env:USERNAME\.openclaw\skills\ppt-generator" `
  -Destination "C:\Users\$env:USERNAME\.openclaw\workspace\skills\" -Recurse

验证:

powershell
openclaw skills list

修改或新增 Skill 后,需要重启网关。

powershell
openclaw gateway --port 18789

九、Skill 调用链路

以“获取贵州茅台 600519.SH 最近 3 天日线”为例,完整链路如下。

OpenClaw Skill 调用链路(图由AI辅助绘制)
OpenClaw Skill 调用链路(图由AI辅助绘制)

实际过程可以拆成五步。

步骤

说明

1

用户在网页或飞书发送消息

2

Gateway 将消息转给 quant-analyst Agent

3

Agent 根据 Skill 描述判断使用 akshare-kline

4

Agent 通过 exec 执行 Python 脚本

5

脚本输出 JSON,模型整理成自然语言

对应执行命令是:

powershell
python skills/akshare-kline/scripts/get_kline.py 600519.SH 1d 3

这里最重要的是 description 字段。OpenClaw 的技能匹配不是简单关键词匹配,而是依赖 LLM 理解用户请求和 Skill 描述之间的关系。因此,description 要写清楚触发条件、正确命令和禁止行为。

十、量化交易 AI 同事

这里构建三个量化相关 Skills:数据获取、技术指标、策略回测。

纯文本
skills/
├── akshare-kline/
│   ├── SKILL.md
│   └── scripts/
│       └── get_kline.py
├── talib/
│   ├── SKILL.md
│   └── scripts/
│       └── calc_indicators.py
└── backtrader/
    ├── SKILL.md
    └── scripts/
        └── run_backtest.py

三个技能的分工如下。

三个量化 Skill 对比
三个量化 Skill 对比

Skill

作用

输入

输出

akshare-kline

获取 A 股 K 线

股票代码、周期、条数

K 线 JSON

talib

计算技术指标

指标名、股票代码或 CSV

指标 JSON

backtrader

运行策略回测

股票代码、日期范围、策略名

回测绩效 JSON

10.1 akshare-kline:获取 K 线数据

这个 Skill 的职责很单一:通过 AkShare 获取 A 股 K 线数据,并以 JSON 返回。用户可以说“获取贵州茅台最近 3 天日线”,Agent 需要转换成脚本命令。

SKILL.md 的重点是把正确执行方式写死。

markdown
---
name: akshare-kline
description: "获取 A 股 K 线。禁止 pip install、禁止检查环境。唯一正确做法:直接执行 exec,命令 python skills/akshare-kline/scripts/get_kline.py ..."
metadata:
  openclaw:
    os: ["win32"]
    requires:
      bins: ["python"]
      packages: ["akshare", "pandas"]
    permissions: ["exec"]
    timeout: 60
---

## 执行流程(必须遵守)

1. 收到 K 线请求后,直接执行 exec。
2. 命令:python skills/akshare-kline/scripts/get_kline.py <stock_code> [period] [count]
3. workdir 为工作区根目录。
4. 将脚本输出的 JSON 直接作为结果返回给用户。

禁止:安装依赖、检查环境、验证包、直接调用 akshare API。

脚本核心逻辑如下。

Python
def get_kline_data(stock_code, period="1d", count=100, adjust=""):
    try:
        symbol = parse_stock_code(stock_code)
        ak_period = period_to_akshare(period)
        start_date, end_date = calc_date_range(period, count)

        df = ak.stock_zh_a_hist(
            symbol=symbol,
            period=ak_period,
            start_date=start_date,
            end_date=end_date,
            adjust=adjust,
        )

        records = format_records(df.tail(count))
        return {
            "stock_code": stock_code,
            "period": period,
            "data_count": len(records),
            "data": records,
        }
    except Exception as error:
        return {"error": f"获取失败: {str(error)}"}

执行效果如下。用户只需要输入自然语言,Agent 最终会调用脚本并返回结构化结果。

akshare-kline 执行结果
akshare-kline 执行结果

10.2 talib:计算技术指标

talib 技能用于计算 SMA、EMA、MACD、RSI、ATR、BBANDS 等技术指标。它可以从 AkShare 获取股票数据,也可以读取 CSV。

调用示例:

powershell
python skills/talib/scripts/calc_indicators.py macd --stock 600519.SH
python skills/talib/scripts/calc_indicators.py rsi data.csv --period 14

脚本设计上适合用注册表模式。新增指标时,只需要往 INDICATORS 增加一项。

Python
INDICATORS = {
    "sma": (calc_sma, ["close"], {"period": 10}),
    "ema": (calc_ema, ["close"], {"period": 12}),
    "macd": (calc_macd, ["close"], {"fast": 12, "slow": 26, "signal": 9}),
    "rsi": (calc_rsi, ["close"], {"period": 14}),
    "atr": (calc_atr, ["high", "low", "close"], {"period": 14}),
    "bbands": (calc_bbands, ["close"], {"period": 20}),
}


def calc_macd(close, fast=12, slow=26, signal=9):
    macd, sig, hist = talib.MACD(
        close,
        fastperiod=fast,
        slowperiod=slow,
        signalperiod=signal,
    )
    return {
        "macd": macd.tolist(),
        "signal": sig.tolist(),
        "histogram": hist.tolist(),
    }

输出不建议返回全部序列。可以截取最后 30 条,同时给出 last_values,方便模型总结当前指标状态。

talib MACD 执行结果
talib MACD 执行结果

10.3 backtrader:策略回测

backtrader 技能用于运行策略回测。它可以从 MySQL 的 trade_stock_daily 表加载数据,也可以使用 AkShare 作为数据来源。支持策略包括 double_ma、macd、rsi、bbands、momentum。

调用示例:

powershell
python skills/backtrader/scripts/run_backtest.py 600519.SH 2025-01-01 2025-12-31 double_ma

以双均线策略为例,核心逻辑是短均线上穿长均线买入,短均线下穿长均线卖出。

Python
class DoubleMAStrategy(bt.Strategy):
    params = (("fast", 10), ("slow", 30))

    def __init__(self):
        self.ma_fast = bt.indicators.SMA(self.data.close, period=self.p.fast)
        self.ma_slow = bt.indicators.SMA(self.data.close, period=self.p.slow)
        self.crossover = bt.indicators.CrossOver(self.ma_fast, self.ma_slow)

    def next(self):
        if not self.position and self.crossover > 0:
            self.buy()
        elif self.position and self.crossover < 0:
            self.close()

回测流程如下。

Python
def run_backtest(stock_code, start_date, end_date, strategy_name):
    df = load_stock_data(stock_code, start_date, end_date)
    strategy = STRATEGIES[strategy_name]

    cerebro = bt.Cerebro()
    cerebro.addstrategy(strategy)
    cerebro.adddata(bt.feeds.PandasData(dataname=df))
    cerebro.broker.setcash(1_000_000)
    cerebro.broker.setcommission(commission=0.0002)
    cerebro.addsizer(bt.sizers.PercentSizer, percents=95)

    cerebro.addanalyzer(bt.analyzers.SharpeRatio, _name="sharpe")
    cerebro.addanalyzer(bt.analyzers.DrawDown, _name="drawdown")
    cerebro.addanalyzer(bt.analyzers.TradeAnalyzer, _name="trades")

    results = cerebro.run()
    return extract_metrics(results, cerebro)

回测输出应包含总收益率、年化收益率、最大回撤、夏普比率、交易次数和胜率。

backtrader 回测结果
backtrader 回测结果

这里要注意,Agent 只负责调度。真正的量化逻辑应写在 Python 脚本里。模型负责理解用户请求、选择技能、拼接参数、执行脚本和解释结果;策略计算、数据加载、回测指标必须由确定性代码完成。

十一、技能看不到怎么办

如果对话时 Agent 看不到 akshare-kline、talib、backtrader,通常不是模型问题,而是工作区和配置问题。

优先检查四件事。

检查项

说明

Skill 是否在工作区

~/.openclaw/workspace/skills/<skill-name>

openclaw.json 是否注册

agents.list.skills 中是否包含技能名

当前 Agent 是否正确

Dashboard 是否切到 quant-analyst

Gateway 是否重启

修改配置或 Skill 后必须重启

同步命令示例:

powershell
xcopy /E /Y "skills\akshare-kline\*" "%USERPROFILE%\.openclaw\workspace\skills\akshare-kline\"
xcopy /E /Y "skills\talib\*" "%USERPROFILE%\.openclaw\workspace\skills\talib\"
xcopy /E /Y "skills\backtrader\*" "%USERPROFILE%\.openclaw\workspace\skills\backtrader\"

几个常见问题也要提前处理。

问题

处理方式

{baseDir} 占位符不生效

改用工作区相对路径 skills/xxx/scripts/run.py

AI 反复执行 pip install

在 description 和正文中明确禁止安装依赖

Windows 没有 python3

requires.bins 和命令都写 python

.env 不被加载

把 API Key 写入全局 .env 或 openclaw.json

backtrader 找不到数据库配置

在技能目录增加 .env 查找逻辑

十二、如何新增一个 Skill

新增 Skill 可以按固定流程执行。

新增 Skill 流程(图由AI辅助绘制)
新增 Skill 流程(图由AI辅助绘制)

假设新增一个 stock-screener 选股技能,目录结构如下。

纯文本
skills/
└── stock-screener/
    ├── SKILL.md
    └── scripts/
        └── screener.py

SKILL.md 可以这样写。

markdown
---
name: stock-screener
description: "A 股选股筛选。直接执行 exec,命令 python skills/stock-screener/scripts/screener.py ..."
metadata:
  openclaw:
    requires:
      bins: ["python"]
    permissions: ["exec"]
    timeout: 60
---

# 选股技能

## 执行流程(必须遵守)

1. 收到选股请求后,直接执行 exec。
2. 命令:python skills/stock-screener/scripts/screener.py <条件参数>
3. 将脚本输出的 JSON 直接返回给用户。

禁止:安装依赖、检查环境。

然后在 openclaw.json 中注册。

JSON
{
  "agents": {
    "list": [
      {
        "id": "quant-analyst",
        "skills": [
          "akshare-kline",
          "talib",
          "backtrader",
          "stock-screener"
        ]
      }
    ]
  }
}

最后同步到工作区,重启 Gateway,通过自然语言测试。

十三、工作空间文件

OpenClaw 的私人助理不仅由模型和技能组成,还依赖一组工作空间文件。这些文件定义身份、规则、用户偏好、长期记忆和工具信息。

OpenClaw 工作空间文件
OpenClaw 工作空间文件

几个核心文件的职责如下。

文件

作用

写法原则

SOUL.md

定义性格、语气、价值观

只写“你是谁”,不要写流程

AGENTS.md

定义规则、工作流、红线

相当于员工手册

IDENTITY.md

定义名字、头像、外在形象

简洁,3-5 行即可

USER.md

用户画像和沟通偏好

写稳定信息,不写临时任务

MEMORY.md

长期记忆蒸馏结果

定期整理,避免无限增长

TOOLS.md

工具路径、API、环境信息

只写在哪里,不写怎么做

BOOTSTRAP.md

首次初始化引导

完成后删除

加载顺序可以理解为:先注入身份和规则,再读取用户画像和记忆,最后按需加载 Skills。需要注意 Token 消耗。MEMORY.md 和其他长期文件不能写成流水账,否则每次会话都会浪费上下文。

小结

搭建 OpenClaw 私人助理的核心步骤是:

纯文本
安装 Node / Git Bash
→ 源码安装 OpenClaw
→ onboard 初始化
→ 配置模型和工作区
→ 启动 Gateway 与 Dashboard
→ 安装或编写 Skills
→ 注册到 openclaw.json
→ 同步到 workspace
→ 通过对话验证调用链路

从个人使用角度看,OpenClaw 的价值在于把大模型变成可持续扩展的工作台。模型负责理解意图和组织流程,Skills 负责封装领域能力,Python 脚本负责确定性执行。对于量化交易这种任务,数据获取、指标计算和回测都应该落在脚本里,模型只做调度和解释。

后续如果继续扩展,可以优先做三件事:整理稳定的 AGENTS.md 和 USER.md,把常用任务封装成 Skills,把所有脚本输出统一为 JSON。这样私人助理才不是一次性聊天窗口,而是一个可以长期维护的个人工作系统。

END