Skip to main content

​
安装问题

症状： 安装已完成，但 shell 找不到 kaleido原因： 存放启动器的目录不在 PATH 中。安装脚本的最后一行已经提示过：If 'kaleido' is not found yet, add <dir> to your PATH and restart your shell.解决办法：
  1. 先重启 shell —— 已经运行中的会话看不到新加入 PATH 的条目
  2. 若使用 uv 安装，确认工具目录在 PATH 中：uv tool dir 和 uv tool list
  3. 若使用引导安装脚本，把它打印的目录写进 shell 配置文件（~/.bashrc、~/.zshrc）
  4. Windows 上请使用 WSL —— shell 引导脚本面向 macOS、Linux 和 WSL
症状： ERROR: Could not find a version that satisfies the requirement kaleido-cli原因： CLI 没有发布到 PyPI，只能从源码安装。解决办法：
也可以使用引导安装脚本，它优先调用 uv，否则回退到隔离的虚拟环境。详见安装。
症状： 安装脚本以这条信息终止解决办法：
  1. 查看当前版本：python3 --version
  2. 安装更新的 Python，或交给 uv 管理：uv python install 3.12
  3. 待 python3 指向 3.10 或更高版本后重新执行安装

​
设置与环境

症状： 任何 node 生命周期命令、或不带参数的 kaleido setup 报出这条信息原因： CLI 通过 docker compose 执行操作，因此二进制文件和运行中的守护进程缺一不可。解决办法：
  1. 同时确认客户端与守护进程：docker version —— 必须出现 “Server” 部分
  2. 启动 Docker Desktop，Linux 上执行 sudo systemctl start docker
  3. 确认 Compose v2 插件可用：docker compose version
  4. 如果完全不想用 Docker，可以只做市场模式设置：kaleido setup --mode market --defaults
症状： No docker-compose.yml found in <dir>，随后是 Run 'kaleido node create' to generate it.，或者 Environment directory not found: <dir>原因：
  • 环境从未创建过，或创建在了另一个基础目录下
  • 配置里的 spawn-dir 指向的位置与环境实际所在的位置不一致
解决办法：
  1. 先看 CLI 实际能识别哪些环境：kaleido node list
  2. 检查基础目录：kaleido config show —— 环境位于 spawn-dir 下，默认为 ~/.kaleido
  3. 重新创建：kaleido node create <name>
症状： 生命周期命令拒绝执行，并列出可用的环境原因： 只有当环境恰好只有一个时，名称才会被自动识别。解决办法： 显式指定名称。
相关的 No environments found. Run 'kaleido node create' first. 则是相反的问题 —— 还没有创建过任何环境。
症状： kaleido setup 以这条信息终止，并提示 Choose a different environment name with --env-name to create a new node.解决办法：
  1. 复用已有环境：kaleido node up <name>，然后 kaleido node use <name>
  2. 或者另建一个：kaleido setup --env-name taker-2
交互式的 kaleido node create 则会询问是否覆盖 compose 文件，这不会影响数据卷。
症状： node up 成功，node info 失败解决办法：
  1. 查看容器状态：kaleido node ps <name>
  2. 读取节点自身的日志：kaleido node logs <name> --service rgb_node_1 --no-follow
  3. 排查端口冲突 —— 节点 1 绑定 3001 与 9735，节点 2 绑定 3002 与 9736。若这些端口被占用，用 kaleido node create 以不同的基础端口重建环境
  4. up 之后稍等片刻：节点需要先打开数据库才能对外提供服务

​
节点连接

症状： 这条信息，外加 Use --node-url or: kaleido config set node-url http://localhost:3001原因： 该命令需要节点，但标志、环境变量和配置里都没有节点 URL。解决办法：
  1. 指向某个环境的节点：kaleido node use <name>
  2. 或直接设置：kaleido config set node-url http://localhost:3001
  3. 或只为这一条命令覆盖：kaleido --node-url http://localhost:3002 wallet balance
症状： wallet、asset、channel、payment 报连接错误，或者余额属于另一个节点原因：
  • 容器没有在运行
  • node-url 仍指向你上次使用的节点
  • shell 里导出了 KALEIDO_NODE_URL，静默覆盖了保存的配置
解决办法：
  1. 确认当前生效的节点：kaleido config show，以及 kaleido node list —— 生效的节点标记为 ●
  2. 启动环境：kaleido node up <name>
  3. 检查是否有残留的覆盖：echo $KALEIDO_NODE_URL
  4. 记住优先级：标志 → 环境变量 → 配置文件
症状： kaleido node use <name> --node 2 被拒绝原因： --node 是 compose 文件中实际定义的节点的 1 起始索引。解决办法： 用 kaleido node list 查看环境里有多少个节点。需要更多节点时，重建环境并在节点数量提示处填更大的值。相关的 No nodes found in environment '<name>'. Is the compose file present? 表示 compose 文件存在，但没有定义任何 rgb_node_* 服务。
症状： Error unlocking wallet: …，或重启后节点命令全部失败原因：
  • 节点重启后没有解锁 —— 每次重启都需要 unlock
  • 解锁请求指向的 bitcoind 或索引器不可达
  • 这个节点上的钱包从未初始化
解决办法：
  1. 解锁：kaleido node unlock
  2. 如果问题出在服务上，改用索引器跟随链，而不是 bitcoind：
  3. 如果从未初始化，先运行一次 kaleido node init
  4. 用 kaleido node info 确认结果
症状： Error initializing wallet: …原因：
  • 这个节点上的钱包已经初始化过 —— init 每个节点只做一次，不是每个会话一次
  • 恢复时传入的 --mnemonic 无效
解决办法：
  1. 若节点已初始化，直接执行 kaleido node unlock
  2. 想从干净的节点重来，kaleido node clean <name> 会不可逆地删除数据卷，之后才能重新 init
  3. 恢复时给助记词加引号，避免被 shell 拆开：--mnemonic "word1 word2 …"

​
钱包与资产

症状： wallet send 或 asset send 报余额不足原因：
  • 余额尚未确认
  • 没有空闲 UTXO 可供 RGB 分配使用
  • 金额之外的手续费无法覆盖
解决办法：
  1. 查看真正可用的部分：kaleido wallet balance 与 kaleido wallet utxos
  2. 在 RGB 操作前创建有色 UTXO：kaleido wallet create-utxos --num 10 --size 3000
  3. signet 上用 Mutiny 水龙头给节点充值，地址来自 kaleido wallet address
  4. 用 kaleido wallet estimate-fee --blocks 6 查看当前费率，并显式传入 --fee-rate
症状： kaleido asset transfers <asset-id> 中的转账始终没有完成解决办法：
  1. 推进待处理的转账：kaleido asset refresh
  2. 重新同步 RGB 钱包：kaleido asset sync
  3. 再看一次状态：kaleido asset transfers <asset-id>
  4. 只有在转账确实失效时，才释放它占用的分配：kaleido asset fail-transfers --batch-idx <idx>
如果你一直在传 --skip-sync，请去掉：命令返回的本来就是缓存状态。
症状： File not found: <path> 或 Invalid JSON: …原因： asset send-batch 接收的是一个描述收款方的 JSON 文件路径，而不是内联标志。解决办法：
确认路径相对于当前目录正确，并在重试前校验该文件。
症状： --agent 模式下 wallet backup 或 wallet restore 被拒绝原因： 目标路径是位置参数，而提示已被禁用。解决办法： 显式传入路径和密码。
restore 会覆盖当前节点数据，务必谨慎执行。

​
通道与 LSP 订单

症状： channel open 或 peer connect 被拒绝原因： 只传了裸公钥。交互模式下 CLI 会追问地址，非交互模式下必须给出完整格式。解决办法：
  1. 使用完整的 peer 字符串：kaleido channel open 03abc...@peer.host:9735 --capacity 100000
  2. 先连接并确认可达：kaleido peer connect 03abc...@peer.host:9735，然后 kaleido peer list
相关的非交互模式拒绝还有 PEER argument is required in non-interactive mode. 与 --capacity is required in non-interactive mode.。
症状： 有色通道命令还没联系节点就被拒绝原因： 脱离资产本身，资产数量没有意义。同样的规则适用于 --push-asset-amount，以及 LSP 订单上的 --lsp-asset-amount / --client-asset-amount。解决办法：
LSP 订单上还有两条约束：--lsp-asset-amount is required when --asset-id is set. 与 --client-asset-amount must be less than or equal to --lsp-asset-amount.。
症状： channel close <channel-id> 被拒绝原因： 关闭通道同时需要通道 ID 和对端公钥。解决办法：
只有在对端无响应时才加 --force：单方面关闭会把资金锁定到时间锁到期为止。
症状： channel order create 或 estimate-fees 拒绝该资产原因： LSP 只为它支持的资产开通有色通道。解决办法： 先查看它支持哪些资产，再使用其中的资产 ID。
LSP did not report a connection URL. 是同一次交互的另一面 —— 返回的 LSP 元数据里没有对等地址，订单无法继续。
症状： channel order pay 返回 This order is not awaiting a wallet payment. Current payment state: <state>原因：
  • 订单已经支付过
  • 在完成资金确认前就过期了
  • 它在等待费率决定，而不是等待付款
解决办法：
  1. 查看当前状态：kaleido channel order get <order-id> --access-token <token>
  2. 若在等待费率，提交决定：kaleido channel order decide <order-id> --accept
  3. 若已过期，重新创建订单 —— --funding-within 与 --expiry-blocks 控制这两个时间窗
  4. 非交互模式下必须显式选择付款方式，否则会看到 Specify exactly one of --onchain or --offchain in non-interactive mode.

​
市场与交换

症状： Pair 'BTC/USD' not found. Use 'kaleido market pairs' to list available pairs.原因：
  • 拼写错误，或该 ticker 未上线
  • 交易对方向写反了 —— 顺序是有意义的
解决办法：
  1. 列出所有交易对：kaleido market pairs
  2. 使用该输出中确切的 BASE/QUOTE ticker
No trading pairs are currently available. 则不同：maker 返回了空列表，问题在上游而不在你的命令。
症状： 报价或交换命令被拒绝，或提示 Provide --from-amount or --to-amount in non-interactive mode.原因： 报价只锚定一侧 —— 你固定发送金额或接收金额，另一侧由 maker 定价。解决办法：
  1. 二者只传其一
  2. 记住这里是显示单位：--from-amount 0.001 是 0.001 BTC，不是 1000 聪
  3. 如果金额被判为无效，用 kaleido market pairs 查看该交易对的上下限
症状： 这条信息，或 Swapstring fields must not be empty or whitespace.、Swapstring contains invalid numeric fields.原因： swapstring 被截断或损坏了。它的结构是：
解决办法：
  1. 从 swap atomic init 的输出中完整复制，不要折行
  2. 加引号，避免 shell 改动它：--swapstring '30/rgb:abc.../10/rgb:def.../600/<hash>'
  3. 或者用 kaleido swap atomic run <pair> 完全跳过这一步
症状： Auto-whitelist validation failed: …，或类似 Swapstring from_amount 30 does not match quote amount 31. 的信息原因： 在本地节点白名单之前，CLI 会用你接受的报价校验 swapstring。不匹配说明这个 swapstring 属于另一笔交换，或者报价已经变了。解决办法：
  1. 重新执行 swap atomic init，并使用同一次响应里的 swapstring 与 payment hash —— 不要跨次混用
  2. 重新报价后不要复用旧的 swapstring
  3. Maker returned no swap payload for --payment-hash; refusing to auto-whitelist. 表示 maker 没有该 payment hash 对应的交换：用 kaleido swap atomic status <payment-hash> 核对
症状： swap atomic init 成功，swap atomic execute 失败原因： maker 结算之前，taker 节点必须先接受这笔交换，而这一步发生在你的节点上，不在 maker 那边。解决办法： 三个步骤必须按顺序执行。
也可以交给 CLI：给 execute 加上 --auto-whitelist，或直接用 kaleido swap atomic run <pair>。
症状： execute 已返回，但资产没有到账解决办法：
  1. 轮询 maker 一侧：kaleido swap atomic status <payment-hash>
  2. 轮询你的节点一侧：kaleido node swap status <payment-hash> --taker
  3. 列出节点已知的交换：kaleido node swap list
  4. 推进待处理的 RGB 转账：kaleido asset refresh
最常见的原因是你发送那一侧的出向容量不足。用 kaleido channel list 检查该资产的容量，而不只是看总余额。

​
脚本与自动化

症状： 脚本停在那里，没有任何输出原因： 命令在等待一个没人会回答的交互提示。解决办法： 加上 --agent，它会把所有提示变成报错：
这样你会得到明确的拒绝信息，例如 PAIR argument is required in non-interactive mode. 或 <option> is required in non-interactive mode.，直接指出缺了什么。
症状： --yes is required in non-interactive mode to accept the quoted price.、… to accept the RFQ price.、… to pay the order.，或它们的 JSON 模式变体原因： 任何花钱或接受价格的操作都会请求确认，而此时没人可以确认。解决办法：
  1. 确认参数无误后加上 --yes
  2. 先用 kaleido market quote 或 kaleido channel order estimate-fees 核价，再带 --yes 执行
  3. kaleido node clean 与 kaleido config reset 同样接受 --yes
症状： Must specify exactly one of --accept or --reject、Must specify at most one of --taker or --maker，或 Specify exactly one of --onchain or --offchain in non-interactive mode.原因： 这些是选择而不是开关，两个都不给或都给时，CLI 拒绝猜测。解决办法： 只传其中一个。交互模式下两个都省略时，CLI 会改为询问。

​
调试

当报错信息不足以定位问题时，从 CLI 自己的视角逐层向外排查：
同时检查 echo $KALEIDO_NODE_URL 与 echo $KALEIDO_API_URL：导出的环境变量会覆盖保存的配置，而且很容易被忘记。

​
获取帮助

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

Telegram 社区

向社区提问。

GitHub Issues

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

邮件支持

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