kaleido-mcp,RGB Lightning Node 则通过 KaleidoCLI 在 Docker 中运行。唯一的网络调用是发往你的节点、signet KaleidoSwap API,以及节点自身所需的比特币与 RGB 服务。
本教程的一切都运行在 signet 上,使用的测试币没有任何价值。不要在其他任何地方复用本教程中的种子或密码。
前置条件
不需要任何 API 密钥,也不需要托管的 LLM。
- 启动一个 signet RGB Lightning Node
用安装脚本安装 KaleidoCLI。它尚未发布到 PyPI,所以 pip install 找不到它:
mutinynet,它与 KaleidoSwap signet API 和 RGB 水龙头使用的是同一个 signet。请记下 kaleido node init 打印的助记词。
- 为节点注资
RGB 资产依附在比特币 UTXO 上,因此节点在接收任何资产之前需要少量 signet BTC。
1
获取 signet BTC
2
为 RGB 创建 UTXO
把一部分 BTC 拆分成可以承载 RGB 分配的 UTXO:
3
获取测试 RGB 资产
创建一张 RGB 发票。不指定资产 ID 即可接收任意资产:打开 KaleidoSwap RGB 水龙头,用 GitHub 登录并粘贴发票。转账确认后,先运行
kaleido asset refresh,再用 kaleido asset list 就能看到该资产。
- 在 signet 上运行 kaleido-mcp
KALEIDO_NETWORK=signet 会把 kaleido-mcp 指向 https://api.signet.kaleidoswap.com 和 Spark 测试网络。把 RLN_NODE_URL 指向第 1 步中的节点:
network: signet 并在 stdio 上等待。你不需要手动保持它运行:下一步中的代理会把它作为子进程启动。这里 WDK_SEED 是可选的,而且普通的 npx 不会安装 Spark 钱包包;缺少它们时 Spark 工具保持关闭,RGB、DEX、支付和行情工具照常可用。全部变量见 MCP 服务器。
- 通过 KaleidoMind 接入本地 QVAC 模型
创建一个项目,安装引擎、QVAC SDK 和 MCP 客户端:
@qvac/sdk 0.13 及以上版本,建议安装最新版本。把下面的代码保存为 agent.mjs:
agent.mjs
onConfirm 回调处暂停,在你输入 y 之前,任何资金都不会离开节点。
这是一个最小的宿主。
@kaleidorg/mind README 以及 kaleido-mind 仓库中的 examples/node-minimal 和 examples/rgb-agent 目录走得更远,包含 skills、recipe 和更大的模型。0.6B 模型能很好地处理快速路径和 recipe;对于开放式请求,Qwen3 1.7B 或 4B 这类更大的模型表现明显更好。
- 可以尝试的提示词
先只读,再收款,最后花费。
KaleidoMind 可能会用旧的
rln_* 名称调用同样的工具;kaleido-mcp 两种名称都提供。
如果没有第二个钱包也想试试发送,可以向朋友要一张 RGB 发票,或者用 kaleido node create 在第二个节点上生成一张。
Mock 模式:无需节点与资金
如果想在节点就绪之前或在 CI 中构建代理逻辑,可以把 MCP 工具源换成@kaleidorg/mind/testing 中的有状态 mock 钱包。它绑定的是同一份工具契约,因此驱动它的代码之后同样可以驱动真实节点:
mock.mjs
scriptedProvider() 完全不需要模型。把它换成第 4 步中的 QVAC provider,就能用真实模型测试 mock 钱包;再把 wallet.registry() 换成 new ToolRegistry([kaleido]),即可接入真实节点。
故障排查
kaleido: command not found
kaleido: command not found
安装程序会把
kaleido 放在一个用户脚本目录中,该目录可能还不在你的 PATH 里。请打开一个新的终端,或按照安装程序打印的路径操作。见 CLI 安装。代理连不上节点
代理连不上节点
运行
kaleido node info。如果失败,用 kaleido node up 启动容器,再用 kaleido node unlock 解锁;每次重启后钱包都会重新锁定。然后确认 RLN_NODE_URL 与 kaleido node list 标记为当前活动的 URL 一致。水龙头的转账一直没有到账
水龙头的转账一直没有到账
运行
kaleido asset refresh 并等待一次确认。如果节点没有空闲的 UTXO,发票就无法创建或结算:用 BTC 注资后再运行一次 kaleido wallet create-utxos。对方无法支付我的 RGB 发票
对方无法支付我的 RGB 发票
付款方会从发票中列出的 RGB 代理获取转账数据。请用
kaleido asset invoice 创建发票(它会加入默认代理),或像上表那样在提示词中指明代理。报价失败或指向了主网
报价失败或指向了主网
确认
kaleido-mcp 输出了 network: signet。环境中显式设置的 KALEIDOSWAP_API_URL 或 KALEIDO_API_URL 会覆盖预设。交换一直没有执行
交换一直没有执行
检查
wdk_list_channels:你需要一条与做市方之间、可用且承载所买卖资产的通道。没有它,报价可以成功,但无法结算。模型调用了错误的工具或编造参数
模型调用了错误的工具或编造参数
小模型不擅长开放式规划。请像上面的提示词那样把请求说具体,或者加载更大的 QVAC 模型。KaleidoMind 的 recipe 会以确定性方式处理多步流程,模型只需要填槽。
黑客松项目灵感
语音钱包
QVAC 也能在本地运行语音转文字和文字转语音。
@kaleidorg/mind/qvac 中的 createQvacVoice 和 runVoiceAssistant 提供免手操作的循环,每次花费前都会语音确认。为 API 付费的代理
让代理用
search_paid_apis 找到付费 API,再通过 mpp_* 和 l402_* 工具按次经闪电网络付款。无需注册,也无需 API 密钥。自主交换机器人
用
l402_get_price 和 kaleidoswap_get_spreads 盯盘,并通过原子交换在 BTC 与 USDT 之间再平衡。在决策看起来可靠之前,请一直保留确认关卡。RGB 资产发行
把门票或积分代币发行为新的 RGB 资产。目前可以通过 CLI(
kaleido asset issue nia)以及 KaleidoMind 的 mock 钱包实现;kaleido-mcp 尚未提供发行工具。