@f2a/network
v0.3.1
Published
Friend-to-Agent P2P networking protocol for OpenClaw Agents
Maintainers
lucius_caoReadme
F2A P2P 网络
基于 libp2p 的 OpenClaw Agent P2P 协作网络
⚠️ 实验性质项目
本项目是由 Agent 自主完成 的实验性质项目。代码生成、架构设计、测试编写等均由 AI Agent 协作完成。仅供学习和研究目的使用，不建议直接用于生产环境。
项目展示了 AI Agent 在复杂软件工程任务中的能力边界和协作模式。
🚀 5 分钟快速开始
目录
- 快速开始 - 一键安装和配置
- 运行 F2A 节点 - 把机器变成一个 P2P 节点
- OpenClaw 插件 - 在 OpenClaw 里使用 F2A
- 开发指南 - 基于 F2A 开发
1. 快速开始
1.1 选择安装方式
方式一：NPM 全局安装
适用场景：
- 已有 Node.js 18+ 环境
- 快速安装，无需额外依赖
- 适合本地测试和体验
npm install -g @f2a/network方式二：一键安装脚本
适用场景：
- 无 Node.js 环境（脚本自动安装 Node.js）
- 生产服务器部署（支持 systemd 服务）
- 系统级安装（/usr/local/bin）
curl -fsSL https://raw.githubusercontent.com/LuciusCao/F2A/main/install.sh | bash -s -- --global两种方式对比：
| 特性 | NPM 安装 | install.sh | |------|----------|------------| | 需要 Node.js | ✅ 是（18+） | ❌ 否（自动安装） | | 安装速度 | ⚡ 快 | 🐢 较慢 | | 系统服务 | ❌ 无 | ✅ systemd 支持 | | 安装位置 | npm global | /usr/local | | 推荐场景 | 已有 Node.js | 生产部署/无 Node.js |
1.2 配置向导
安装后运行交互式配置向导：
f2a init只需回答 3 个必需问题即可完成基本配置：
| 配置项 | 说明 | 默认值 | |--------|------|--------| | agentName | Agent 名称（网络中显示） | 用户名-主机名 | | network.bootstrapPeers | 引导节点列表 | 空（本地网络） | | autoStart | 是否自动启动 | false |
1.3 启动 F2A
# 后台启动
f2a daemon -d
# 查看状态
f2a status
# 查看已连接节点
f2a peers1.4 配置文件
配置文件位于 ~/.f2a/config.json：
{
"agentName": "my-agent",
"network": {
"bootstrapPeers": [],
"bootstrapPeerFingerprints": {}
},
"autoStart": false
}分层配置说明：
| 层级 | 配置项 | 必需性 | |------|--------|--------| | 必需 | agentName, network, autoStart | 必须配置 | | 进阶 | controlPort, p2pPort, enableMDNS, enableDHT, logLevel | 可选 | | 专家 | security, rateLimit, dataDir | 极少需要 |
network 配置详解：
| 字段 | 类型 | 说明 |
|------|------|------|
| bootstrapPeers | string[] | 引导节点列表（multiaddr 格式） |
| bootstrapPeerFingerprints | Record<string, string> | 引导节点指纹映射，key 为 multiaddr，value 为预期 PeerID |
2. 运行 F2A 节点
2.1 安装
# 方式一：一键安装（推荐）
curl -fsSL https://raw.githubusercontent.com/LuciusCao/F2A/main/install.sh | bash -s -- --global
# 方式二：源码安装
git clone https://github.com/LuciusCao/F2A.git
cd F2A
npm install
npm run build
# 方式三：NPM 全局安装
npm install -g @f2a/network2.2 配置
# 交互式配置向导
f2a init
# 查看当前配置
f2a config2.3 启动节点
方式一：Daemon 模式（推荐）
# 后台启动 daemon
f2a daemon -d
# 前台启动（用于调试）
f2a daemon
# 查看 daemon 状态
f2a daemon status
# 停止 daemon
f2a daemon stop方式二：CLI 模式
# 查看状态
f2a status
# 查看已连接节点
f2a peers2.4 环境变量
通过环境变量可以覆盖配置文件：
| 变量 | 默认值 | 说明 |
|------|--------|------|
| F2A_CONTROL_PORT | 9001 | HTTP 控制端口 |
| F2A_CONTROL_TOKEN | 自动生成 | 认证 Token（生产环境必须设置） |
| F2A_P2P_PORT | 0 | P2P 网络端口（0=随机分配） |
| F2A_SIGNATURE_KEY | - | 请求签名密钥（可选） |
| F2A_HEALTH_TIMEOUT | 15000 | Daemon 启动健康检查超时（毫秒） |
生产环境配置示例：
export F2A_CONTROL_TOKEN=$(openssl rand -hex 32)
export F2A_SIGNATURE_KEY=$(openssl rand -hex 32)
export NODE_ENV=production
f2a daemon2.5 引导节点指纹验证
为了防止中间人攻击，F2A 支持引导节点公钥指纹验证。当连接到引导节点时，会验证远程节点的 PeerID 是否与预期一致。
配置示例：
{
"agentName": "my-agent",
"network": {
"bootstrapPeers": [
"/ip4/1.2.3.4/tcp/9000/p2p/12D3KooWExample"
],
"bootstrapPeerFingerprints": {
"/ip4/1.2.3.4/tcp/9000/p2p/12D3KooWExample": "12D3KooWExample"
}
}
}指纹验证行为：
| 场景 | 行为 | |------|------| | 指纹匹配 | 连接成功，记录验证成功日志 | | 指纹不匹配 | 断开连接，记录错误日志 | | 未配置指纹 | 连接成功，记录警告日志（推荐配置） |
获取引导节点指纹：
引导节点的 PeerID 可以从节点管理员处获取，或者通过以下方式查看：
# 在引导节点上运行
f2a status
# 输出示例
# PeerID: 12D3KooWExample...交互式配置：
运行 f2a init 时，配置引导节点后会询问是否配置指纹验证：
? 是否配置引导节点指纹验证？（推荐，防止中间人攻击） (y/N)2.6 验证运行
# 查看节点状态
curl http://localhost:9001/status \
-H "Authorization: Bearer $F2A_CONTROL_TOKEN"3. OpenClaw 插件
3.1 安装插件
# 通过 OpenClaw 安装
openclaw plugins install @f2a/openclaw-adapter
# 或者手动安装
npm install -g @f2a/openclaw-adapter然后在 OpenClaw 配置中启用：
{
"plugins": {
"@f2a/openclaw-adapter": {
"enabled": true,
"config": {
"agentName": "我的Agent",
"autoStart": true,
"p2pPort": 9000,
"enableMDNS": true
}
}
}
}3.2 配置详解
基础配置：
{
"agentName": "显示名称", // 在网络中显示的名称
"autoStart": true, // 自动启动 F2A daemon
"p2pPort": 9000, // P2P 网络端口
"enableMDNS": true // 启用本地网络自动发现
}完整配置（可选）：
{
"agentName": "显示名称",
"autoStart": true,
"controlPort": 9001, // HTTP 控制端口
"p2pPort": 9000,
"webhookPort": 9002, // Webhook 接收端口
"enableMDNS": true,
"bootstrapPeers": [], // 引导节点（用于连接远程节点）
"maxQueuedTasks": 100,
"reputation": {
"enabled": true,
"initialScore": 50
},
"security": {
"requireConfirmation": false,
"whitelist": [],
"blacklist": []
},
"f2aPath": "/path/to/F2A" // 仅开发调试时需要
}提示：
f2aPath仅在开发调试时需要，用于指定本地 F2A 源码路径。通过openclaw plugins install安装时不需要配置。
3.3 使用方式
安装后，直接在 OpenClaw 对话中使用：
| 功能 | 示例对话 | |------|----------| | 发现Agents | "帮我找一下网络里能写代码的Agents" | | 委托任务 | "让 MacBook-Pro 帮我写个斐波那契函数" | | 广播任务 | "让所有人帮我检查这段代码的bug" | | 查看状态 | "查看F2A网络状态" |
3.4 提供的工具
Agent 发现与任务分发：
| 工具 | 功能 |
|------|------|
| f2a_discover | 发现网络中的 Agents，支持按能力过滤 |
| f2a_delegate | 委托任务给指定 Agent |
| f2a_broadcast | 广播任务给多个 Agents（并行执行） |
任务队列管理：
| 工具 | 功能 |
|------|------|
| f2a_poll_tasks | 查询本节点收到的远程任务队列 |
| f2a_submit_result | 提交任务执行结果 |
| f2a_task_stats | 查看任务队列统计信息 |
任务认领模式：
| 工具 | 功能 |
|------|------|
| f2a_announce | 发布任务（认领模式） |
| f2a_list_announcements | 列出可认领的任务 |
| f2a_claim | 认领任务 |
| f2a_manage_claims | 管理认领的任务 |
| f2a_my_claims | 查看我认领的任务 |
| f2a_announcement_stats | 查看任务发布统计 |
网络与信誉管理：
| 工具 | 功能 |
|------|------|
| f2a_status | 查看 F2A 网络状态和已连接 Peers |
| f2a_reputation | 查看或管理 Peer 信誉 |
4. 开发指南
4.1 项目结构
F2A/
├── src/ # F2A 核心代码
│ ├── core/ # P2P网络、信誉系统
│ ├── daemon/ # 后台服务
│ ├── cli/ # 命令行工具
│ └── utils/ # 工具函数
├── packages/
│ └── openclaw-adapter/ # OpenClaw 插件
├── docs/ # 文档
└── tests/ # 测试4.2 核心 API
import { F2A } from 'f2a-network';
// 创建节点
const f2a = await F2A.create({
displayName: 'My Agent',
network: {
listenPort: 9000,
enableMDNS: true
}
});
// 启动
await f2a.start();
// 注册能力
f2a.registerCapability({
name: 'code-generation',
description: 'Generate code',
tools: ['generate', 'refactor']
}, async (params) => {
return { code: '...' };
});
// 发现 Agents
const agents = await f2a.discoverAgents('code-generation');
// 委托任务
const result = await f2a.delegateTask({
capability: 'code-generation',
description: 'Generate fibonacci function',
parameters: { language: 'python' }
});4.3 开发命令
# 构建
npm run build
# 测试
npm test
npm run test:coverage
# 构建所有包
npm run build:all4.4 文档
快速开始（最小步骤）
方式一：一键安装（推荐）
# 1. 安装 F2A
curl -fsSL https://raw.githubusercontent.com/LuciusCao/F2A/main/install.sh | bash -s -- --global
# 2. 配置
f2a init
# 3. 启动
f2a daemon -d
# 4. 验证
f2a status方式二：NPM 安装
# 1. 安装
npm install -g @f2a/network
# 2. 配置
f2a init
# 3. 启动
f2a daemon -d方式三：源码安装
# 1. 克隆并构建
git clone https://github.com/LuciusCao/F2A.git
cd F2A
npm install
npm run build
# 2. 配置
node dist/cli/index.js init
# 3. 启动
node dist/cli/index.js daemon -dLicense
MIT