openclaw-stock-skill

� 核心能力

本技能提供强大的股票数据查询与分析能力，主要包含：

1. 实时数据：提供实时股票快照、实时分时行情。
2. 历史数据：支持查询股票、可转债、ETF、指数等品种的历史数据（日线、分钟线、财务指标等）。
3. 自定义通知（开发中）：支持涨停、炸板、放量大涨、涨停大额成交等异动信号的自定义消息通知。

�📥 安装方法

npx skills add https://github.com/1018466411/openclaw-stock-data-skill

安装时按提示选择：

1. 选择 openclaw
2. 选择 global 应用于所有 Agent
3. Copy to all agents: yes

本技能教会代理如何使用你自建的股票数据服务（注册账号 https://data.diemeng.chat），通过 API Key 进行鉴权，查询股票的日线、分钟线、财务指标等数据。

⚙️ API Key 配置约定

• OpenClaw 会按照 skills.entries.<key> 配置 把 API Key 和自定义配置注入到进程环境变量中。
• 本技能约定使用环境变量 STOCK_API_KEY 作为主密钥，并在 metadata.openclaw.primaryEnv 中声明，以便通过 skills.entries.openclaw-stock-skill.apiKey 统一配置。
• 推荐的 OpenClaw 配置示例（~/.openclaw/openclaw.json）：

{
  skills: {
    entries: {
      "openclaw-stock-skill": {
        enabled: true,
        // 建议在 OpenClaw UI 的 Skill 参数面板里填写 apiKey，
        // Gateway 会自动将其写入 STOCK_API_KEY 环境变量
        apiKey: { source: "env", provider: "default", id: "STOCK_API_KEY" },
        env: {
          // 可在这里直接写死，或通过系统环境变量覆盖
          STOCK_API_KEY: "YOUR_REAL_STOCK_API_KEY"
        },
        config: {
          // 可选：覆盖默认域名
          baseUrl: "https://data.diemeng.chat"
        }
      }
    }
  }
}

参考文档：Skills Config、Skills

⚠️ 重要说明

1. 权限开通与 403 错误

如果 API 返回 403 错误，说明您的账号没有开通对应接口的权限。 请务必访问官网 https://data.diemeng.chat/，在个人中心开通所需权限（如股票行情、实时快照、可转债等）。

2. 接口类型区分

• 实时接口：
  • get_stock_snapshot_daily（不传日期或传今日）：获取最新实时快照（价格、成交量、五档盘口等）。
  • get_stock_snapshot_push_history：获取实时推送的历史记录。
  • get_call_auction：获取集合竞价数据。
• 历史接口：
  • get_daily_data：获取历史日 K 线。
  • get_history_data：获取历史分钟线。
  • get_finance_data：获取历史财务指标。
  • get_stock_snapshot_daily（传历史日期）：获取历史快照。
• 指数与板块接口：
  • get_index_history：获取指数分钟级历史数据。
  • get_ths_sector_categories：获取同花顺板块分类数据。
  • get_ths_constituent_stocks：获取同花顺成分股数据。

总体说明

• 基础域名：默认使用 https://data.diemeng.chat，如存在 skills.entries.openclaw-stock-skill.config.baseUrl 则优先使用配置中的 baseUrl。
• 鉴权方式：所有需要权限的接口都必须带上 API Key：
  • 首选 HTTP Header：apiKey: <STOCK_API_KEY>（推荐）
  • 兼容 Header：X-API-Key: <STOCK_API_KEY>
  • 后端也支持在 JSON body 中携带 apiKey 字段，但为了安全与规范，本技能统一通过 Header 传递。
• 返回结构：
  • 大多数接口返回：{ "code": 200, "msg": "成功", "data": { ... } }
  • 少数列表类接口直接返回数组或简单结构，实际响应以 JSON 为准。
• 限流与黑名单：
  • API Key 及 IP 都有严格限流与黑名单逻辑：
    • 无效 API Key 多次尝试会触发封禁（参见后端 DataAccessVerifier 实现）。
    • 需优先缓存和复用同一 API Key，不要在循环中频繁切换。
• ⚠️ 数据量限制：除特别说明外，大多数列表类接口单次请求最多返回 10000 条数据。如需获取更多数据，请使用分页参数。

能力概览（建议的工具意图）

代理应将本技能视作一组 HTTP 能力，而不是单一接口：

• get_stock_daily_bars：查询指定股票在某一时间区间内的日线 K 线数据。
• get_stock_intraday_bars：查询分钟级（1/5/15/30/60 分钟）历史数据。
• get_stock_finance_factors：查询日度财务因子（PE、PB、换手率等）。
• get_stock_list：查询股票基础信息列表，用于代码／名称搜索。
• get_stock_calendar_and_snapshot：查询交易日历和当日快照。
• get_stock_search：使用自然语言条件搜索符合条件的股票（如"PE<20 且换手率>3%"）。
• get_stock_call_auction：查询集合竞价数据。
• get_stock_closing_snapshot：查询收盘快照数据。
• get_stock_snapshot_daily：查询实时或历史股票快照（含 Redis 缓存加速）。
• get_stock_suspension：查询股票停牌信息。
• get_stock_adj_factor：查询复权因子。
• get_bond_daily：查询可转债日线数据。
• get_bond_indicator_daily：查询可转债日指标数据。
• get_bond_list：查询可转债列表信息。

代理在规划调用时，应根据用户自然语言意图，选择以上能力并组合使用。

接口详情与调用规范

1. 日线数据：POST /api/stock/daily

• URL：{baseUrl}/api/stock/daily
• 方法：POST
• Headers：
  • Content-Type: application/json
  • apiKey: <STOCK_API_KEY>
• 请求体 JSON（后端 DailyDataRequest）：

{
  "stock_code": "000001.SZ",
  "start_time": "2024-01-01",
  "end_time": "2024-01-31",
  "page": 0,
  "page_size": 1000
}

• 说明：
  • stock_code 可以是单个字符串，也可以是字符串数组。
  • start_time、end_time 格式为 YYYY-MM-DD。
  • 支持分页，page 从 0 开始。
• 响应字段：
  • data.total：总记录数
  • data.list：每条记录包含 stock_code, stock_name, trade_date, open, high, low, close, vol, amount 等字段，价格与成交量已在后端统一保留 2 位小数。
• 响应主体（简化）：
  • data.total：总记录数
  • data.list：每条记录包含 stock_code, trade_date, open, high, low, close, vol, amount 等字段，价格与成交量已在后端统一保留 2 位小数。

代理在需要“某股某段时间的日 K 线”时，应优先选择该接口。

2. 分钟级历史数据：POST /api/stock/history

• URL：{baseUrl}/api/stock/history
• 方法：POST
• Headers：同上
• 请求体 JSON（后端 HistoryDataRequest）：

{
  "stock_code": "000001.SZ",
  "level": "5min",
  "start_time": "2024-01-01 09:30:00",
  "end_time": "2024-01-01 15:00:00",
  "page": 0,
  "page_size": 1000
}

• 字段说明：
  • level："1min" | "5min" | "15min" | "30min" | "60min"
  • start_time / end_time：
    • 允许仅日期（自动补全 00:00:00 和 23:59:59）
    • 或完整时间戳 YYYY-MM-DD HH:MM:SS
• 响应主体（简化）：
  • data.list 中每条包含：stock_code, trade_time, open, high, low, close, vol, amount。

用于用户询问“某天/某段时间内的分钟级行情、分时数据”等场景。

3. 当天分时数据：POST /api/realtime/history

• URL：{baseUrl}/api/realtime/history
• 方法：POST
• Headers：同上
• 请求体 JSON：

{
  "stock_code": "000001.SZ",
  "trade_time": "2026-03-15 09:31:00"
}

• 说明：
  • 获取当天分时数据 (实时 1 分钟级别分时数据)，支持全市场或指定股票。
  • stock_code 或 trade_time 至少提供一个。
  • 返回数据会根据 stock_code + trade_time 进行去重。

调用建议（定时任务拉取全市场数据）：

• 建议使用时间 (trade_time) 来获取实时分时，一次可以获取某一分钟的全市场数据。
• 使用定时任务来获取数据，每分钟获取上一分钟的数据。
• 建议在每分钟的 2 到 5 秒后开始获取。
• 如果获取不到，建议暂停 1 秒后继续获取，最多重试不要超过 60 次，避免陷入死循环。
• 建议在每分钟 15 秒之后再调用接口更新一次数据，确保数据的准确性。

4. 财务与因子（行情因子）：POST /api/stock/finance

• URL：{baseUrl}/api/stock/finance
• 方法：POST
• 请求体 JSON（后端 FinanceDataRequest）：

{
  "stock_code": "000001.SZ",
  "start_time": "2024-01-01",
  "end_time": "2024-03-31",
  "page": 0,
  "page_size": 1000
}

• 主要返回字段（列表中每条）：
  • stock_code, stock_name, trade_date, close, turnover_rate, turnover_rate_f, volume_ratio, pe, pe_ttm, pb, ps, ps_ttm, dv_ratio, dv_ttm, total_share, float_share, free_share, total_mv, circ_mv 等。

适合估值分析、换手率、成交金额、市值等相关问题。

4. 股票基础信息列表：GET /api/stock/list

• URL：{baseUrl}/api/stock/list
• 方法：GET
• Query 参数：
  • stock_code（可选）：精确股票代码筛选
  • page：默认 0
  • page_size：默认 20000
• 响应（封装在统一 success 结构中）：
  • data.total
  • data.list：包含 stock_code, name, area, industry, list_date, symbol, list_status, delist_date, is_hs 等。

当用户只给出股票名称、地区、行业等描述时，可先通过该接口获取匹配列表，再提示用户选择具体代码。

5. 交易日历与快照：GET /api/basic/calendar & GET /api/basic/snapshot

5.1 交易日历：GET /api/basic/calendar

• URL：{baseUrl}/api/basic/calendar
• 方法：GET
• Query 参数：
  • start_time: YYYY-MM-DD
  • end_time: YYYY-MM-DD
• 响应：
  • data 为数组，每条含 date, is_open（1 为交易日，0 为休市）。

当用户问“某段时间哪些是交易日”“下一个交易日是什么时候”等，可使用此接口。

5.2 快照：GET /api/basic/snapshot

• URL：{baseUrl}/api/basic/snapshot
• 方法：GET
• Query 参数：
  • stock_code（可选）
  • page, page_size
• 返回最新一笔集合竞价数据的汇总，字段包括价格、成交量、买卖盘等。

当用户需要“当前（最近一次）盘口快照”或大盘扫描时，可使用此接口。

6. 股票条件搜索：POST /api/stock/search

• URL：{baseUrl}/api/stock/search
• 方法：POST
• Headers：
  • Content-Type: application/json
  • apiKey: <STOCK_API_KEY>
• 请求体 JSON：

{
  "query": "pe_ttm < 20 且 turnover_rate > 3%",
  "stock_code": "000001.SZ",
  "date": "2024-01-01",
  "page": 0,
  "page_size": 100,
  "sort_by": "pe_ttm",
  "sort_order": "asc"
}

• 字段说明：

  • query（必填）：搜索条件，支持自然语言或表达式
    • 支持格式：pe_ttm < 20、turnover_rate > 3%、pe_ttm < 20 且 turnover_rate > 3%
    • 支持中文：市盈率小于20、换手率大于3%
    • 支持单位：circ_mv > 100亿、volume > 1000万
  • stock_code（可选）：精确股票代码筛选
  • date（可选）：日期，格式 YYYY-MM-DD 或 MM-DD（默认为当年）
    • 不提供日期：查询 stock_snapshot_daily（最新实时数据）
    • 提供日期：查询 stock_finance_daily（历史财务数据）
  • page：页码，从 0 开始
  • page_size：每页数量，最大 1000
  • sort_by（可选）：排序字段，如 pe_ttm、turnover_rate
  • sort_order（可选）：排序方向 asc 或 desc（默认 desc）

• 支持的字段：

  • price / close：股价/收盘价
  • pct_chg：涨跌幅
  • turnover_rate：换手率
  • pe / pe_ttm：市盈率
  • pb：市净率
  • total_mv / circ_mv：总市值/流通市值
  • total_share / float_share：总股本/流通股本
  • volume / turnover：成交量/成交额
  • dividend_ratio：股息率

• 响应主体：

  • data.total：总记录数
  • data.list：符合条件的股票列表

重要提醒：该接口单次请求最多返回 1000 条数据。如需获取更多结果，请使用分页功能。

适用场景：用户需要根据财务指标筛选股票，如"帮我找出 PE<20 的股票"、"换手率大于 5% 的股票有哪些"。

8. 集合竞价数据：POST /api/stock/call_auction

• URL：{baseUrl}/api/stock/call_auction
• 方法：POST
• Headers：apiKey: <STOCK_API_KEY>
• 请求体 JSON：

{
  "stock_code": "000001.SZ",
  "start_time": "2024-01-01 09:15:00",
  "end_time": "2024-01-01 09:25:00",
  "page": 0,
  "page_size": 100
}

• 字段说明：
  • start_time / end_time：时间范围，支持仅日期（自动补全时间）
  • page_size：最大 10000
• 返回字段：stock_code, name, trade_time, close, open, high, low, pre_close, vol, amount, turnover_rate, pe, pb, pe_ttm, dv_ttm 等

重要提醒：单次请求最多返回 10000 条数据。

9. 收盘快照数据：POST /api/stock/closing_snapshot

• URL：{baseUrl}/api/stock/closing_snapshot
• 方法：POST
• Headers：apiKey: <STOCK_API_KEY>
• 请求体 JSON：