名称： farcaster-agent
描述： 自动创建 Farcaster 账户并发布 Cast。来自 Farcaster 团队的官方技能。
元数据： {"openclaw":{"emoji":"🟣","requires":{"bins":["node","npm"],"env":[]},"install":[{"id":"npm","kind":"shell","command":"cd {baseDir}/.. && npm install","label":"安装依赖项"}]}}

Farcaster 智能体

来自 Farcaster 团队的官方技能。可自动创建和管理 Farcaster 账户。注册新的 Farcaster 身份（FID），添加签名密钥，设置包含用户名的个人资料，并向网络发布 Cast。

何时使用此技能

在以下场景中使用此技能：
- 需要从零开始创建 Farcaster 账户
- 想要向 Farcaster 发布 Cast（消息）
- 需要设置包含用户名、简介和个人头像的个人资料
- 希望在 Farcaster 社交网络上建立自动化存在

前提条件

您需要在任何主流链（以太坊、Optimism、Base、Arbitrum 或 Polygon）上拥有大约 1 美元的 ETH 或 USDC。本技能会自动处理跨链桥接和代币兑换。

完整流程

步骤 1：生成钱包并请求资金

如果您没有已注资的钱包，请先创建一个：

const { Wallet } = require('ethers');

const wallet = Wallet.createRandom();
console.log('地址:', wallet.address);
console.log('私钥:', wallet.privateKey);

向您的操作员请求： “我已创建一个钱包。请向 <地址> 发送约 1 美元的 ETH 或 USDC，支持以下任一链：以太坊、Optimism、Base、Arbitrum 或 Polygon。完成后请通知我。”

请安全保存私钥 —— 后续所有步骤都需要它。

步骤 2：运行自动设置

资金到位后，运行完整设置：

cd {baseDir}/..
PRIVATE_KEY=0x... node src/auto-setup.js "您的第一条 Cast 内容"

此命令将：
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 账户。生产环境中请自行实现安全存储方案。

您可以验证和管理凭证：

cd {baseDir}/..

# 列出所有已存储的账户
node src/credentials.js list

# 获取活跃账户的凭证
node src/credentials.js get

# 显示凭证文件路径
node src/credentials.js path

要禁用自动保存，请使用 --no-save 参数：

PRIVATE_KEY=0x... node src/auto-setup.js "您的 Cast" --no-save

发布 Cast

要发布更多 Cast，可以从存储中加载凭证：

const { postCast, loadCredentials } = require('{baseDir}/../src');

// 加载已保存的凭证
const creds = loadCredentials();

const { hash } = await postCast({
  privateKey: creds.custodyPrivateKey,
  signerPrivateKey: creds.signerPrivateKey,
  fid: Number(creds.fid),
  text: '您的 Cast 内容'
});

console.log('Cast 链接: https://farcaster.xyz/~/conversations/' + hash);

或者通过 CLI 使用环境变量：

cd {baseDir}/..
PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 node src/post-cast.js "您的 Cast 内容"

设置个人资料

要设置用户名、显示名称、简介和个人头像：

cd {baseDir}/..
PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 npm run profile myusername "显示名称" "我的简介" "https://example.com/pfp.png"

或者以编程方式：

const { setupFullProfile } = require('{baseDir}/../src');

await setupFullProfile({
  privateKey: '0x...',
  signerPrivateKey: '...',
  fid: 123,
  fname: 'myusername',
  displayName: '我的显示名称',
  bio: '我是一个自主的 AI 智能体。',
  pfpUrl: 'https://api.dicebear.com/7.x/bottts/png?seed=myagent'
});

Fname（用户名）要求

• 仅限小写字母、数字和连字符
• 不能以连字符开头
• 1-16 个字符
• 每个账户只能有一个 fname
• 每 28 天只能更改一次

个人头像选项

对于头像，可以使用任何可通过 HTTPS 公开访问的图片 URL：
- DiceBear（生成头像）：https://api.dicebear.com/7.x/bottts/png?seed=yourname
- IPFS 托管的图片
- 任何公开的图片 URL

成本明细

建议预算 1 美元，以应对重试和 Gas 费波动。

API 端点

Neynar Hub API (https://hub-api.neynar.com)

Neynar REST API (https://api.neynar.com)

Farcaster Fname 注册表 (https://fnames.farcaster.xyz)

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 秒（代码会自动处理此问题）。

手动分步操作（如果自动设置失败）

如果自动设置中途失败，您可以单独运行各个步骤：

cd {baseDir}/..

# 1. 注册 FID（在 Optimism 上）
PRIVATE_KEY=0x... node src/register-fid.js

# 2. 添加签名者密钥（在 Optimism 上）
PRIVATE_KEY=0x... node src/add-signer.js

# 3. 将 ETH 兑换为 USDC（在 Base 上，用于 x402 支付）
PRIVATE_KEY=0x... node src/swap-to-usdc.js

# 4. 发布 Cast
PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 node src/post-cast.js "你好！"

# 5. 设置个人资料
PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 npm run profile username "名称" "简介" "头像-url"

编程接口

所有函数均可导入使用：

const {
  // 完整的自主设置
  autoSetup,
  checkAllBalances,

  // 核心功能
  registerFid,
  addSigner,
  postCast,
  swapEthToUsdc,

  // 个人资料设置
  setProfileData,
  registerFname,
  setupFullProfile,

  // 凭证管理
  saveCredentials,
  loadCredentials,
  listCredentials,
  setActiveAccount,
  updateCredentials,
  getCredentialsPath,

  // 实用工具
  checkFidSync,
  checkSignerSync,
  getCast
} = require('{baseDir}/../src');

示例：完整自主流程

const { Wallet } = require('ethers');
const { autoSetup, setupFullProfile } = require('{baseDir}/../src');

// 1. 生成钱包（或使用现有钱包）
const wallet = Wallet.createRandom();
console.log('请向此地址注资 1 美元的 ETH 或 USDC:', wallet.address);

// 2. 在操作员注资后，运行设置
const result = await autoSetup(wallet.privateKey, 'gm farcaster!');

console.log('FID:', result.fid);
console.log('签名者:', result.signerPrivateKey);
console.log('Cast:', result.castHash);

// 3. 设置个人资料
await setupFullProfile({
  privateKey: wallet.privateKey,
  signerPrivateKey: result.signerPrivateKey,
  fid: result.fid,
  fname: 'myagent',
  displayName: '我的 AI 智能体',
  bio: 'Farcaster 上的自主智能体',
  pfpUrl: 'https://api.dicebear.com/7.x/bottts/png?seed=myagent'
});

console.log('个人资料: https://farcaster.xyz/myagent');

源代码

完整实现位于：https://github.com/rishavmukherji/farcaster-agent

详细技术文档，请参阅该仓库中的 AGENT_GUIDE.md 文件。