六、openclaw-搭建你的私人助理

# 六、openclaw-搭建你的私人助理 ## 一、学习目标 1. 掌握 OpenClaw 的安装配置流程，包含前置要求、源码安装、初始化、飞书集成等 2. 学会 Skill 技能的配置与实际使用，以 PPT 制作案例为核心掌握技能调用逻辑 3. 能够独立搭建自定义 Skill 技能，重点掌握量化相关技能（akshare-kline、talib、backtrader）的实现 4. 了解大厂基于 OpenClaw 的衍生产品及生态应用 5. 掌握 OpenClaw 工作空间的核心文件与加载逻辑 ## 二、OpenClaw 安装配置 ### 2.1 安装前置要求 需安装并配置以下组件，各组件作用及验证方式如下表： 表格 | **组件** | **要求** | **验证命令** | **核心作用** | | --- | --- | --- | --- | | Node.js | 含 npm 和 node，建议 LTS 版 v20.x/v22.x | node -v / npm -v | 运行代码、管理依赖、构建项目、注册全局命令 | | Git for Windows | 完整安装，包含 Git Bash | where.exe git | 下载源码、运行 Bash 构建脚本、为 npm 提供 bash 环境 | | PowerShell | Windows 自带版本 | 无 | 执行安装命令、设置环境变量、运行 openclaw 系列命令 | | Git Bash | 配置系统路径，供 npm 调用 | Test-Path "安装路径 /bin/bash.exe" | 执行.sh 构建脚本、作为 npm 的 script-shell | **思考疑问**：若安装 Node.js 时未勾选 Add to PATH，手动配置环境变量的具体步骤是什么？ #### 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" ``` 3. 路径验证：`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 ``` 2. 全局链接（将 openclaw 注册为全局命令，支持任意目录调用） ``` npm link ``` 3. 验证安装结果（显示版本如 2026.3.3 即为成功） ``` openclaw --version ``` **思考疑问**：执行 npm install 时出现依赖下载失败，有哪些可行的解决办法（如镜像源切换）？ ### 2.3 初始化配置（Onboarding） 1. 启动配置向导（--install-daemon 为守护进程安装，实现后台运行） ``` openclaw onboard --install-daemon ``` 2. 交互配置选项选择（按提示依次确认，核心选项如下）： - Security：Yes（确认理解安全警告，开启工具权限） - Onboarding mode：Manual（手动配置，灵活度更高） - Setup：Local gateway (this machine)（本地网关，仅本机访问） - Workspace：D:.openclaw\\workspace（自定义路径需确保目录存在） - Model/auth provider：Qwen（通义千问，可后续更换为其他模型） 3. 网关基础配置（向导自动生成，默认参数如下）： - Port：18789（默认端口，避免与其他服务冲突） - Bind：Loopback (127.0.0.1)（仅本地回环，保证安全性） - Auth：Token（自动生成访问令牌，用于控制面板登录） **思考疑问**：若需要让局域网内其他设备访问 OpenClaw，需将 Bind 修改为哪个地址？ ### 2.4 飞书集成配置 #### 2.4.1 飞书插件安装 若向导中出现`Error: spawn npm ENOENT`，手动全局安装插件： ``` npm install -g @openclaw/feishu ``` #### 2.4.2 飞书凭证配置 1. 启动配置向导： ``` openclaw configure ``` 2. 按层级选择配置项：Channels → Feishu/Lark → Use local plugin path（自动检测插件路径） 3. 输入飞书应用信息： - App ID：飞书开放平台创建应用的唯一 ID - App Secret：飞书应用的密钥（需妥善保管，避免泄露） - Domain：Feishu ([feishu.cn](https://feishu.cn))（国内版飞书，国际版为\[larksuite.com\](https://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"] } ] } } ``` 3. 配置项说明： - 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" ``` **思考疑问**：若同时配置了配置文件和环境变量，OpenClaw 的优先级是怎样的？ ### 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\ # 画布文件（可视化相关资源） ``` ## 三、Skill 技能配置与使用 ### 3.1 Agent Skills 核心概念 1. **定义**：Agent Skills 是模块化、标准化的能力封装机制，让 AI 智能体从通用型转变为专业型，本质是**可移植的能力包**（类似给 AI 安装的 APP / 岗位 SOP）。 2. **核心特征**： - **物理形态**：以文件夹为单位，核心文件为 SKILL.md（YAML 前置元数据 + Markdown 文档），可包含脚本、模板、参考文档等可选资源 - **渐进式披露**：系统启动仅加载 50-100 tokens 的元数据，按需加载完整指令（2-5K tokens），运行时动态执行脚本，减少 Token 消耗 - **与传统工具的区别**：Skills 是**专业知识封装**（塑造 AI 思维和解决问题的方法），Tools 是**可执行函数**（明确输入输出和副作用） **思考疑问**：Skills 和 Tools 在实际使用中，如何根据场景选择？ ### 3.2 Skills 定义结构 每个 Skill 为独立文件夹，目录结构固定，不可随意修改： ``` my-skill/ ├── SKILL.md # 核心定义文件（必须存在，包含元数据和操作指令） ├── scripts/ # 可选脚本文件夹（存放Python/Shell等执行脚本） ├── templates/ # 可选模板文件夹（存放PPT/HTML等模板文件） └── resources/ # 可选资源文件夹（存放图片、配置文件等静态资源） ``` #### 3.2.1 SKILL.md 文件结构（固定格式） ``` # YAML前置元数据（必须放在文件开头，严格遵循YAML语法） name: "技能名称" description: "技能描述（关键，LLM根据此匹配技能）" version: "1.0.0" # Markdown正文（AI的操作手册，包含执行流程、参数说明、触发示例等） ## 执行流程 1. 步骤1 2. 步骤2 ## 参数说明 - 参数1：说明 - 参数2：说明 ``` ### 3.3 OpenClaw 工作目录体系 OpenClaw 涉及三个核心工作目录，**Skills 加载路径为 Agent 配置的 workspace**，这是核心要点，易混淆！ 1. **OpenClaw 系统目录**：C:\\Users <用户名>.openclaw\\ → 存放全局配置、日志、内置 Skills 2. **Agent 工作区**：由 openclaw.json 中的`workspace`字段指定 → **实际运行目录，Skills 优先从这里加载**（核心） 3. **启动目录**：执行`openclaw gateway`的目录 → 决定读取哪个 openclaw.json（优先级视版本而定） **核心结论**：Skills 不是从 clawhub install 的位置直接加载，而是从 Agent 配置的 workspace 加载！ ### 3.4 openclaw.json 技能相关配置 #### 3.4.1 配置文件位置优先级（从高到低） 1. 当前启动目录：./openclaw.json（执行命令的目录） 2. 用户主目录：/.openclaw/openclaw.json（C:\\Users <用户名>.openclaw\\） #### 3.4.2 关键配置项 ``` { "agents": { "defaults": { "model": { "primary": "dashscope/qwen-max-latest" }, "workspace": "/.openclaw/workspace" // 全局默认工作区，Skills加载路径 }, "list": [ { "id": "quant-analyst", "model": "dashscope/qwen-max-latest", "workspace": "/.openclaw/workspace", // 覆盖全局默认，每个Agent可独立配置 "skills": ["ppt-generator", "akshare-kline", "talib"] // 声明加载的技能列表 } ] } } ``` **配置要点**： - `workspace`：指定 Agent 的工作根目录，Skills 会从`/skills/`加载（必须存在 skills 子目录） - `skills`：仅声明 Agent 需要加载的 Skills，**文件必须实际存在于 workspace 的 skills 目录中**，否则无法加载 ### 3.5 Skills 安装步骤 #### 3.5.1 前置准备：安装 clawhub（技能包管理工具） ``` # 管理员权限运行，全局安装clawhub npm install -g clawhub ``` #### 3.5.2 技能安装方式 ##### 方式 1：安装到全局（默认） ``` clawhub install ppt-generator # 默认安装路径：C:\Users\<用户名>\.openclaw\skills\ppt-generator ``` ##### 方式 2：安装到指定工作区 ``` clawhub install ppt-generator --workspace "D:\你的项目\.openclaw" ``` #### 3.5.3 核心步骤：将技能同步到 Agent 工作区 安装后的技能需手动同步到 Agent 配置的 workspace 的 skills 目录，否则 Agent 无法加载，步骤如下： ``` # 1. 确认Agent的workspace（如~/.openclaw/workspace） # 2. 创建skills目录（若不存在） mkdir C:\Users\$env:USERNAME\.openclaw\workspace\skills # 3. 复制技能到工作区（递归复制所有文件） Copy-Item -Path "C:\Users\$env:USERNAME\.openclaw\skills\ppt-generator" ` -Destination "C:\Users\$env:USERNAME\.openclaw\workspace\skills\" -Recurse ``` #### 3.5.4 技能验证 执行以下命令，查看已就绪的技能，标注为`ready`即为加载成功： ``` openclaw skills list ``` **思考疑问**：执行 openclaw skills list 时，技能标注为`missing`，除了路径问题，还有哪些排查方向？ ### 3.6 Skills 查找方法 #### 方法 1：使用 clawhub search 命令行搜索 ``` # 按关键词搜索，如PPT、基金分析、股票等 clawhub search "PPT" ``` **搜索结果**：返回技能名称、描述、评分等信息，如`ppt-generator`（乔布斯风 PPT 生成）。 #### 方法 2：使用 clawhub.ai 网页检索 访问地址：https://clawhub.ai/，输入关键词（如 ppt-generator），可查看技能详情、作者、下载量、安全扫描结果等。 #### 方法 3：GitHub 开源仓库查找 推荐仓库：https://github.com/huangserva/servasyy\_skills，包含 PPT 制作、漫画生成、文档写作等多种技能，步骤如下： 1. 下载仓库 ZIP 包，解压到本地 2. 将需要的技能文件夹（如 ppt-generator）复制到 Agent 工作区的 skills 目录 3. 重启 OpenClaw 网关，加载新技能 ### 3.7 案例：PPT 制作技能的使用 #### 3.7.1 基础使用：调用默认 ppt-generator 技能 用户请求：`帮我做一个PPT，讲解下人工智能的概念` 1. OpenClaw 匹配到 ppt-generator 技能的触发条件（含 PPT、演示文稿等关键词） 2. AI 读取 SKILL.md，提炼讲稿内容并生成幻灯片大纲 3. 尝试调用 scripts/generate.py 生成 HTML 文件，若脚本缺失，直接基于模板生成 HTML 代码 4. 返回 HTML 代码，用户保存为.html 文件即可在浏览器中打开 #### 3.7.2 进阶使用：调用自定义 PPT 技能 1. 从 GitHub 下载自定义 ppt-generator 技能，同步到 Agent 工作区 2. 重启网关：`openclaw gateway --port 18789` 3. 发送请求：`帮我做一个PPT，讲解下人工智能的概念` 4. AI 加载新技能的 SKILL.md，生成更详细的大纲（含封面、目录、核心内容、结束页） 5. 生成完整的 HTML 代码，支持触摸滑动、CSS 动画等交互效果，可直接保存并打开 #### 3.7.3 PPT 生成的两种路径 ##### 路径 A：Python 图片生成流程（生成.pptx/.pdf） 1. 调用 shared-lib/presentation/ 下的 Python 模块 2. 创建会话→生成图像描述 Prompt→调用图像 API 生成 PNG 幻灯片 3. 通过 assemble_pptx.py 将 PNG 图片组装成.pptx 文件，支持导出为.pdf ##### 路径 B：直接生成 HTML（快速演示，无需图像 API） 1. AI 直接输出自包含的 HTML 文件（集成 CSS 动画 + JS 翻页交互） 2. 保存到 workspace 目录，用户在浏览器中直接打开即可查看演示效果 #### 3.7.4 核心脚本：assemble_pptx.py **作用**：将生成的 slide_01.png、slide_02.png 等图片拼装成.pptx 文件 **核心功能**： 1. 读取图片目录中所有 slide_\*.png 文件 2. 若存在 ppt_content.yaml 配置，在图片上叠加文字层 3. 用 python-pptx 库创建 16:9 比例的 PowerPoint 文件 支持命令行调用： ``` python assemble_pptx.py --input_dir 图片目录 --output 输出文件.pptx ``` ### 3.8 技能使用的整体运行流程 1. 用户发送自然语言消息（如`帮我做一个PPT`） 2. OpenClaw 检查 Agent 已安装的 skills 列表，确认技能文件存在 3. LLM 根据消息内容匹配 SKILL.md 的`description`字段（触发条件） 4. AI agent 读取 SKILL.md 作为操作指南，分析用户需求（场景、受众、调性） 5. 根据 SKILL.md 中的风格要求选择对应生成方式（如乔布斯风、极简风） 6. 调用技能对应的脚本或模板，生成结果并返回给用户 ## 四、Skill 技能搭建 ### 4.1 量化技能搭建核心目标 创建三个独立的量化交易相关 Skill，实现**A 股 K 线数据获取**、**技术指标计算**、**交易策略回测**的完整量化流程，三个技能相互独立，可单独调用也可组合使用。 ### 4.2 量化技能整体结构 所有量化技能均遵循 Skills 标准目录结构，每个技能为独立文件夹，包含 SKILL.md 和 scripts 子目录，结构如下： ``` skills/ ├── akshare-kline/ # K线数据获取技能 │ ├── SKILL.md │ └── scripts/ │ └── get_kline.py ├── talib/ # 技术指标计算技能 │ ├── SKILL.md │ └── scripts/ │ └── calc_indicators.py └── backtrader/ # 策略回测技能 ├── SKILL.md └── scripts/ └── run_backtest.py ``` **核心原则**：每个技能独立开发、测试、部署，降低耦合度，便于维护和扩展。 ### 4.3 量化技能 1：akshare-kline（A 股 K 线数据获取） #### 4.3.1 技能功能 通过 akshare 库获取 A 股任意股票的 K 线数据（日线、分钟线等），返回标准化 JSON 格式数据，为后续指标计算和回测提供数据源。 #### 4.3.2 前置依赖 ``` pip install akshare pandas ``` #### 4.3.3 脚本用法 ``` python scripts/get_kline.py [period] [count] # 示例：获取贵州茅台最近100天日线数据 python scripts/get_kline.py 600519.SH 1d 100 ``` - stock_code：股票代码（如 600519.SH 为贵州茅台，000001.SZ 为平安银行） - period：K 线周期（1d = 日线，1min=1 分钟线，5min=5 分钟线） - count：获取数据条数（最新 N 条） #### 4.3.4 SKILL.md 编写（核心） **关键要求**：明确禁止 AI 执行 pip install、检查环境等操作，直接执行 exec 命令，避免冗余步骤。 ``` name: akshare-kline description: "获取A股K线。禁止pip install、禁止检查环境。唯一正确做法：直接执行exec，命令python skills/akshare-kline/scripts/get_kline.py ..." metadata: openclaw: emoji: "📈" os: ["win32"] # 支持的操作系统 requires: bins: ["python"] # 需要的可执行程序 packages: ["akshare", "pandas"] # 仅声明，不自动安装 permissions: - "exec" # 必须的权限 timeout: 60 # 超时时间（秒） ## 执行流程（必须遵守） 1. 收到K线请求后，直接执行exec，无需检查pip、python版本等 2. 命令格式：python skills/akshare-kline/scripts/get_kline.py [period] [count] 3. workdir为工作区根目录，路径使用相对路径 4. 将脚本输出的JSON直接作为结果返回给用户 ## 触发示例 - 获取贵州茅台600519.SH最近30天日线数据 - 查000001.SZ的5分钟线，最近100条 ``` #### 4.3.5 核心脚本：get_kline.py 逻辑 1. 接收命令行参数（股票代码、周期、条数） 2. 通过 akshare 获取 K 线数据，返回 DataFrame 3. 数据校验（检查数据是否为空、字段是否完整） 4. 标准化列名（处理中英文列名不一致问题） 5. 截取最后 count 条数据并格式化 6. 返回标准 JSON 结构（含股票代码、周期、数据条数、具体 K 线数据） 7. 异常处理：捕获错误并返回错误信息 JSON #### 4.3.6 技能执行逻辑 用户请求（获取茅台 K 线）→ Gateway → Agent (LLM) → 匹配 akshare-kline 技能 → 调用 exec 工具 → 执行 get_kline.py → 返回 JSON 结果 → LLM 整理后回复用户 ### 4.4 量化技能 2：talib（技术指标计算） #### 4.4.1 技能功能 基于 TA-Lib 库计算 A 股股票的常见技术指标，包括 SMA、EMA、MACD、RSI、ATR、BBANDS 等，支持从 akshare 获取数据或读取本地 CSV 文件，返回 JSON 格式指标数据。 #### 4.4.2 前置依赖 ``` pip install talib numpy pandas akshare ``` #### 4.4.3 脚本用法 ``` # 方式1：从akshare获取股票数据计算指标 python scripts/calc_indicators.py --stock # 示例：计算贵州茅台的MACD指标 python scripts/calc_indicators.py macd --stock 600519.SH # 方式2：读取本地CSV文件计算指标 python scripts/calc_indicators.py --period # 示例：读取data.csv计算14日RSI指标 python scripts/calc_indicators.py rsi data.csv --period 14 ``` #### 4.4.4 核心脚本：calc_indicators.py 逻辑 定义指标注册表（INDICATORS 字典），键为指标名，值为（计算函数、所需字段、默认参数） ``` INDICATORS = { "sma": (calc_sma, ["close"], {"period": 10}), "macd": (calc_macd, ["close"], {"fast": 12, "slow": 26, "signal": 9}), "rsi": (calc_rsi, ["close"], {"period": 14}) } ``` 1. 支持两种数据来源：--stock 参数（从 akshare 获取）或 CSV 文件路径 2. 调用 TA-Lib 库计算指标（TA-Lib 接收 numpy 数组，返回 numpy 数组） 3. 数据格式化：将 numpy 数组转换为列表，截取最后 30 条数据（避免数据量过大） 4. 输出 JSON 结构：含指标数据、数据长度、最新值（last_values） 5. 异常处理：捕获数据获取失败、指标计算错误等异常 #### 4.4.5 技能执行逻辑 用户请求（计算 MACD）→ Gateway → Agent (LLM) → 匹配 talib 技能 → 调用 exec 工具 → 执行 calc_indicators.py → 返回 JSON 结果 → LLM 整理后回复用户 ### 4.5 量化技能 3：backtrader（交易策略回测） #### 4.5.1 技能功能 基于 Backtrader 框架运行量化交易策略回测，支持双均线、MACD、RSI、布林带、动量 5 种内置策略，数据来源为 MySQL 数据库或 akshare，返回回测绩效指标（收益率、最大回撤、夏普比率等）。 #### 4.5.2 前置依赖 ``` pip install backtrader pandas pymysql python-dotenv akshare ``` #### 4.5.3 脚本用法 ``` python scripts/run_backtest.py # 示例：双均线策略回测贵州茅台2024-2025年数据 python scripts/run_backtest.py 600519.SH 2024-01-01 2025-12-31 double_ma ``` - strategy_name：策略名（double_ma/macd/ rsi/bbands/ momentum） #### 4.5.4 核心脚本：run_backtest.py 逻辑 1. 加载.env 配置文件（数据库连接信息、回测参数） 2. 从 MySQL（trade_stock_daily 表）或 akshare 加载股票 K 线数据 3. 初始化 Backtrader 引擎（Cerebro），设置初始资金、手续费、仓位比例 4. 添加指定策略（如双均线策略 DoubleMAStrategy） 5. 添加分析器：夏普比率（SharpeRatio）、最大回撤（DrawDown）、交易分析（TradeAnalyzer） 6. 运行回测，提取绩效指标 7. 返回 JSON 结构：含股票代码、策略名、回测时间、收益率、最大回撤、夏普比率、交易次数、胜率等 #### 4.5.5 双均线策略核心代码示例 ``` import backtrader as bt class DoubleMAStrategy(bt.Strategy): # 策略参数：10日均线、30日均线 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: if self.crossover > 0: self.buy() # 有仓位时，死叉卖出 elif self.crossover < 0: self.close() ``` #### 4.5.6 技能执行逻辑 用户请求（双均线回测）→ Gateway → Agent (LLM) → 匹配 backtrader 技能 → 调用 exec 工具 → 执行 run_backtest.py → 返回 JSON 结果 → LLM 整理后回复用户 ### 4.6 三个量化技能对比 | **维度** | **akshare-kline** | **talib** | **backtrader** | | --- | --- | --- | --- | | 核心用途 | 获取 A 股 K 线数据 | 计算技术指标 | 运行交易策略回测 | | 数据来源 | akshare | akshare / CSV 文件 | MySQL 数据库 /akshare | | 核心依赖 | akshare、pandas | talib、numpy、pandas | backtrader、pymysql、pandas | | 脚本参数 | 股票代码 + 周期 + 条数 | 指标名 + 股票代码 / CSV 路径 | 股票代码 + 日期范围 + 策略名 | | 超时设置 | 60s | 30s | 120s | | 平台限制 | Windows + Linux | Windows + Linux | Windows + Linux | ### 4.7 常见问题：技能看不到 / 无法调用的解决 **问题现象**：与 AI 对话时，AI 无法识别 akshare-kline、talib 等自定义技能，仅显示 Feishu、Gemini 等内置技能。 **核心原因**：技能加载优先级问题，加载优先级：extra < bundled < managed < agents-skills < **workspace**（最高），若技能未放在 workspace 目录，无法被 Agent 加载。 **解决方案**： 1. **路径同步**：将技能文件夹复制到 Agent 工作区：C:\\Users <用户名>.openclaw\\workspace\\skills\\ 2. **配置确认**：在 openclaw.json 中显式指定 workspace，确保`agents.defaults.workspace`和`quant-analyst.workspace`均设为～/.openclaw/workspace 3. **Agent 切换**：在 Dashboard 中切换到**quant-analyst**智能体（技能绑定到该 Agent） 4. **重启网关**：修改配置和文件后，必须重启网关才能生效：`openclaw gateway --port 18789` ### 4.8 量化技能使用常见知识 #### 4.8.1 Backtrader 支持的策略及逻辑 | **策略名** | **核心逻辑** | **适用场景** | | --- | --- | --- | | double_ma（双均线） | 10 日均线金叉 30 日均线买入，死叉卖出 | 趋势行情，简单直观 | | macd | MACD 线上穿信号线买入，线下穿卖出 | 捕捉趋势转折点，过滤震荡 | | rsi | RSI<30 超卖买入，RSI>70 超买卖出 | 震荡行情，避免追高杀跌 | | bbands（布林带） | 价格触及下轨买入，触及上轨卖出 | 利用波动率捕捉超买 / 超卖 | | momentum（动量） | 近期涨幅靠前的股票买入 | 跟踪强势股，捕捉加速上涨 | #### 4.8.2 TA-Lib 核心技术指标及应用 TA-Lib 支持 158 种技术指标，核心常用指标如下： | **指标** | **说明** | **核心应用** | | --- | --- | --- | | SMA | 简单移动平均 | 趋势判断（如 10/30 日均线） | | EMA | 指数移动平均 | 更敏感的趋势跟踪（如 12/26 日 EMA） | | MACD | 指数平滑异同移动平均 | 金叉 / 死叉买卖信号 | | RSI | 相对强弱指标 | 超买超卖判断（核心） | | ATR | 真实波幅均值 | 止损设置（止损 = 入场价 - 2×ATR） | | BBANDS | 布林带 | 波动率监控，超买超卖信号 | **RSI 超买超卖判断标准**： - RSI > 70：超买区，可能回调，考虑卖出 - RSI < 30：超卖区，可能反弹，考虑买入 - 30 < RSI < 70：震荡行情，需结合其他指标确认 #### 4.8.3 完整量化流程规划（数据采集→指标计算→回测） 1. **明确目标**：确定策略、目标股票、回测周期（建议从单股票 + 单策略开始） 2. **数据采集**：用 akshare-kline 获取 K 线数据，存入 MySQL trade_stock_daily 表 3. **指标计算**：用 talib 计算核心指标（RSI、MACD、布林带），为策略提供信号 4. **策略回测**：用 backtrader 运行回测，配置.env 文件（数据库、资金、手续费） 5. **迭代优化**：根据回测结果调整策略参数，加入风控（止损 / 止盈）、仓位管理 ### 4.9 如何新增一个自定义 Skill 以新增**stock-screener（A 股选股）** 技能为例，掌握自定义技能的完整搭建流程，**所有自定义技能均遵循此流程**。 #### 步骤 1：创建技能目录结构（固定格式） ``` # 在skills目录下创建stock-screener文件夹 mkdir -p skills/stock-screener/scripts # 创建核心文件 touch skills/stock-screener/SKILL.md touch skills/stock-screener/scripts/screener.py ``` #### 步骤 2：编写 SKILL.md 文件（元数据 + 操作手册） 严格遵循 YAML+Markdown 格式，明确技能描述、执行流程、禁止事项： ``` name: stock-screener description: "A股选股筛选。直接执行exec，命令python skills/stock-screener/scripts/screener.py ..." metadata: openclaw: requires: bins: ["python"] packages: ["pandas", "akshare"] permissions: ["exec"] timeout: 60 ## 执行流程（必须遵守） 1. 收到选股请求后，直接执行exec，无需检查环境和依赖 2. 命令格式：python skills/stock-screener/scripts/screener.py <条件参数> 3. 工作目录为Agent工作区根目录，使用相对路径 4. 将脚本输出的JSON直接返回给用户，无需额外处理 禁止：安装依赖、检查Python版本、修改脚本参数。 ``` #### 步骤 3：编写执行脚本（screener.py） 实现选股核心逻辑，要求**输入为命令行参数，输出为标准 JSON 格式**，包含异常处理，确保脚本可独立运行。 #### 步骤 4：注册到 openclaw.json 在 Agent 的 skills 列表中添加新技能名，确保配置生效： ``` { "agents": { "list": [ { "id": "quant-analyst", "skills": ["akshare-kline", "talib", "backtrader", "stock-screener"] } ] } } ``` #### 步骤 5：同步到 Agent 工作区 将新技能文件夹复制到～/.openclaw/workspace/skills/，确保路径正确。 #### 步骤 6：重启网关并测试 ``` # 重启网关 openclaw gateway --port 18789 # 在控制面板或飞书中发送请求，测试技能是否可用 ``` **思考疑问**：自定义技能的脚本中需要调用第三方 API（如股票数据 API），如何处理 API 密钥的配置，避免泄露？ ### 4.10 技能搭建核心总结 搭建自定义 Skill 的核心步骤（量化技能为例）： 1. **写 Python 脚本**：封装核心功能，统一以 JSON 格式输出，确保脚本可独立运行 2. **写 SKILL.md**：明确技能描述、执行流程、参数格式，约束 AI 行为（禁止冗余操作） 3. **注册到 openclaw.json**：将技能挂载到指定 Agent 的 skills 列表 4. **同步到工作区**：确保～/.openclaw/workspace/skills/ 下有最新的技能文件 5. **启动网关测试**：通过自然语言请求验证 AI 能正确匹配并调用技能，返回有效结果 **核心定位**：AI 在技能体系中扮演**调度员**角色，负责理解自然语言、匹配技能、拼装命令行参数、执行脚本并将 JSON 结果翻译成自然语言；**真正的业务逻辑（如量化计算）均在 Python 脚本中实现**。 ## 五、OpenClaw 的调用逻辑与技能匹配机制 ### 5.1 完整调用链路（以获取贵州茅台 K 线为例） Step1：用户发送消息 → Gateway（ws://127.0.0.1:18789），消息：`获取贵州茅台600519.SH最近3天日线` Step2：Gateway 将消息转发给指定 Agent（quant-analyst），并构建 System Prompt，包含： - 基础人设（IDENTITY.md、SOUL.md） - 工具列表（exec、read、write 等） - 技能摘要（所有挂载技能的 SKILL.md 描述字段）Step3：LLM 分析消息内容，匹配 akshare-kline 技能的 description 字段，决定调用 exec 工具，拼装命令： ``` python skills/akshare-kline/scripts/get_kline.py 600519.SH 1d 3 ``` Step4：exec 工具在 Agent 工作区（C:\\Users\\xxx.openclaw\\workspace）执行上述命令 Step5：get_kline.py 脚本执行完成，返回 JSON 格式 K 线数据，LLM 将 JSON 整理为自然语言，回复给用户 ### 5.2 技能匹配机制（核心） **关键结论**：技能匹配**不是简单的关键词匹配**，而是依赖 LLM 的自然语言理解能力，**description 字段是匹配的核心依据**。 1. Gateway 启动时，读取 Agent 配置的 skills 列表，加载每个技能的 SKILL.md 文件 2. 将每个 SKILL.md 的`description`字段提取并注入到 System Prompt 中，作为 LLM 的技能参考 3. 用户发送消息时，LLM 根据消息的语义和技能的 description，自主判断是否调用该技能 4. 若匹配成功，LLM 根据 SKILL.md 中的执行流程，调用对应的工具（如 exec）并拼装正确的命令行参数 5. 执行脚本并获取结果，LLM 整理后回复用户 **核心要点**：SKILL.md 的 description 字段需**简洁、明确、包含核心触发场景**，便于 LLM 准确匹配。 ### 5.3 技能开发常见问题梳理 | **问题** | **原因** | **解决方法** | | --- | --- | --- | | {baseDir} 占位符不生效 | OpenClaw 不支持 {baseDir} 占位符，早期版本兼容问题 | 改为工作区相对路径，如 skills/akshare-kline/scripts/get_kline.py | | AI 反复执行 pip install | AI 看到 requires.packages 后，自主执行安装操作 | 在 description 和正文中显式写：禁止 pip install、禁止检查环境 | | python3 在 Windows 上不存在 | Windows 默认只有 python 命令，无 python3 | 将 requires.bins 改为 \["python"\]，命令中使用 python 而非 python3 | | .env 文件不被 Gateway 加载 | 项目根目录的.env 未被加载，API Key 失效 | 将 API Key 直接写入 openclaw.json 的 apiKey 字段（不提交到 Git） | | 工作区与项目目录不同步 | 修改项目中技能文件后，未同步到 workspace | 执行同步命令：xcopy /E/Y "技能目录 \*" "workspace 技能目录" | | Backtrader 脚本找不到.env | exec 执行时工作目录为 workspace，无.env 文件 | 修改脚本的 load_env () 函数，从技能目录查找.env（如 skills/backtrader/.env） | ## 六、大厂的龙虾军团（OpenClaw 生态衍生产品） 各大厂商基于 OpenClaw 开源框架进行二次开发，推出了云端 / 端侧的 AI 智能体产品，核心保留 OpenClaw 的 Skills 体系，实现跨平台可移植性。 ### 6.1 核心衍生产品对比 | **产品名称** | **厂商** | **基础模型** | **部署方式** | **核心优势** | **当前状态** | | --- | --- | --- | --- | --- | --- | | Kimi Claw | 月之暗面 | Kimi K2.5 | 云端托管 | 一键部署、7×24 小时在线、5000 + 社区技能、跨平台接入 | Beta 测试 | | 小艺 Claw | 华为 | 华为大模型 | 端侧 + 云端 | 鸿蒙系统级集成、四大人设、隐私性好 | 内测中 | | 小米 Claw | 小米 | MiMo（自研） | 端侧 | 跨应用操作、系统级权限、自主执行复杂任务 | 封测中 | | MaxClaw | MiniMax | MiniMax 模型 | 云端 | 待定（对标 OpenClaw） | 开发中 | ### 6.2 代表产品：Kimi Claw（月之暗面） #### 6.2.1 核心特性 1. **一键云端部署**：无需本地服务器，浏览器即可创建，自动配置 Kimi K2.5 模型和联网能力 2. **7×24 小时在线**：云端守护进程运行，关闭浏览器后任务仍可执行（如定时任务） 3. **长期记忆**：持久化存储对话历史、用户偏好、任务记录，跨会话保持上下文 4. **ClawHub 技能库**：内置 5000 + 社区开源技能，支持一键安装和扩展 5. **定时任务**：支持设置周期性自动化任务（如每日股票新闻汇总、定时数据采集） 6. **跨平台接入**：可部署到飞书、企业微信、微博、Telegram 等社交 / 办公平台 7. **40GB 云存储**：提供文件存储和长期记忆空间，支持文件上传和处理 #### 6.2.2 与传统 VPS 的区别 Kimi Claw 是**基于 OpenClaw 的托管云服务**，并非传统虚拟主机，核心区别如下： | **特性** | **传统 VPS / 虚拟主机** | **Kimi Claw** | | --- | --- | --- | | 基础设施 | 用户自行购买、配置服务器 | Kimi 统一托管在云端，无需用户管理 | | 部署方式 | 手动安装、配置环境，需命令行操作 | 一键部署，可视化界面，无需命令行 | | 运维责任 | 用户负责维护、更新、安全防护 | Kimi 团队负责底层运维、更新、安全 | | 资源隔离 | 独立虚拟机 / 容器，资源独享 | 多租户共享集群资源，轻量级隔离 | | 访问方式 | SSH/RDP 远程登录，需专业知识 | Kimi 网页端对话界面，可视化操作 | #### 6.2.3 典型使用场景：定时股票新闻推送 1. 用户请求：`每天早上9点发送九安医疗的重要新闻` 2. AI 建议错峰时间（如 9:08），避免整点任务拥挤 3. 用户确认后，AI 创建 cron 定时任务，任务 ID 唯一标识 4. 到指定时间，AI 自动搜索九安医疗的新闻、公告、股价异动等信息 5. 将信息整理后推送到飞书 / 企业微信，实现自动化信息汇总 ### 6.3 OpenClaw 生态趋势总结 1. **部署形态分化**：云端派（Kimi Claw）主打零门槛、自动化；端侧派（华为 / 小米 Claw）主打系统集成、隐私性，满足不同场景需求 2. **行业标准升级**：OpenClaw 从开源框架逐步成为 AI 智能体的行业标准，各大厂商均基于其架构开发，保证生态兼容性 3. **Skills 跨平台可移植**：一次编写的 Skills 技能，可在所有基于 OpenClaw 的产品中复用，降低开发者成本 4. **开发方式灵活**：开发者可无缝切换**自建网关**（本地部署，高度定制）和**厂商托管**（云端部署，零运维）两种方案 ## 七、OpenClaw 工作空间详解 OpenClaw 的工作空间包含一系列核心配置文件，定义了 AI 的人格、身份、操作规则、记忆等，**所有文件均为 Markdown 格式**，加载顺序固定，是 AI 智能体的 “灵魂” 所在。 ### 7.1 核心文件及作用 | **文件名** | **核心作用** | **关键要点** | | --- | --- | --- | | SOUL.md | 定义 AI 的灵魂 / 人格 | 包含性格、语气、价值观、沟通风格；像气质而非操作手册；可自我修改 | | AGENTS.md | AI 的员工手册 | 定义工作流、决策框架、工具使用约定；宪法级别文件，只读（用户指示可追加）；包含红线禁止事项 | | IDENTITY.md | 定义 AI 的外在形象 | 包含姓名、头像、表情符号、物种概念；与 SOUL 分离（内在性格 vs 外在形象）；简洁（3-5 行） | | USER.md | 用户画像 | 告诉 AI 服务对象的信息；包含姓名、时区、职业、技术背景、沟通偏好；静态文件，不常变化 | | MEMORY.md | 长期记忆（蒸馏版） | 存储提炼后的用户偏好、项目上下文、过往决策；非原始日志，需定期整理；可自我修改 | | TOOLS.md | 工具使用备注 | 包含 API 端点、设备名称、文件路径等；只写 “在哪里”，不写 “怎么做”；环境特定配置 | | BOOTSTRAP.md | 首次引导（一次性） | 全新工作空间的初始化仪式；仅首次运行执行，完成后必须删除；定义初始化规则 | | HEARTBEAT.md | 定时任务清单 | 心跳巡检任务配置；定时任务运行时加载 | | memory/YYYY-MM-DD.md | 每日记忆日志 | 原始对话记录、决策过程；启动时自动加载今天和昨天的日志，其余按需搜索 | ### 7.2 核心文件编写示例 #### 7.2.1 SOUL.md（核心：人格定义） ``` - 回答先给结论，再补充细节，拒绝大段文字 - 语气直接、专业，不冒犯，避免口语化 - 遇到不确定的问题先尝试解决，再向用户提问 - 执行外部动作（发邮件、执行命令）前，必须先向用户确认 - 内部整理（总结、规划、数据清洗）可自主执行，无需确认 ``` #### 7.2.2 AGENTS.md（核心：操作规则） ``` ## 会话启动流程 1. 优先阅读SOUL.md —— 明确自身人格 2. 阅读USER.md —— 明确服务对象 3. 阅读memory/YYYY-MM-DD.md（今天和昨天）—— 加载近期记忆 4. 若为主会话，额外阅读MEMORY.md —— 加载长期记忆 ## 记忆规则 - 重要信息必须写入文件，不依赖临时记忆 - 当日决策、上下文 → 写入memory/YYYY-MM-DD.md - 长期用户偏好、项目核心信息 → 更新MEMORY.md - 记忆文件为只读，仅在用户明确指示下可追加/修改 ## 红线（禁止事项） - 永远不要外泄用户的私人数据、项目信息 - 执行破坏性命令（如rm、格式化）前，必须多次确认 - 优先使用trash命令（可恢复），替代rm命令（不可恢复） - 不随意安装第三方依赖，严格遵循SKILL.md的执行流程 ``` ### 7.3 工作空间加载顺序（固定） 1. 引导文件注入（按顺序）：SOUL.md → USER.md → IDENTITY.md → TOOLS.md → MEMORY.md 2. 自动加载**今天和昨天**的 memory/YYYY-MM-DD.md 每日日志 3. 若用户需要历史信息，按需搜索更早的每日日志 4. 加载完成后，开始与用户的对话 ### 7.4 工作空间使用注意事项 1. **Token 消耗控制**：所有核心文件每次会话都会注入 LLM 上下文，消耗 Token，需**保持文件简洁**，尤其是 MEMORY.md（避免冗余内容） 2. **文件大小限制**：默认单文件最大 20,000 字符，所有文件总计 150,000 字符，超限会被自动截断，影响 AI 理解 3. **子代理限制**：子代理会话仅注入 AGENTS.md 和 TOOLS.md，其余引导文件会被过滤，保证轻量级运行 4. **Kimi Claw 特殊性**：Kimi Claw 为托管版，用户无法直接编辑核心文件，但底层加载逻辑与开源 OpenClaw 完全一致 5. **记忆管理**：每日日志会持续积累，需定期整理 MEMORY.md，将有用信息提炼进去，删除无用的原始日志，减少 Token 消耗 ## 八、课程核心总结 1. **OpenClaw 核心定位**：基于 Node.js 开发的 AI 智能体框架，通过模块化的 Skills 体系实现 AI 的能力扩展，支持本地部署和云端托管，是连接通用大模型与专业业务场景的桥梁。 2. **安装配置核心**：前置依赖（Node.js、Git）的正确配置是基础，openclaw.json 的格式为核心（尤其是 models.providers 和 agents.list），技能必须同步到 Agent 工作区才能加载。 3. **Skills 体系核心**：Skills 是可移植的能力包，核心文件为 SKILL.md（description 字段是匹配关键），AI 仅作为调度员，实际业务逻辑由 Python 脚本实现，遵循 “脚本封装功能 + SKILL.md 定义规则 + 配置文件挂载” 的搭建原则。 4. **量化技能核心**：实现了 “数据获取（akshare-kline）→指标计算（talib）→策略回测（backtrader）” 的完整量化流程，每个技能独立，可组合使用，是自定义 Skills 的典型应用。 5. **生态趋势核心**：OpenClaw 已成为 AI 智能体的行业标准，大厂衍生产品分为云端和端侧，Skills 具备跨平台可移植性，开发者可根据需求选择自建网关或厂商托管方案。 6. **工作空间核心**：由一系列 Markdown 文件定义 AI 的人格、规则、记忆，加载顺序固定，需控制文件大小以减少 Token 消耗，是 AI 智能体个性化的关键。 **核心思考**：OpenClaw 的核心价值在于将通用大模型 “专业化”，通过 Skills 体系让非技术人员也能通过自然语言调用专业工具，未来如何进一步降低 Skills 的开发门槛，实现更广泛的生态扩展？