openfort-cli

Openfort CLI

⚠️ 测试密钥与正式密钥。 openfort login 会针对单一模式进行身份验证。测试密钥（pk_test_… / sk_test_…）在测试网上运行；正式密钥（pk_live_… / sk_live_…）在持有真实资金的主网上运行，两者彼此隔离——在其中一个环境中创建的账户无法在另一个环境中使用。

• 使用测试（开发）密钥登录时创建的钱包仅存在于测试网上，且绝不能持有生产资金。
• 如需用于生产环境，请使用正式密钥重新进行身份验证并创建全新钱包；不要重复使用测试钱包。 请参阅 https://openfort.io/docs/configuration/api-keys。

你正在帮助用户使用 Openfort——一个区块链钱包基础设施平台，支持 EVM 和 Solana 链上的嵌入式钱包、全局钱包、后端钱包以及链上基础设施（Bundler + Paymaster）。

本指南介绍概念模型和工作流知识。要执行特定 CLI 命令，请委派给相应的 openfort-* 技能（例如，/openfort-accounts-evm、/openfort-policies-create）。

核心概念

钱包类型

Openfort 提供三种钱包产品：

钱包类型	控制者	用途
嵌入式钱包	最终用户（自托管）	消费者应用、游戏——用户通过社交登录、通行密钥或密码恢复来拥有自己的密钥
全局钱包	最终用户（跨应用）	通过 Ecosystem SDK 在多个应用间共享的生态系统钱包
后端钱包	开发者（服务器端）	自动化、AI Agent、薪资发放、交易机器人——开发者使用 API 密钥签名

CLI 主要管理后端钱包。嵌入式钱包和全局钱包通过 SDK（React、React Native、Swift、Unity、JavaScript）管理。

账户模型（后端钱包）

账户模型分为三个层级，理解这一层级结构至关重要：

EOA (Externally Owned Account)
  └── created with: openfort accounts evm create
  └── ID format: acc_...
  └── A standard Ethereum key pair

Delegated Account (Smart Account via EIP-7702)
  └── created with: openfort accounts evm update <eoa-id> --chainId <chain> --implementationType CaliburV9
  └── Gets its own acc_... ID (different from the EOA)
  └── Chain-specific — one delegation per chain
  └── Enables account abstraction (gasless transactions)
  └── On-chain delegation happens automatically on first transaction

Solana Account
  └── created with: openfort accounts solana create
  └── Separate key management from EVM
  └── Supports SOL, USDC, and SPL token transfers

Gas 赞助体系

要启用免 Gas 交易，必须配置三种资源：

Policy (ply_...)
  └── Defines WHAT is allowed (e.g., "sponsor EVM transactions on chain 84532")
  └── Has rules with criteria (chain IDs, contract addresses, operation types)

Sponsorship (pol_...)
  └── Links a Policy to a payment strategy
  └── Strategies: pay_for_user, charge_custom_tokens, fixed_rate
  └── Chain-specific

Transaction
  └── References the Sponsorship ID via --policy pol_...
  └── Gas fees are covered according to the sponsorship strategy

交易流程

发送交易有两种方式：

推荐：accounts evm send-transaction（一条命令即可完成所有操作）

1. 接收一个 EOA 账户 ID
2. 自动在目标链上查找或创建委托账户
3. 根据需要签署 EIP-7702 授权（首次交易）
4. 创建交易意图
5. 签名并提交

进阶：手动流程（需要精细控制时使用）

1. 将 EOA 升级为委托账户：accounts evm update
2. 创建交易意图：transactions create（返回可签名的 signableHash）
3. 签署哈希：accounts evm sign
4. 提交签名：transactions sign

常见工作流

首次设置

1. openfort login — 通过浏览器进行身份验证
2. openfort backend-wallet setup — 生成 ECDSA P-256 签名密钥
3. openfort accounts evm create — 创建第一个钱包

发送免 Gas 交易（端到端）

1. 创建钱包：openfort accounts evm create
2. 注册目标合约：openfort contracts create --name "..." --address 0x... --chainId <chain>
3. 创建策略：openfort policies create --scope project --rules '[{"action":"accept","operation":"sponsorEvmTransaction","criteria":[{"type":"evmNetwork","operator":"in","chainIds":[<chain>]}]}]'
4. 创建赞助配置：openfort sponsorship create --policyId ply_... --strategy pay_for_user --name "..." --chainId <chain>
5. 发送交易：openfort accounts evm send-transaction acc_... --chainId <chain> --interactions '[{"to":"0x...","data":"0x...","value":"0"}]' --policy pol_...
6. 验证：openfort transactions get <tin_id>

Solana 代币转账

1. 创建钱包：openfort accounts solana create
2. 转账 SOL：openfort accounts solana transfer <id> --to <address> --amount <lamports> --cluster devnet
3. 转账 USDC：openfort accounts solana transfer <id> --to <address> --amount <amount> --token usdc --cluster mainnet-beta
4. 转账任意 SPL 代币：openfort accounts solana transfer <id> --to <address> --amount <amount> --token <mint-address>

设置 Webhook

1. 创建订阅：openfort subscriptions create --topic transaction_intent.successful --triggers '[{"type":"webhook","target":"https://..."}]'
2. 可用主题：transaction_intent.broadcast、transaction_intent.successful、transaction_intent.cancelled、transaction_intent.failed、balance.project、balance.contract、balance.dev_account、user.created、user.updated、user.deleted、account.created、solana_transaction.broadcast、solana_transaction.successful、solana_transaction.failed、funding.session.updated、transaction.submitted、transaction.succeeded、transaction.failed、test

Session Keys（委托签名）

Session Keys 允许用户在有限时间内批准交易，无需反复确认：

1. 创建：openfort sessions create --address 0x... --chainId <chain> --validAfter <unix> --validUntil <unix> --player pla_... --account acc_...
2. 签名：openfort sessions sign <id> --signature 0x...
3. 撤销：openfort sessions revoke --address 0x... --chainId <chain> --player pla_...

SDK 集成方式

对于嵌入式钱包和全局钱包，用户使用 SDK，而非 CLI：

平台	SDK	主要功能
React	@openfort/openfort-react	Hooks：useEmailAuth、useOAuth、useEthereumEmbeddedWallet、useSolanaEmbeddedWallet
React Native	@openfort/openfort-react-native	支持 Passkey/密码恢复的移动端 Hooks
JavaScript	@openfort/openfort-js	原生 JavaScript，可与 Wagmi/Viem/Ethers 配合使用
Swift	OpenfortSDK	原生 iOS，支持 Apple Sign-In 和 Passkeys
Unity	OpenfortSDK	跨平台游戏集成
Global Wallet	@openfort/ecosystem-js	用于跨应用钱包的生态系统 SDK

身份验证方式（嵌入式钱包）

• 邮箱 + 密码
• 邮箱 OTP（无密码）
• 手机 OTP（短信）
• 社交 OAuth（Google、Apple、Discord、Twitter、Facebook、LINE）
• 访客模式（注册前试用）
• 外部钱包（SIWE）
• 第三方提供商（Firebase、Supabase、Better-Auth、AccelByte、PlayFab、LootLocker）

恢复方式（嵌入式钱包）

• 自动 — 最简单的方式，由 Openfort 管理恢复
• 密码 — 用户设置恢复密码
• Passkey — 通过 WebAuthn 实现生物识别安全验证

支持的链

Openfort 支持多条 EVM 链和 Solana。常见链 ID：

• Ethereum 主网：1
• Polygon：137
• Base：8453
• Base Sepolia（测试网）：84532
• Arbitrum：42161
• Optimism：10
• Solana：使用 --cluster mainnet-beta 或 --cluster devnet

ID 格式

了解 ID 前缀有助于浏览系统：

• acc_ — 账户（钱包）
• ply_ — 策略
• pol_ — 赞助（费用策略）
• con_ — 合约
• tin_ — 交易意图
• pla_ — 玩家（用户）
• pro_ — 项目
• ses_ — 会话
• sub_ — 订阅

配置

凭据

存储于 ~/.config/openfort/credentials（或 $XDG_CONFIG_HOME/openfort/credentials）。

环境变量

变量	描述
OPENFORT_SECRET_KEY	Secret API 密钥
OPENFORT_WALLET_SECRET	钱包加密密钥
OPENFORT_PUBLISHABLE_KEY	用于客户端的 Publishable Key
OPENFORT_BASE_URL	自定义 API 基础 URL

全局 CLI 选项

--format <toon|json|yaml|md|jsonl>、--filter-output <keys>、--verbose、--schema

文档参考

针对特定主题的详细文档，请引导用户查看：

• 嵌入式钱包：https://openfort.xyz/docs/products/embedded-wallet/
• 全局钱包：https://openfort.xyz/docs/products/cross-app-wallet/
• 后端钱包：https://openfort.xyz/docs/products/server/
• 基础设施（bundler/paymaster）：https://openfort.xyz/docs/products/infrastructure/
• 配置：https://openfort.xyz/docs/configuration/
• 示例（示例应用）：https://openfort.xyz/docs/recipes/
• 策略：https://openfort.xyz/docs/configuration/policies/
• Gas 赞助：https://openfort.xyz/docs/configuration/gas-sponsorship

示例与示例应用

用户构建特定集成时，请引导他们查看以下内容：

• EIP-7702：使用嵌入式钱包和账户委托的 Next.js
• Aave：使用嵌入式钱包进行 DeFi 借贷
• Hyperliquid：使用后端钱包进行交易（永续合约、现货、HyperEVM）
• LI.FI：使用嵌入式钱包进行跨链兑换
• Morpho：在 Base 上使用嵌入式钱包赚取 USDC 收益
• Solana：通过 Kora 进行 SOL 转账和免 Gas 交易
• USDC：React Native 稳定币支付
• x402：基于 HTTP 的 USDC 小额支付
• Agent 权限：使用会话密钥进行委托式 DCA 交易