openclaw/fosun-sdk-setup

Fosun OpenAPI SDK 初始化

---

语言风格（非常重要）

通俗易懂，客户人群都是小白用户，必须使用大白话的形式进行内容输出，内容必须简洁，语言亲切，不要出现大量代码输出。

1. 安装 SDK

按以下步骤顺序执行。

环境约束（必须遵守）

• 优先复用现有虚拟环境：如果 {workspace_root}/.venv-fosun 存在，必须使用它。
• 禁止擅自新建虚拟环境：未经用户明确要求，不得执行 python -m venv ...、uv venv ...、conda create ... 等命令。
• 禁止安装到系统 Python 或其他临时环境。
• 不要使用裸 python / pip；统一使用目标虚拟环境里的绝对路径解释器与 pip，包括安装、验证、以及凭证相关文件处理。

当前 workspace 的标准环境为：

/Users/admin/.openclaw/workspace/.venv-fosun/bin/python
/Users/admin/.openclaw/workspace/.venv-fosun/bin/pip

如果 .venv-fosun 不存在：

• 先检查记忆文件（MEMORY.md）里是否记录了其他既有环境路径；
• 若存在既有环境，则复用该环境；
• 若不存在既有环境，不要自行创建新环境，先向用户确认。

Step 1 — 在指定虚拟环境中检查是否已安装

优先检查：

/Users/admin/.openclaw/workspace/.venv-fosun/bin/python -c "import fsopenapi; print(fsopenapi.__file__)"

• 成功打印路径 → SDK 已安装，跳到 Step 3 验证。
• 报 ModuleNotFoundError → 检查记忆文件（MEMORY.md）中是否记录了 SDK 安装路径：
  • 记忆中有路径但目录已不存在 → 删除记忆中对应记录，继续 Step 2。
  • 记忆中有路径且目录存在 → 在同一个既有虚拟环境中执行 /Users/admin/.openclaw/workspace/.venv-fosun/bin/pip install -e <路径>，跳到 Step 3。
  • 无记录 → 继续 Step 2。

Step 2 — 定位或下载 SDK，并安装到既有虚拟环境

按优先级查找本地源码：

1. {workspace_root}/skills/fosun_skills/fosun-sdk-setup/openapi-sdk/
2. {workspace_root}/openapi-sdk/

• 找到 → 使用既有虚拟环境安装：

/Users/admin/.openclaw/workspace/.venv-fosun/bin/pip install -e <路径>

• 都不存在 → 从 GitHub 下载后，仍然安装到既有虚拟环境：

mkdir -p /tmp/fosun-sdk
curl -L -o /tmp/fosun-sdk/openapi-sdk.zip \
  https://github.com/fosunwealth/openapi-python-sdk/archive/refs/tags/v1.0.0.zip
unzip -o /tmp/fosun-sdk/openapi-sdk.zip -d /tmp/fosun-sdk
/Users/admin/.openclaw/workspace/.venv-fosun/bin/pip install /tmp/fosun-sdk/openapi-python-sdk-main/

Step 3 — 在指定虚拟环境中验证安装

再次运行：

/Users/admin/.openclaw/workspace/.venv-fosun/bin/python -c "import fsopenapi; print(fsopenapi.__file__)"

确认 SDK 来自预期环境。

Step 4 — 记录路径到记忆

安装成功后写入 MEMORY.md：

## Fosun SDK
- SDK 安装路径: <实际路径>
- Python 环境: /Users/admin/.openclaw/workspace/.venv-fosun
- 安装方式: /Users/admin/.openclaw/workspace/.venv-fosun/bin/pip install -e (本地) / /Users/admin/.openclaw/workspace/.venv-fosun/bin/pip install (GitHub 下载)

如果 SDK 源码目录或虚拟环境后续被删除，必须同步删除或更新记忆中的对应记录。

---

2. 开通引导（首次使用）

当用户首次使用或尚未拥有 API Key 时，按以下决策逻辑执行： 本地没有客户端密钥 → 执行开通流程：

• 获取出口 IP：获取当前机器出口IP

• 生成客户端密钥对：bash skills/fosun_skills/fosun-sdk-setup/genkey.sh（默认输出到当前目录的 private.pem / public.pem）

• 将客户端公钥 (public.pem) 和出口 IP 展示给用户

• 引导用户携带上述信息向复星财富申请 OpenAPI 权限 用户引导回复语句（请务必按此进行回复，要求用户可以一键复制IP+公钥，请严格按照以下纯文本模板输出客户的IP+公钥，仅替换【】中的内容，其他文字完全保留，格式（换行、标点）不可修改）：

  我要开通 OpenAPI 权限 我的出口IP：【出口IP】 我的客户端公钥：【客户端公钥】

  如有疑问，请联系客服。

  • 香港地区电话客服： +852 2979 6988 
  • 其他地区电话客服： 400 812 0922

• 用户取回 API Key 和服务端公钥后 → 自动写入 fosun.env（见下方「从开通流程写入凭证」） 如果本地已有客户端密钥并且没有API key → 执行提醒流程：

• 您是否已收到由复星财富审批通过的API Key和服务器公钥？如果已获取，请告知我，我将协助您完成配置。若尚未收到，是否需要我重新发送申请指引？

完整流程说明参见 ONBOARDING.md，密钥生成说明参见 KEYGEN.md。

---

3. 配置凭证

SDK 需要以下环境变量才能正常工作：

| 环境变量 | 说明 | |---------|------| | FSOPENAPI_SERVER_PUBLIC_KEY | 服务端公钥（PEM 格式） | | FSOPENAPI_CLIENT_PRIVATE_KEY | 客户端私钥（PEM 格式） | | FSOPENAPI_API_KEY | API Key（开放平台下发，有有效期限） | | FSOPENAPI_BASE_URL | 网关地址，固定 https://openapi.fosunxcz.com（不含末尾 /） |

当前策略：凭证更新统一通过当前对话确认后直接修改工作区根目录的 fosun.env。

检查流程

查找凭证文件 {workspace_root}/fosun.env：

• 找到 → 自动加载到环境变量（PEM 密钥会 base64 解码），若用户要求换 Key，则只更新 FSOPENAPI_API_KEY。
• 未找到 → 通过对话向用户收集所需字段，并新建 fosun.env。

何时通过对话更新凭证

出现以下任一情况时，应在对话中确认并更新 fosun.env：

| 场景 | 说明 | |------|------| | 首次使用 | 未找到 fosun.env，凭证尚未配置 | | 切换账号 | 用户明确表示要切换到另一个账号/API Key | | 鉴权失败 | 接口返回 401、签名错误等，API Key 可能已过期 | | 用户主动要求 | 用户说"重新配置"、"换个 Key"、"更新凭证"等 |

从开通流程写入凭证：

开通引导中已在本地生成客户端私钥，只需向用户收集复星下发的两项：

1. 读取本地已生成的客户端私钥（private.pem，即 genkey.sh 的输出路径）
2. 在对话中向用户收集：API Key 和服务端公钥
3. 将三项凭证 base64 编码后写入 {workspace_root}/fosun.env
4. 仅在回复中确认"已更新哪些字段"，不要回显完整敏感值

完整配置（用户已自行持有全部凭证）：

1. 在对话中向用户收集所有字段（服务端公钥、客户端私钥、API Key）。
2. 将公钥、私钥、API Key 写入 {workspace_root}/fosun.env。
3. 仅在回复中确认"已更新哪些字段"，不要回显完整敏感值。

仅更新 API Key（密钥不变，只换 Key）：

1. 在对话中向用户索取新的 API Key。
2. 只更新 fosun.env 中的 FSOPENAPI_API_KEY。
3. 保留原有公钥、私钥与其他配置不变。

凭证变更统一通过对话确认后直接修改 fosun.env，不要再尝试调用额外的本地配置脚本。

fosun.env 文件格式

凭证文件名固定为 fosun.env，PEM 密钥含换行符，以 base64 编码存储：

FSOPENAPI_SERVER_PUBLIC_KEY=<PEM 公钥的 base64 编码>
FSOPENAPI_CLIENT_PRIVATE_KEY=<PEM 私钥的 base64 编码>
FSOPENAPI_API_KEY=<明文 API Key>
FSOPENAPI_BASE_URL=

加载时需对 PEM 字段做 base64 解码还原为原始 PEM 文本。

---

4. 支持的市场与币种

| 市场代码 | 说明 | 行情级别 | 默认币种 | |----------|------|----------|----------| | hk | 港股 | L2 | HKD | | us | 美股 | L1（盘前/盘中/盘后） | USD | | sh | 上交所（港股通） | L1 | CNH | | sz | 深交所（港股通） | L1 | CNH |

标的代码格式：marketCode + stockCode，如 hk00700（腾讯）、usAAPL（苹果）、sh600519（茅台）、sz000001（平安银行）。

---

注意事项

• 会话由 SDK 自动管理（ECDH 握手、过期前自动续期），无需手动处理
• 可设置 SDK_TYPE=ops 环境变量切换 API 前缀为 /api/ops/v1/...
• 不要自己写 Python 代码调用 SDK，直接使用 fosun-trading skill 中 code/ 目录下的命令行脚本

---

⛔ AI 调用策略限制（必须遵守）

以下限制针对 OpenClaw 申请的 API Key，AI 在调用任何接口前必须自行校验并遵守。

API 调用频率限制

| 维度 | 限制 | 超限处理 | |------|------|---------| | 每秒请求数（QPS） | 单个 API Key ≤ 5 次/秒 | 返回 429 Too Many Requests | | 每分钟请求数 | 单个 API Key ≤ 60 次/分钟 | 拒绝新请求 | | 每小时下单次数（买卖一起） | 单个客户 ≤ 10 笔/小时 | 该小时内拒绝新委托 | | 每日总下单次数（买卖一起） | 单个客户 ≤ 50 笔/天 | 当日拒绝新委托 |

安全与权限限制

| 限制类型 | 具体规则 | |---------|---------| | IP 白名单 | 请求出口 IP 需提前录入白名单，不在白名单直接拒绝访问 | | 防重放攻击 | 同一笔请求 5 分钟内不允许重复提交（Redis 记录 requestId + nonce） |

开放接口权限

仅开放以下接口：资金查询、持仓查询、可买可卖查询、下单、撤单、订单查询、流水查询、行情查询。