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 打印的助记词。
如果 3001 端口已被占用,kaleido setup 会选择下一个空闲端口。kaleido node list 会显示该 URL,在后续步骤中把它用作 RLN_NODE_URL。
- 为节点注资
RGB 资产依附在比特币 UTXO 上,因此节点在接收任何资产之前需要少量 signet BTC。
1
获取 signet BTC
打印一个链上地址,并从公共的 Mutinynet 水龙头向它发币。该水龙头要求你用 GitHub 登录,或支付一张小额闪电发票:signet 大约每 30 秒出一个块。用
kaleido wallet balance 查看余额。2
为 RGB 创建 UTXO
把一部分 BTC 拆分成可以承载 RGB 分配的 UTXO:
3
获取测试 RGB 资产
打开 KaleidoSwap RGB 水龙头并用 GitHub 登录。复制页面上列出的 USDT 或 XAUT 资产 ID,并为它创建一张 RGB 发票:把发票粘贴到水龙头的 RGB 链上标签页。每次领取发送 100 USDT 或 0.1 XAUT,每天最多 5 次。转账确认后,先运行
kaleido asset refresh,再用 kaleido asset list 就能看到该资产。水龙头的闪电标签页需要一条通往你节点的路由,因此要在下一步之后才能使用。4
向 KaleidoSwap LSP 购买通道
交换和闪电支付都需要通道。KaleidoSwap LSP 会向你的节点开一条通道,可选地在它那一侧预置 USDT 或 XAUT,你在链上支付费用:
- 通道大小:50,000 到 1,000,000 sat,每条通道最多 1,000 USDT 或 XAUT。一条 200,000 sat 的通道费用约 3,400 sat。
- 通过代理:
Buy a channel from the KaleidoSwap LSP preloaded with 10 USDT会调用kaleidoswap_lsp_get_info、kaleidoswap_lsp_quote_asset_channel和kaleidoswap_lsp_create_asset_channel。把费用支付到订单返回的地址。 - 在 KaleidoSwap 桌面版中:Channels → Order New Channel。
- 在 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.20.0,并以 0.21.0 为测试基准。把下面的代码保存为 agent.mjs:
agent.mjs
onConfirm 回调处暂停,在你输入 y 之前,任何资金都不会离开节点。
这是一个最小的宿主。
@kaleidorg/mind README 以及 kaleido-mind 仓库中的 examples/node-minimal 和 examples/rgb-agent 目录走得更远,包含 skills、recipe 和更大的模型。示例加载 Qwen3.5 2B(约 1.3 GB),在我们的测试中它完成了所有 signet RGB 钱包任务。QWEN3_5_4B_MULTIMODAL_Q4_K_M(约 2.7 GB)同样准确,但速度约慢一倍;0.8B 模型在钱包操作上会陷入循环。示例中的 token 上限为模型回答前的推理留出了空间。
- 可以尝试的提示词
先只读,再收款,最后花费。
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 资产发行
用
rln_issue_asset 把门票或积分代币发行为新的 RGB 资产(需要空闲的可着色 UTXO),或在 CLI 中使用 kaleido asset issue nia。