@huaxiaomiao/js-sdk

花小喵服务端 JavaScript SDK。当前版本用于 OpenClaw 调用花小喵开放接口：

• 运行前权益预检：确认本次 OpenClaw 运行是否允许继续。
• 运行结束通知：通知花小喵尽快同步 AI 网关调用日志。
• 自动处理签名请求头、JSON 序列化、Nonce、Timestamp、Body-SHA256 和 HTTP 错误。

不要在浏览器中使用本 SDK。SDK 需要 App Secret，Secret 只能存在于 OpenClaw 服务端运行环境。

安装

仓库内本地安装：

npm install ./sdk/js-sdk

如果你拿到的是打包文件：

npm install ./huaxiaomiao-js-sdk-0.1.0.tgz

快速开始

import { HuaxiaomiaoClient } from "@huaxiaomiao/js-sdk";

const hxm = new HuaxiaomiaoClient({
  baseUrl: openclawConfig.huaxiaomiao.open_interface.base_url,
  appId: openclawConfig.huaxiaomiao.open_interface.app_id,
  secret: openclawConfig.huaxiaomiao.open_interface.secret,
});

SDK 不读取 OpenClaw 配置文件，也不读取环境变量。OpenClaw 初始化流程负责把 secret、user_id、assistant_instance_id 等信息写入配置；调用方先读取配置，再传给 SDK。

baseUrl 可以带路径前缀，例如 https://api.example.com/platform。SDK 会使用最终请求 URL 的 path + query 参与签名，避免签名路径和实际请求路径不一致。baseUrl 不能带 query 或 fragment。

运行前预检

在 OpenClaw before_agent_run hook 中调用：

const result = await hxm.runtime.preflight({
  assistant_instance_id: openclawConfig.huaxiaomiao.assistant_instance.id,
  openclaw_run_id: ctx.runId,
  trigger: "user_message",
  user_id: openclawConfig.huaxiaomiao.user_id,
  diagnostics: {
    openclaw_session_id: ctx.sessionId,
    openclaw_session_key: ctx.sessionKey,
    openclaw_job_id: ctx.jobId,
  },
}, {
  timeoutMs: 3000,
});

if (result.data.code !== "OK" || result.data.data.allow !== true) {
  const message = result.data.data?.user_message || "服务校验未通过";
  throw new Error(message);
}

SDK 会请求：

POST /openapi/runtime/v1/runs/preflight

运行结束通知

在 OpenClaw agent_end hook 中调用：

await hxm.runtime.finished({
  assistant_instance_id: openclawConfig.huaxiaomiao.assistant_instance.id,
  openclaw_run_id: ctx.runId,
  status: "success",
  finished_at: new Date().toISOString(),
  user_id: openclawConfig.huaxiaomiao.user_id,
  trigger: "user_message",
  duration_ms: durationMs,
  diagnostics: {
    openclaw_session_id: ctx.sessionId,
    openclaw_session_key: ctx.sessionKey,
    openclaw_job_id: ctx.jobId,
  },
}, {
  timeoutMs: 3000,
});

SDK 会请求：

POST /openapi/runtime/v1/runs/finished

错误处理

import {
  HuaxiaomiaoHttpError,
  HuaxiaomiaoNetworkError,
} from "@huaxiaomiao/js-sdk";

try {
  await hxm.runtime.preflight(params);
} catch (error) {
  if (error instanceof HuaxiaomiaoHttpError) {
    console.error(error.status, error.code, error.requestId);
  } else if (error instanceof HuaxiaomiaoNetworkError) {
    console.error(error.message);
  } else {
    throw error;
  }
}

SDK 不自动重试。OpenClaw hook 应按接口文档决定是否重试。

timeoutMs 会在请求超时时主动 abort，并抛出 HuaxiaomiaoNetworkError。如果调用方已有 AbortController，也可以传入 signal：

await hxm.runtime.preflight(params, {
  signal: controller.signal,
  timeoutMs: 3000,
});

自定义请求

未来新增开放接口时，可以使用底层请求方法：

await hxm.post("/openapi/runtime/v1/example", {
  target_id: "demo_target_001",
  event: "example",
});

post() 会执行一次 JSON.stringify()，用同一份字符串计算 Body-SHA256 和签名，并发送同一份字符串。

生成签名字符串

createSignStr() 是公开工具方法，用于排障、自定义 HTTP 客户端或离线验算。它只生成签名相关数据，不发送 HTTP 请求。

import { createSignStr } from "@huaxiaomiao/js-sdk";

const result = createSignStr({
  method: "POST",
  path: "/openapi/runtime/v1/example",
  body: '{"target_id":"demo_target_001","event":"example"}',
  appId: "hxm_app_test_001",
  secret: "hxm_test_secret_123",
  timestamp: "1780567200",
  nonce: "018f6c9c-2a7a-7a65-9d2c-8a6a3b0e7a11",
});

console.log(result.bodySha256);
// 0df339e0b2f55972945fdc59ac3182c537a258c16f39da4f8cf58a6164e2eb7b

console.log(result.signature);
// bc1be213b56107ccbe0473d5eaa315c03466ad2850e1ab6114d0d83fdba8525c

上面打印完整 signature 只适用于这组固定离线测试向量。真实请求排障时不要记录完整 signature 或完整 signStr，只记录 request_id、endpoint、body hash 前缀等脱敏信息。

result.signStr 是实际参与 HMAC 的 5 行字符串：

POST
/openapi/runtime/v1/example
1780567200
018f6c9c-2a7a-7a65-9d2c-8a6a3b0e7a11
0df339e0b2f55972945fdc59ac3182c537a258c16f39da4f8cf58a6164e2eb7b

返回值：

{
  signStr,
  body,
  bodySha256,
  signature,
  headers
}

headers 可直接用于 HTTP 请求：

{
  "App-Id": "...",
  "Timestamp": "...",
  "Nonce": "...",
  "Body-SHA256": "...",
  "Signature": "...",
  "Signature-Version": "v1"
}

打包交付

本 SDK 是纯 Node.js ESM，不需要 webpack、Rollup 或 esbuild 打 bundle。给其他项目使用时，生成 npm tarball 即可：

cd sdk/js-sdk
npm test
npm pack

生成文件：

huaxiaomiao-js-sdk-0.1.0.tgz

npm pack 会自动先执行 npm test。

安全注意事项

生产日志不得记录：

• App Secret
• AI 网关令牌
• 完整 prompt
• 用户上传文件正文
• 完整 signStr
• 完整 Signature