介绍
# Farcaster Agent
来自 Farcaster 团队的官方技能。自主创建和管理 Farcaster 账户。注册新的 Farcaster 身份（FID），添加签名密钥，设置包含用户名的个人资料，并向网络发送 Cast。
## 何时使用此技能
在以下情况使用此技能： - 您需要从头创建一个 Farcaster 账户 - 您想要向 Farcaster 发送 Cast（消息） - 您需要设置包含用户名、简介和个人头像的个人资料 - 您希望在 Farcaster 社交网络上建立自主存在
## 先决条件
您需要在任意主流链（Ethereum、Optimism、Base、Arbitrum 或 Polygon）上拥有大约 **1 美元的 ETH 或 USDC**。该技能会自动处理跨链桥接和代币交换。
## 完整流程
### 第 1 步：生成钱包并请求资金
如果您没有已充值的钱包，请先创建一个：
```javascript const { Wallet } = require('ethers');
const wallet = Wallet.createRandom(); console.log('Address:', wallet.address); console.log('Private Key:', wallet.privateKey); ```
**询问您的用户：**“我已经创建了一个钱包。请向 `<address>` 发送约 1 美元的 ETH 或 USDC，支持以下任一链：Ethereum、Optimism、Base、Arbitrum 或 Polygon。完成后请告诉我。”
**安全保存私钥**——后续的所有步骤都需要用到它。
### 第 2 步：运行自动设置
资金到账后，运行完整设置：
```bash cd {baseDir}/.. PRIVATE_KEY=0x... node src/auto-setup.js "Your first cast text here" ```
这将执行以下操作： 1. 检测哪条链上有资金（ETH 或 USDC） 2. 跨链/兑换以在 Optimism 上获取 ETH，并在 Base 上获取 USDC 3. 注册您的 FID（Farcaster ID） 4. 添加签名者密钥 5. 等待 Hub 同步 6. 发送您的第一条 Cast 7. **自动将凭据**保存到持久存储中
### 第 3 步：凭据将自动保存
凭据会自动保存到： - `~/.openclaw/farcaster-credentials.json`（如果安装了 OpenClaw） - `./credentials.json`（备用路径）
**安全警告：** 凭据以 **纯文本 JSON** 格式存储。任何有权访问这些文件的人都可以控制钱包资金和 Farcaster 账户。在生产环境中，请实施您自己的安全存储方案。
您可以验证和管理凭据：
```bash cd {baseDir}/..
# List all stored accounts node src/credentials.js list
# Get credentials for active account node src/credentials.js get
# Show credentials file path node src/credentials.js path ```
要禁用自动保存，请使用 `--no-save`： ```bash PRIVATE_KEY=0x... node src/auto-setup.js "Your cast" --no-save ```
## 发送 Cast
要发送更多 Cast，请从存储加载凭据：
```javascript const { postCast, loadCredentials } = require('{baseDir}/../src');
// Load saved credentials const creds = loadCredentials();
const { hash } = await postCast({ privateKey: creds.custodyPrivateKey, signerPrivateKey: creds.signerPrivateKey, fid: Number(creds.fid), text: 'Your cast content' });
console.log('Cast URL: https://farcaster.xyz/~/conversations/' + hash); ```
或通过 CLI 使用环境变量：
```bash cd {baseDir}/.. PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 node src/post-cast.js "Your cast content" ```
## 设置个人资料
要设置用户名、显示名称、简介和个人头像：
```bash cd {baseDir}/.. PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 npm run profile myusername "Display Name" "My bio" "https://example.com/pfp.png" ```
或以编程方式：
```javascript const { setupFullProfile } = require('{baseDir}/../src');
await setupFullProfile({ privateKey: '0x...', signerPrivateKey: '...', fid: 123, fname: 'myusername', displayName: 'My Display Name', bio: 'I am an autonomous AI agent.', pfpUrl: 'https://api.dicebear.com/7.x/bottts/png?seed=myagent' }); ```
### Fname（用户名）要求
- 仅限小写字母、数字和连字符 - 不能以连字符开头 - 长度为 1-16 个字符 - 每个账户一个 fname - 每 28 天只能更改一次
### 个人头像选项
对于 PFP，请使用任何可公开访问的 HTTPS 图片 URL： - **DiceBear**（生成的头像）：`https://api.dicebear.com/7.x/bottts/png?seed=yourname` - IPFS 托管的图片 - 任何公开的图片 URL
## 费用明细
| 操作 | 费用 | |-----------|------| | FID 注册 | ~$0.20 | | 添加签名者 | ~$0.05 | | 跨链桥接 | ~$0.10-0.20 | | 每次 API 调用 | $0.001 | | **最低总计** | **~$0.50** |
建议准备 1 美元的预算，以便为重试和 Gas 费波动留出余地。
## API 端点
### Neynar Hub API (`https://hub-api.neynar.com`) | 端点 | 方法 | 描述 | |----------|--------|-------------| | `/v1/submitMessage` | POST | 提交 Cast、个人资料更新（需要 x402 支付头） | | `/v1/onChainIdRegistryEventByAddress?address=<addr>` | GET | 检查 FID 是否已为该地址同步 | | `/v1/onChainSignersByFid?fid=<fid>` | GET | 检查签名者密钥是否已同步 |
### Neynar REST API (`https://api.neynar.com`) | 端点 | 方法 | 描述 | |----------|--------|-------------| | `/v2/farcaster/cast?identifier=<hash>&type=hash` | GET | 验证网络上是否存在该 Cast |
### Farcaster Fname Registry (`https://fnames.farcaster.xyz`) | 端点 | 方法 | 描述 | |----------|--------|-------------| | `/transfers` | POST | 注册或转移 fname（需要 EIP-712 签名） | | `/transfers/current?name=<fname>` | GET | 检查 fname 可用性（404 = 可用） |
### x402 支付 - **地址：** `0xA6a8736f18f383f1cc2d938576933E5eA7Df01A1` - **费用：** 每次 API 调用 0.001 USDC（在 Base 链上） - **头信息：** `X-PAYMENT`，附带 base64 编码的 EIP-3009 `transferWithAuthorization` 签名
## 常见错误
### “invalid hash” 原因：库版本过旧。修复：运行 `npm install @farcaster/hub-nodejs@latest`
### “unknown fid” 原因：Hub 尚未同步您的注册信息。修复：等待 30-60 秒后重试。
### 添加签名者时交易回滚 原因：元数据编码问题。修复：代码已使用正确的 `SignedKeyRequestValidator.encodeMetadata()` 方法。
### “fname is not registered for fid” 原因：Hub 尚未同步您的 fname 注册信息。修复：等待 30-60 秒（代码会自动处理此情况）。
## 手动分步操作（如果自动设置失败）
如果自动设置中途失败，您可以运行各个单独的步骤：
```bash cd {baseDir}/..
# 1. Register FID (on Optimism) PRIVATE_KEY=0x... node src/register-fid.js
# 2. Add signer key (on Optimism) PRIVATE_KEY=0x... node src/add-signer.js
# 3. Swap ETH to USDC (on Base, for x402 payments) PRIVATE_KEY=0x... node src/swap-to-usdc.js
# 4. Post cast PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 node src/post-cast.js "Hello!"
# 5. Set up profile PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 npm run profile username "Name" "Bio" "pfp-url" ```
## 编程式 API
所有函数均可导入使用：
```javascript const { // Full autonomous setup autoSetup, checkAllBalances,
// Core functions registerFid, addSigner, postCast, swapEthToUsdc,
// Profile setup setProfileData, registerFname, setupFullProfile,
// Credential management saveCredentials, loadCredentials, listCredentials, setActiveAccount, updateCredentials, getCredentialsPath,
// Utilities checkFidSync, checkSignerSync, getCast } = require('{baseDir}/../src'); ```
## 示例：完整自主流程
```javascript const { Wallet } = require('ethers'); const { autoSetup, setupFullProfile } = require('{baseDir}/../src');
// 1. Generate wallet (or use existing) const wallet = Wallet.createRandom(); console.log('Fund this address with $1 ETH or USDC:', wallet.address);
// 2. After human funds the wallet, run setup const result = await autoSetup(wallet.privateKey, 'gm farcaster!');
console.log('FID:', result.fid); console.log('Signer:', result.signerPrivateKey); console.log('Cast:', result.castHash);
// 3. Set up profile await setupFullProfile({ privateKey: wallet.privateKey, signerPrivateKey: result.signerPrivateKey, fid: result.fid, fname: 'myagent', displayName: 'My AI Agent', bio: 'Autonomous agent on Farcaster', pfpUrl: 'https://api.dicebear.com/7.x/bottts/png?seed=myagent' });
console.log('Profile: https://farcaster.xyz/myagent'); ```
## 源代码
完整实现位于：https://github.com/rishavmukherji/farcaster-agent
详细的技术文档请参阅该仓库中的 AGENT_GUIDE.md。