CoinFello CLI 技能

使用 npx @coinfello/agent-cli@latest CLI 工具与 CoinFello 交互。该 CLI 支持智能账户创建、SIWE 认证、委托管理、基于自然语言提示的交易执行，以及交易状态查询。

前提条件

• Node.js 20 或更高版本（npx 随 Node.js 一同提供）

CLI 可通过 npx @coinfello/agent-cli@latest 直接调用，无需手动构建。

环境变量

若同时设置了 RPC_BASE_URL 和 RPC_API_KEY，CLI 将通过 QuickNode 路由 RPC 请求（支持链：Ethereum、Optimism、BSC、Polygon、Mantle、Base、Arbitrum、Linea、Sepolia、Base Sepolia）。若任一变量缺失，或目标链不受支持，则自动回退至该链的默认公共 RPC。

设置 RPC_URL_OVERRIDE（例如：http://127.0.0.1:8545）可强制所有 RPC 调用均经由该自定义 URL，无视链类型及其他 RPC 配置。

安全须知

本技能执行以下敏感操作：

• 密钥生成与存储：默认情况下，create_account 在 macOS Secure Enclave（或可用时的 TPM 2.0）中生成硬件级保护的 P256 密钥。私钥永不离开硬件，亦无法导出——仅将公钥坐标及密钥标签（key tag）保存至 ~/.clawdbot/skills/coinfello/config.json。若硬件密钥支持不可用，CLI 将发出警告并回退至软件密钥。您也可显式启用明文软件密钥（通过传入 --use-unsafe-private-key），此时原始私钥将以明文形式存入配置文件 —— 该选项仅限开发与测试用途。
• 签名守护进程（signer daemon）：运行 signer-daemon start 将通过 Touch ID / 密码完成一次性认证，并缓存授权上下文。后续所有签名操作复用该缓存，避免重复认证提示。守护进程通过用户作用域的 Unix 域套接字通信，权限严格限制为 0600。若守护进程未运行，签名操作将回退至直接执行模式（每次均需触发 Touch ID 提示）。
• 会话令牌存储：运行 sign_in 将 SIWE 会话令牌存入同一配置文件。
• 委托签名：运行 send_prompt 可能收到服务端下发的委托请求，该请求将被保存至本地文件；运行 approve_delegation_request 则会构造、签名并提交该委托至 CoinFello API。

用户应在执行委托流程前，确保信任通过 COINFELLO_BASE_URL 配置的 CoinFello API 终端节点。

快速上手

# 1. 启动签名守护进程（可选，可避免重复 Touch ID 提示）
npx @coinfello/agent-cli@latest signer-daemon start

# 2. 创建智能账户（默认使用 Secure Enclave）
npx @coinfello/agent-cli@latest create_account

# 3. 使用您的智能账户通过 SIWE 登录 CoinFello
npx @coinfello/agent-cli@latest sign_in

# 4. 发送自然语言提示 — 若需委托，系统将自动保存供审查
npx @coinfello/agent-cli@latest send_prompt "向 0xRecipient... 发送 5 USDC"

# 5. 批准委托请求（若 send_prompt 已保存请求）
npx @coinfello/agent-cli@latest approve_delegation_request

命令说明

create_account

创建 MetaMask Hybrid 智能账户。默认情况下，签名密钥在 macOS Secure Enclave（硬件级保护、不可导出）中生成。若 Secure Enclave 不可用，CLI 将发出警告并回退至软件密钥。传入 --use-unsafe-private-key 可显式启用明文软件密钥（仅限开发/测试）。

npx @coinfello/agent-cli@latest create_account [--use-unsafe-private-key]

• 默认（Secure Enclave）：在硬件中生成 P256 密钥；将 key_tag、public_key_x、public_key_y、key_id 和 smart_account_address 保存至 ~/.clawdbot/skills/coinfello/config.json；私钥永不离开 Secure Enclave。
• --use-unsafe-private-key：生成随机 secp256k1 私钥，并以明文形式存入配置文件。仅限开发与测试使用。
• 必须在 send_prompt 之前执行

get_account

显示本地配置中当前智能账户地址。

npx @coinfello/agent-cli@latest get_account

• 输出已保存的 smart_account_address
• 若尚未创建账户，则以错误退出

sign_in

使用 Sign-In with Ethereum（SIWE）及您的智能账户登录 CoinFello，并将会话令牌保存至本地配置。

npx @coinfello/agent-cli@latest sign_in

• 使用配置文件中存储的私钥完成登录
• 将会话令牌保存至 ~/.clawdbot/skills/coinfello/config.json
• 后续 send_prompt 调用将自动加载该会话令牌
• 必须在 create_account 之后、send_prompt 之前执行，以启用认证流程

set_delegation

将已签名的父级委托（JSON 格式）存入本地配置。

npx @coinfello/agent-cli@latest set_delegation ''

• — 表示 MetaMask Smart Accounts Kit 中 Delegation 对象的 JSON 字符串

new_chat

从本地配置中清除已保存的会话 ID，使下一次 send_prompt 启动全新对话。

npx @coinfello/agent-cli@latest new_chat

• 从 ~/.clawdbot/skills/coinfello/config.json 中移除 chat_id
• 当需要重置对话上下文时使用（例如：发生上下文窗口溢出错误后）

signer-daemon

管理 Secure Enclave 签名守护进程。启动守护进程将通过 Touch ID / 密码完成一次性认证并缓存授权，从而避免后续签名操作（如账户创建、登录、委托签名）重复弹出认证提示。

npx @coinfello/agent-cli@latest signer-daemon start    # 启动守护进程（一次性认证）
npx @coinfello/agent-cli@latest signer-daemon status   # 检查守护进程是否正在运行
npx @coinfello/agent-cli@latest signer-daemon stop     # 停止守护进程

• 若守护进程未运行，所有 Secure Enclave 操作将回退至直接执行模式（每次均需 Touch ID 提示）
• 守护进程为可选组件 —— 所有命令均可在无守护进程状态下正常工作

send_prompt

向 CoinFello 发送自然语言提示。若服务端判定需委托方可执行该操作，CLI 将委托请求保存至本地文件，并在终端打印详细信息供审查。该委托不会自动签名 —— 您必须显式调用 approve_delegation_request 完成批准。

npx @coinfello/agent-cli@latest send_prompt ""

若您收到如下错误： Failed to send prompt: Conversation request failed (400): {"error":"Your input exceeds the context window of this model. Please adjust your input or start a new chat and try again."} 请执行 npx @coinfello/agent-cli@latest new_chat 以开启新对话并获得新的上下文窗口。

内部执行流程：

1. 从 /api/v1/automation/coinfello-agents 获取可用 agent 列表，并将提示发送至 CoinFello 对话接口
2. 若服务端返回只读响应（无 clientToolCalls 且无 txn_id）→ 打印响应文本并退出
3. 若服务端直接返回 txn_id（无工具调用）→ 打印该 ID 并退出
4. 若服务端返回含 chainId 与 scope 的 ask_for_delegation 客户端工具调用：
   • 将委托请求（scope、链 ID、调用 ID、会话 ID）保存至 ~/.clawdbot/skills/coinfello/pending_delegation.json
   • 在终端打印该委托请求的人类可读摘要
   • 退出且不执行签名 —— 请运行 approve_delegation_request 完成批准

approve_delegation_request

批准并签名由 send_prompt 保存的待处理委托请求，随后提交至 CoinFello。

npx @coinfello/agent-cli@latest approve_delegation_request

内部执行流程：

1. 从 ~/.clawdbot/skills/coinfello/pending_delegation.json 读取待处理委托
2. 获取 CoinFello 的委托地址（delegate address）
3. 根据委托请求中的链 ID 重建智能账户
4. 解析 scope 并构造子委托（若智能账户尚未在链上部署，则使用 ERC-6492 签名封装）
5. 将已签名委托作为 clientToolCallResponse 连同 chatId 与 callId 一并发送
6. 清空待处理委托文件
7. 返回可用于追踪的 txn_id

常见工作流

基础流程：发送提示（服务端驱动委托）

# 启动签名守护进程（可选，减少 Touch ID 提示次数）
npx @coinfello/agent-cli@latest signer-daemon start

# 若尚未创建账户，请先执行（默认使用 Secure Enclave）
npx @coinfello/agent-cli@latest create_account

# 登录（委托流程必需）
npx @coinfello/agent-cli@latest sign_in

# 发送自然语言提示 — 若需委托，系统将自动保存供审查
npx @coinfello/agent-cli@latest send_prompt "向 0xRecipient... 发送 5 USDC"

# 查看终端中打印的委托请求摘要，然后批准
npx @coinfello/agent-cli@latest approve_delegation_request

只读提示

部分提示无需发起链上交易。CLI 可自动识别此类场景，并仅打印响应结果。

npx @coinfello/agent-cli@latest send_prompt "Base 链的 chain ID 是多少？"

Gas 费用估算

实际链上 Gas 成本因网络而异。请勿将主网 Ethereum 的 Gas 价格套用于 L2 链。

以上为常规网络状况下的近似范围。Base 等 L2 网络的费用显著低于 Ethereum 主网。

边界情况处理

• 无智能账户：请在 send_prompt 前执行 create_account。CLI 会检查配置文件中是否存在已保存的私钥与地址。
• 未登录：若服务端要求认证，请在 send_prompt 前执行 sign_in。
• 链名称无效：CLI 将抛出错误，并列出 viem 支持的有效链名称。
• 不支持的链：CLI 将拒绝 CoinFello 基础设施与 MetaMask 委托合约尚未覆盖的链。当前支持链包括：Ethereum、OP Mainnet、BNB Smart Chain、Polygon、Mantle、Base、Arbitrum One、Linea、Sepolia、Base Sepolia。在任何其他链上为智能账户充值，将导致资金永久锁定。
• 只读响应：若服务端返回纯文本响应且无交易关联，CLI 将直接打印响应并退出，不创建委托。

问题反馈与技术支持

若您遇到无法通过故障排查步骤解决的 Bug 或异常行为，请将问题描述及相关错误输出发送邮件至 support@coinfello.com。

参考文档

完整配置结构、支持链列表、API 细节、scope 类型及故障排查指南，请参阅 references/REFERENCE.md。