Skip to main content

​
常见问题

只有需要连接节点的命令才需要。只装一个 CLI，就可以浏览交易对并请求报价：
Docker 只用于 node 管理的本地环境。如果你已经在别处运行 RGB 闪电节点，用 --node-url 指过去即可，完全不需要 Docker。
setup 是首次使用的入口，node create 是创建更多环境的向导。
  • kaleido setup 把 API 和节点默认值写入 ~/.kaleido/config.json；在 local 模式下还会用默认端口创建并启动一个环境。不带参数的 kaleido setup 以非交互方式运行，因此 Docker 必须已经在运行。
  • kaleido node create [name] 会依次询问基础目录、名称、节点数量、网络和基础端口。需要第二个环境或非默认端口时用它。
详见快速开始与节点环境。
因为不同命令使用两套不同的单位约定。所以报价用 --from-amount 0.001 是对的，而 kaleido asset send rgb:abc... 100 rgb:invoice... 发送的是 100 个原始单位，不是 100 个显示单位。发送前先用 kaleido asset metadata <asset-id> 确认精度。
它们是同一套协议的两种作用范围。日常交易用 kaleido swap atomic run <pair> 即可，它把 init、whitelist 和 execute 合并成一条命令。详见市场与交换。
可接受的取值取决于具体命令：
  • market quote —— BTC_LN、RGB_LN、BTC_ONCHAIN
  • swap atomic init 与 swap atomic run —— BTC_L1、BTC_LN、RGB_L1、RGB_LN
--from-layer 和 --to-layer 都是可选的：省略时，layer 由请求的交易对方向推导。需要指定具体路径时再显式传入，例如通过闪电发送、通过 RGB on Lightning 接收：
不会。 CLI 只是两套 HTTP API 之上的终端客户端。助记词在你运行 kaleido node init 时于 RGB 闪电节点内部生成，所有签名也都在节点里完成。CLI 无法转移节点未授权的任何资金。用 --password 传入的钱包密码会留在 shell 历史里 —— 重要场景请使用交互式输入，并把 kaleido wallet backup 的备份妥善保存。
节点的密钥在静态时是加密的，因此启动后处于锁定状态。kaleido node init 每个节点只需运行一次，kaleido node unlock 则每次重启后都要运行。解锁同时决定节点使用哪些比特币服务。交互模式下 CLI 会提供三种配置档 —— signet 默认值、regtest 默认值或自定义 —— 并询问节点如何跟随链：
  • --chain-sync block（默认）通过 RPC 从 bitcoind 读取区块
  • --chain-sync transaction 只依赖索引器跟随链，完全不需要 bitcoind
使用 --chain-sync transaction 时，--bitcoind-* 选项会被忽略。详见节点环境。
优先级从高到低：
  1. 命令行标志：--node-url、--api-url
  2. 环境变量：KALEIDO_NODE_URL、KALEIDO_API_URL
  3. ~/.kaleido/config.json 中保存的配置
用 kaleido config show 查看已保存的配置，用 kaleido config path 查看文件路径。注意 kaleido node use <name> 写入的是保存的配置，因此对同时传了 --node-url 的命令不起作用。
可以。每个环境都是独立的 Docker Compose 项目，拥有自己的 compose 文件、数据卷和端口，而且一个环境内可以有多个节点。
节点 1 使用守护进程端口 3001 和对等端口 9735，节点 2 使用 3002 和 9736，依此类推。只有一个环境时，up、stop、logs、clean 等命令会自动识别；有多个时必须指定名称。
区别在于删除的范围：clean 不可撤销：它会先关停环境，再删除数据卷，钱包也在其中。如果节点里还有你需要的东西，先执行 kaleido wallet backup。
RGB 的分配绑定在特定的比特币输出上，因此节点需要空闲的「有色」UTXO 才能发行、接收或发送资产。链上余额即使充足，如果只集中在一个大 UTXO 上也不够用。
在大量 RGB 操作之前一次性准备好，不要用一个建一个。--up-to 会把 --num 的含义从「新建这么多个」改为「补齐到总共这么多个」。
三个标志就够了：
  • --json 返回原始 JSON 而不是表格，便于交给 jq
  • --agent 关闭所有交互提示，缺少参数时直接报错而不是阻塞
  • --yes 自动确认报价、付款和破坏性操作
非交互模式下 CLI 宁可报错也不会猜测，例如 --yes is required in non-interactive mode to accept the quoted price.。详见故障排查。
是的 —— 它封装了 Python 版 SDK（kaleido-sdk），这也是命令输出与 API 模型高度一致的原因。实际影响有三点：
  • 请求使用 30 秒超时，最多重试 3 次
  • 错误以 Error: <message> 的形式呈现，来自底层 SDK 异常，因此 SDK 错误参考解释了失败的含义
  • market quote 的显示金额使用与 SDK 相同的精度换算工具
如果你要开发应用而不是执行命令，请直接使用 KaleidoSDK。
三者驱动的是同一套 API，所以用 CLI 创建的节点也能从 SDK 使用，反之亦然。
CLI 从源码安装 —— 它没有发布到 PyPI，因此 pip install kaleido-cli 找不到这个包。请使用引导安装脚本或 uv：
重新执行同一条命令即可更新，uv 安装会替换已有的工具。CLI 没有 kaleido --version 标志，因此请以 uv tool list 的输出或安装时的提交号来说明版本。完整方式见安装。

​
获取帮助

如果遇到的是报错而不是疑问，请查阅故障排查；上游文档与相关链接见更多资源。 其他情况请通过下面你偏好的渠道反馈问题，并附上：
  1. CLI 的安装方式，以及 uv tool list 的输出（没有 --version 标志）
  2. Python 版本（python --version）与操作系统
  3. 你执行的完整命令，以及加上 --json 后的输出
  4. 节点是本地 Docker 环境还是远程节点，以及所在网络
  5. kaleido config show 与 kaleido node ps 的输出，去掉其中的密码

Telegram 社区

向社区提问。

GitHub Issues

在相应的仓库中报告缺陷。

邮件支持

紧急问题的直接支持渠道。