settings

设置技能

管理存储在 ~/.aibtc/config.json 中的配置。控制用于经过身份验证的 Stacks API 请求的 Hiro API 密钥、自定义 Stacks API 节点 URL，并提供版本信息。

用法

bun run settings/settings.ts <subcommand> [options]

子命令

set-hiro-api-key

将 Hiro API 密钥保存到 ~/.aibtc/config.json。与公开（未经身份验证）的请求相比，经过身份验证的请求具有更高的速率限制。

在 https://platform.hiro.so/ 获取免费的 API 密钥

bun run settings/settings.ts set-hiro-api-key --api-key <key>

选项：

• --api-key（必需）— 你的 Hiro API 密钥（敏感值）

输出：

{
  "success": true,
  "message": "Hiro API key saved. All subsequent Hiro API requests will use this key.",
  "maskedKey": "abcd...wxyz",
  "storedIn": "~/.aibtc/config.json"
}

get-hiro-api-key

检查是否已配置 Hiro API 密钥。显示密钥来源和遮蔽后的预览。

bun run settings/settings.ts get-hiro-api-key

输出（已配置密钥）：

{
  "configured": true,
  "source": "~/.aibtc/config.json",
  "maskedKey": "abcd...wxyz",
  "hint": "API key is active. Hiro API requests use authenticated rate limits."
}

输出（无密钥）：

{
  "configured": false,
  "source": "none",
  "maskedKey": "(not set)",
  "hint": "No API key configured. Using public rate limits. Get a key at https://platform.hiro.so/"
}

delete-hiro-api-key

从 ~/.aibtc/config.json 中移除已存储的 Hiro API 密钥。如果环境中设置了 HIRO_API_KEY，仍会将其用作备用值。

bun run settings/settings.ts delete-hiro-api-key

输出：

{
  "success": true,
  "message": "Hiro API key removed from ~/.aibtc/config.json.",
  "envFallbackActive": false,
  "hint": "No API key configured. Requests will use public rate limits."
}

set-stacks-api-url

将所有 Stacks API 请求指向自定义节点，而不是默认的 Hiro API。该 URL 必须提供与 api.hiro.so 相同的 /v2/ 和 /extended/v1/ 端点。

bun run settings/settings.ts set-stacks-api-url --url <url>

选项：

• --url（必需）— Stacks API 节点的基础 URL（例如，http://localhost:3999）

输出：

{
  "success": true,
  "message": "Custom Stacks API URL saved. All subsequent Stacks API requests will use this node.",
  "url": "http://localhost:3999",
  "storedIn": "~/.aibtc/config.json",
  "tip": "Use get-stacks-api-url to verify, or delete-stacks-api-url to revert to the default."
}

get-stacks-api-url

显示当前使用的 Stacks API URL，并指明它是自定义节点还是默认的 Hiro API。

bun run settings/settings.ts get-stacks-api-url

输出（自定义 URL）：

{
  "activeUrl": "http://localhost:3999",
  "isCustom": true,
  "source": "~/.aibtc/config.json",
  "defaultUrl": "https://api.testnet.hiro.so",
  "network": "testnet",
  "hint": "Using custom Stacks API node."
}

输出（默认）：

{
  "activeUrl": "https://api.testnet.hiro.so",
  "isCustom": false,
  "source": "default (Hiro API)",
  "defaultUrl": "https://api.testnet.hiro.so",
  "network": "testnet",
  "hint": "Using default Hiro API. Use set-stacks-api-url to point to your own node."
}

delete-stacks-api-url

移除自定义 Stacks API URL，并恢复为默认的 Hiro API（api.mainnet.hiro.so 或 api.testnet.hiro.so）。

bun run settings/settings.ts delete-stacks-api-url

输出：

{
  "success": true,
  "message": "Custom Stacks API URL removed. Reverted to default: https://api.testnet.hiro.so",
  "activeUrl": "https://api.testnet.hiro.so",
  "network": "testnet"
}

get-server-version

检查当前安装的软件包版本，并与 npm 上最新发布的版本进行比较。

bun run settings/settings.ts get-server-version

输出：

{
  "currentVersion": "0.1.0",
  "latestVersion": "0.1.0",
  "isLatest": true,
  "updateAvailable": false,
  "package": "@aibtc/skills"
}

check-relay-health

检查 x402 赞助中继的健康状况，以及链上赞助地址的 nonce 状态。报告中继可达性、版本、赞助方 nonce 缺口和内存池拥堵情况。

bun run settings/settings.ts check-relay-health [--relay-url <url>] [--sponsor-address <address>]

选项：

• --relay-url（可选）— 赞助中继的基础 URL（默认：https://sponsor.aibtc.dev）
• --sponsor-address（可选）— 中继赞助方的 STX 地址（默认：SP1PMPPVCMVW96FSWFV30KJQ4MNBMZ8MRWR3JWQ7）

输出（健康）：

{
  "healthy": true,
  "relay": {
    "url": "https://sponsor.aibtc.dev",
    "reachable": true,
    "status": "ok",
    "version": "1.0.0"
  },
  "sponsor": {
    "address": "SP1PMPPVCMVW96FSWFV30KJQ4MNBMZ8MRWR3JWQ7",
    "lastExecutedNonce": 732,
    "possibleNextNonce": 733,
    "lastMempoolNonce": null,
    "mempoolCount": 0,
    "missingNonces": []
  },
  "issues": [],
  "hint": "Relay and sponsor are operating normally."
}

输出（检测到问题）：

{
  "healthy": false,
  "relay": { "url": "https://sponsor.aibtc.dev", "reachable": false, "error": "fetch failed" },
  "sponsor": {
    "address": "SP1PMPPVCMVW96FSWFV30KJQ4MNBMZ8MRWR3JWQ7",
    "lastExecutedNonce": 732,
    "possibleNextNonce": 733,
    "lastMempoolNonce": null,
    "mempoolCount": 0,
    "missingNonces": [730]
  },
  "issues": [
    "Relay unreachable: fetch failed",
    "Nonce gaps detected: [730]. Transactions may be stuck. The sponsor may need to fill missing nonces."
  ],
  "hint": "Issues detected — see the issues array for details."
}

配置文件

所有设置都存储在 ~/.aibtc/config.json 中。任何钱包或设置子命令首次使用时都会自动创建此文件。

{
  "version": 1,
  "activeWalletId": null,
  "autoLockTimeout": 15,
  "hiroApiKey": "your-key-here",
  "stacksApiUrl": "http://localhost:3999"
}

环境变量备用值

• HIRO_API_KEY — 如果配置中未设置已存储的密钥，则使用此值
• NETWORK — 设置为 mainnet 或 testnet（默认：testnet）
• API_URL — 自定义 x402 中继 URL