openclaw-stock-skill

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

> ⚙️ **API Key 配置约定**
>
> - OpenClaw 会按照 [`skills.entries.<key>` 配置](https://docs.openclaw.ai/tools/skills-config) 把 API Key 和自定义配置注入到进程环境变量中。
> - 本技能约定使用环境变量 **`STOCK_API_KEY`** 作为主密钥，并在 `metadata.openclaw.primaryEnv` 中声明，以便通过 `skills.entries.openclaw-stock-skill.apiKey` 统一配置。
> - 推荐的 OpenClaw 配置示例（`~/.openclaw/openclaw.json`）：
>
> ```json5
> {
>   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](https://docs.openclaw.ai/tools/skills-config)、[Skills](https://docs.openclaw.ai/tools/skills)

## 总体说明

- **基础域名**：默认使用 `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 多次尝试会触发封禁（参见后...

# 股票数据 API Skill for OpenClaw

这是一个为 OpenClaw 等 Agent 工具设计的股票数据 Skill，提供了 A 股市场及周边资产的完整数据访问能力。

## 📋 数据分类概览

1. **股票历史数据**  
   - 日 K 线（前复权/不复权）、分钟级历史、日度财务因子、估值、复权因子、历史快照等  
   - 典型函数：`get_daily_data`、`get_history_data`、`get_finance_data`、`get_daily_adj_data`、`get_adj_factor`、`get_stock_snapshot_daily` 等

2. **股票实时数据**  
   - 集合竞价、基础快照、推送快照历史、停牌信息等  
   - 典型函数：`get_call_auction`、`get_basic_snapshot`、`get_stock_snapshot_push_history`、`get_stock_suspension` 等

3. **可转债历史和实时数据**  
   - 可转债日线、分钟级行情、日度指标（纯债价值、转股溢价等）、收盘快照、基础列表等  
   - 典型函数：`get_bond_daily`、`get_bond_history`、`get_bond_indicator_daily`、`get_bond_closing_snapshot`、`get_bond_list` 等

4. **ETF 数据**  
   - ETF 日线与分钟级历史行情  
   - 典型函数：`get_etf_daily`、`get_etf_history`

5. **指数历史数据**  
   - 指数分钟级历史行情（支持多种时间粒度）  
   - 典型函数：`get_index_history`

> 此外还提供 **条件搜索等高级能力**，详见 `stock_api.py` 与 `skill.json`。

## 🚀 快速开始

### 1. 注册账号并开通接口权限

**重要：使用本 Skill 前，必须先注册账号并为需要使用的接口开通对应权限。**

1. 访问 [https://data.diemeng.chat/](https://data.diemeng.chat/)
2. 注册新账号或登录现有账号
3. 在 **个人中心 / 权限或套餐管理** 中，按需开通以下数据大类的访问权限：
   - 股票历史数据（行情、财务、估值等）
   - 股票实时数据（集合竞价、基础快照等）
   - 可转债数据（历史 & 实时）
   - ETF 数据
   - 指数历史数据
4. 在 **API 管理** 中创建并复制您的 **API Key**

> 如果未为某一类接口开通权限，即使配置了 API Key，也会收到 403 或权限不足的错误。

### 2. 在 Skill 页面配置 API Key（推荐）

在 OpenClaw / ClawHub 中启用本 Skill 时：

1. 打开 `openclaw-stock-skill` 的 Skill 配置页面
2. 在参数面板中将从 `data.diemeng.chat` 获取的 **API Key** 填入对应字段（通常是 `apiKey` 或 `STOCK_API_KEY`）
3. 保存后...