coinfello

CoinFello CLI 技能

使用 npx @coinfello/agent-cli@latest CLI 与 CoinFello 交互。该 CLI 可处理智能账户创建、SIWE 身份验证、委托管理、基于提示词的交易和交易状态检查。

前置条件

• Node.js 20 或更高版本（Node.js 已包含 npx）

可通过 npx @coinfello/agent-cli@latest 使用该 CLI。无需手动构建。

环境变量

变量	必需	默认值	描述
COINFELLO_BASE_URL	否	https://app.coinfello.com/	CoinFello API 的基础 URL
RPC_BASE_URL	否	—	QuickNode RPC 基础 URL（例如：https://your-endpoint-name）
RPC_API_KEY	否	—	QuickNode API 密钥
RPC_URL_OVERRIDE	否	—	用于开发／测试的自定义 RPC URL 覆盖项（覆盖所有其他 RPC 设置）

如果同时设置了 RPC_BASE_URL 和 RPC_API_KEY，CLI 会通过 QuickNode 路由受支持链（Ethereum、Optimism、BSC、Polygon、Mantle、Base、Arbitrum、Linea、Sepolia、Base Sepolia）的 RPC 请求。如果缺少其中任一项，或链不受支持，则会回退到该链的默认公共 RPC。

设置 RPC_URL_OVERRIDE（例如：http://127.0.0.1:8545），即可通过自定义 URL 路由所有 RPC 调用，不受链或其他 RPC 设置影响。

安全提示

此技能会执行以下敏感操作：

• 密钥生成和存储：默认情况下，create_account 会在 macOS Secure Enclave（或支持时使用 TPM 2.0）中生成硬件保护的 P256 密钥。私钥不会离开硬件，也无法导出；只有公钥坐标和密钥标签会保存到 ~/.clawdbot/skills/coinfello/config.json。如果不支持硬件密钥，CLI 会发出警告并回退到软件私钥。你也可以通过传入 --use-unsafe-private-key，明确选择使用明文软件密钥；这会将原始私钥存储在配置文件中——仅用于开发和测试。
• 签名器守护进程：运行 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. Start the signing daemon (optional, but avoids repeated Touch ID prompts)
npx @coinfello/agent-cli@latest signer-daemon start

# 2. Create a smart account (uses Secure Enclave by default)
npx @coinfello/agent-cli@latest create_account

# 3. Sign in to CoinFello with your smart account (SIWE)
npx @coinfello/agent-cli@latest sign_in

# 4. Send a natural language prompt — if a delegation is needed, it will be saved for review
npx @coinfello/agent-cli@latest send_prompt "send 5 USDC to 0xRecipient..."

# 5. Approve the delegation request (if one was saved by 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 '<delegation-json>'

• <delegation-json> — 表示 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    # Start daemon (one-time auth)
npx @coinfello/agent-cli@latest signer-daemon status   # Check if daemon is running
npx @coinfello/agent-cli@latest signer-daemon stop     # Stop the daemon

• 如果守护进程未运行，所有 Secure Enclave 操作都会回退为直接执行（每次都提示输入 Touch ID）
• 守护进程为可选项 — 所有命令都可以在没有它的情况下运行

send_prompt

向 CoinFello 发送自然语言提示词。如果服务器要求提供委托才能执行操作，CLI 会将委托请求保存到本地文件，并在终端中记录详细信息供审核。委托不会自动签署 — 你必须通过 approve_delegation_request 显式批准。

npx @coinfello/agent-cli@latest send_prompt "<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 的委托地址
3. 使用委托请求中的链 ID 重建智能账户
4. 解析作用域并创建子委托（如果智能账户尚未部署到链上，则使用 ERC-6492 签名进行封装）
5. 将签名后的委托连同 chatId 和 callId 作为 clientToolCallResponse 发回
6. 清除待处理的委托文件
7. 返回用于跟踪的 txn_id

常见工作流

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

# Start the signing daemon (optional, reduces Touch ID prompts)
npx @coinfello/agent-cli@latest signer-daemon start

# Create account if not already done (uses Secure Enclave by default)
npx @coinfello/agent-cli@latest create_account

# Sign in (required for delegation flows)
npx @coinfello/agent-cli@latest sign_in

# Send a natural language prompt — if a delegation is needed, it will be saved for review
npx @coinfello/agent-cli@latest send_prompt "send 5 USDC to 0xRecipient..."

# Review the delegation request logged to the terminal, then approve it
npx @coinfello/agent-cli@latest approve_delegation_request

只读提示词

某些提示词不需要交易。CLI 会自动检测到这一点，并直接打印响应。

npx @coinfello/agent-cli@latest send_prompt "what is the chain ID for Base?"

Gas 费用估算

实际的链上 Gas 费用会因网络而异。不要将以太坊主网的 Gas 价格套用于 L2 链。

网络	兑换 / 转账 Gas 费用
Base	$0.0003 – $0.0006

这些是在正常网络条件下的近似范围。Base 等 L2 的费用远低于以太坊主网。

边缘情况

• 没有智能账户：在运行 send_prompt 前，先运行 create_account。CLI 会检查配置中是否保存了私钥和地址。
• 未登录：如果服务端要求身份验证，请在运行 send_prompt 前先运行 sign_in。
• 无效的链名称：CLI 会抛出错误，并列出有效的 viem 链名称。
• 不支持的链：CoinFello 基础设施和 MetaMask 委托合约不可用的链会被 CLI 拒绝。支持的链：Ethereum、OP Mainnet、BNB Smart Chain、Polygon、Mantle、Base、Arbitrum One、Linea、Sepolia、Base Sepolia。在任何其他链上为智能账户注资都会导致资金永久锁定。
• 只读响应：如果服务端返回的是不含交易的文本响应，CLI 会打印该响应并退出，不会创建委托。

Bug 报告与支持

如果遇到无法通过故障排除步骤解决的 Bug 或意外行为，请发送邮件至 [email protected]，描述问题并附上任何相关的错误输出。

参考

完整的配置架构、支持的链、API 详情、作用域类型和故障排除信息，请参阅 references/REFERENCE.md。