> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaleidoswap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 工具：快速上手

> 把 AI 代理接入比特币：从测试网络上的第一次只读工具调用，到验证过一笔报价之后再开启真实执行。

这是从「装好工具」到「验证一笔交换」的完整路径。顺序是先只读，再报价，最后执行 —— 因为除第一步之外，每一步都会动用真实价值。

## 开始之前

| 要求                    | 说明                                                                   |
| --------------------- | -------------------------------------------------------------------- |
| **一个测试网络**            | regtest 或 signet。首次运行绝不要用主网                                          |
| **一份钱包种子**            | 用于测试网络的一次性 BIP-39 助记词，设置到 `WDK_SEED`                                 |
| **一个节点**              | 仅 `wdk_*` 工具和原子交换需要。Spark 工具只需要种子，行情数据什么都不需要                         |
| **一个 MCP 宿主或 LLM 密钥** | Claude Desktop 或其他 MCP 客户端，或者用于 KaleidoAgent 的 Anthropic / OpenAI 密钥 |

如果你还没有安装任何组件，请先看[安装](/cn/ai-tools/installation)。

<h2 id="pick-a-surface">
  选择接入方式
</h2>

| 如果你想                                 | 从这里开始                                      |
| ------------------------------------ | ------------------------------------------ |
| 给 Claude Desktop 或自己的 MCP 客户端加上比特币工具 | [MCP 服务器](/cn/ai-tools/mcp-servers)        |
| 让代理无人值守地管理一个投资组合                     | [KaleidoAgent](/cn/ai-tools/kaleido-agent) |
| 在本地端通过聊天或语音操作钱包                      | [KaleidoMind](/cn/ai-tools/kaleido-mind)   |
| 不改代码就调整代理行为                          | [Skills](/cn/ai-tools/skills)              |

## 首次运行：MCP 服务器

<Steps>
  <Step title="把网关添加到宿主客户端">
    把 `kaleido-mcp` 配置块加入你的 MCP 宿主配置，将 `KALEIDOSWAP_API_URL` 指向测试环境，并把 `SPARK_NETWORK` 设为 `REGTEST`。完整 JSON 见 [MCP 服务器页面](/cn/ai-tools/mcp-servers#client-configuration)。
  </Step>

  <Step title="重启宿主客户端">
    MCP 宿主只在启动时读取配置。已经在运行的客户端不会自动识别新服务器，必须重启。
  </Step>

  <Step title="调用一个只读工具">
    先从不会动用资金的操作开始。请求行情数据，它既不需要种子也不需要节点：

    ```
    What is the current Bitcoin price and the Fear and Greed index?
    ```

    这会触发 `l402_get_price` 和 `l402_get_sentiment`。只要有回答，连接就是通的。
  </Step>

  <Step title="确认钱包已接好">
    接着确认钱包工具能正常解析：

    ```
    Show me my Spark balance and my Spark address.
    ```

    这会调用 `spark_get_balance` 和 `spark_get_address`。这一步报错说明是种子或网络问题，而不是连接问题。
  </Step>

  <Step title="交易前先报价">
    只询价，不下单：

    ```
    Quote 100000 sats of BTC into USDT. Do not place an order.
    ```

    `kaleidoswap_get_quote` 会返回一个 `rfq_id`、原始数量、费用和过期时间。请仔细核对原始数量：它们以资产的最小单位计价，不是显示单位。
  </Step>

  <Step title="报价确认无误后再执行">
    一笔原子交换需要 DEX 工具和钱包工具配合，并且节点必须在通道中持有该资产。[跨服务器调用顺序](/cn/ai-tools/mcp-servers#atomic-swap-across-servers)按顺序列出了每一次调用。
  </Step>
</Steps>

## 首次运行：KaleidoAgent

<Steps>
  <Step title="保持 dry run 开启">
    `agent.config.json` 中的 `portfolio.dry_run` 默认为 `true`。先别动它。代理会完成推理、决策并汇报一笔交易，但不会真正提交。
  </Step>

  <Step title="启动代理">
    ```bash theme={null}
    npm start
    ```

    这会同时启动代理和监听 `http://localhost:4242` 的状态 API。若要使用仪表盘，另外运行 `npm run dev:webapp` 并打开 `http://localhost:5173`。
  </Step>

  <Step title="手动触发一轮循环">
    不必等定时任务，可以直接让状态 API 跑一轮：

    ```bash theme={null}
    curl -X POST http://localhost:4242/run \
      -H 'Content-Type: application/json' \
      -d '{"task_id":"rebalance"}'
    ```

    然后读取 `GET /status`，查看它的决策、它看到的余额，以及 token 开销。
  </Step>

  <Step title="检查风险上限">
    确认 `max_swap_usd`、`min_btc_reserve_sats` 和 `stop_loss_btc_sats` 与你在测试网络上能接受的损失相符。每笔交换提交之前都会校验这些参数。
  </Step>

  <Step title="确认无误后再关闭 dry run">
    当连续几轮的 dry-run 决策都看起来正确后，再把 `portfolio.dry_run` 设为 `false`。
  </Step>
</Steps>

## 确认机制长什么样

两种代理接入方式对花费的把关方式不同，值得弄清楚你依赖的是哪一种。

| 接入方式               | 把关机制                                                               |
| ------------------ | ------------------------------------------------------------------ |
| **KaleidoMind**    | 结构性把关。每个会动用资金的工具都标记了 `requiresConfirmation`，引擎会暂停并等待宿主的确认面板。模型无法绕过 |
| **KaleidoAgent**   | 策略性把关。`dry_run` 加上 `agent.config.json` 中的风险上限，在提交前校验               |
| **通用宿主中的 MCP 服务器** | 取决于你的宿主客户端。多数 MCP 客户端会为每次工具调用弹出确认，但那是客户端的行为，不是服务器的                 |

<Warning>
  通用 MCP 宿主是保护最弱的一条路径。如果你的客户端自动批准工具调用，LLM 就能不经询问地从配置的钱包中花钱。在完全弄清客户端如何处理批准之前，请只使用测试网络种子。
</Warning>