multiclaws 0.4.9 → 0.4.11

package/README.md

@@ -1,75 +1,9 @@
 # MultiClaws
 
-Multi-agent collaboration plugin for [OpenClaw](https://openclaw.ai). Connect multiple OpenClaw instances into a team so their AIs can delegate tasks to each other using the [A2A protocol](https://google.github.io/A2A/).
+Multi-agent collaboration plugin for [OpenClaw](https://openclaw.ai). Connect multiple OpenClaw instances into a team and delegate tasks between them using the [A2A protocol](https://google.github.io/A2A/).
 
 [中文文档](README.zh-CN.md)
 
-## The Core Idea
-
-Every OpenClaw instance is a gateway to data and systems that only *that machine* can reach — local files, logged-in accounts, connected devices, internal networks. MultiClaws connects these isolated islands so AI agents can collaborate across them.
-
-**The division of labor isn't about who is smarter. It's about who has the key.**
-
-- Your laptop has your codebase and personal email
-- Your colleague's machine has their Google Workspace and internal database access
-- The office server has the production logs
-
-None of these can reach the others directly. MultiClaws lets each agent do what only it can do, and routes the results back to whoever asked.
-
-## Two Core Features
-
-### 1. Profiles Make Every OpenClaw Discoverable
-
-Each OpenClaw instance has a profile — a bio written in plain text that describes what data and systems it can access. When your agent needs to get something done, it reads the team profiles and figures out who to ask. No manual routing, no hardcoded assignments.
-
-The profile is what turns each OpenClaw into a callable unit for others. Your colleague writes "I have access to Google Workspace and the sales spreadsheets" in their bio — and your agent can now delegate Google Sheets tasks to them, without you configuring anything. Add a new teammate to the team, their profile appears, your agent starts routing tasks to them automatically.
-
-Getting started takes one sentence to your AI. No config files, no YAML, no A2A protocol knowledge required. The profile is the only interface.
-
-### 2. Collaborate by Who Has the Key, Not Who Is Better
-
-Traditional task routing assumes you split work by skill: "this agent is good at data, that one is good at writing." That's the wrong model for distributed systems.
-
-Each OpenClaw can only reach what its own machine can reach. The right question isn't *who is more capable* — it's *who has access*. MultiClaws routes tasks based on data ownership: your colleague's agent handles their Google Sheets because they're the only one logged in. The office server's agent handles production logs because it's the only one on that network.
-
-**The profile bio is a declaration of access, not a resume.**
-
-## Example
-
-*Eric needs a monthly business review report.*
-
-```
-A (Eric's MacBook)
-  → has: local git history, personal Telegram, own email
-
-B (zxj's Windows PC)
-  → has: Google Sheets with sales data (logged in as zxj)
-
-C (ljl's machine)
-  → has: internal OA system (browser already logged in), local MySQL
-```
-
-Eric tells his AI: *"Generate this month's business review."*
-
-```
-A reads team profiles
-  → B's bio: "access to Google Workspace, sales spreadsheets"
-  → C's bio: "access to internal OA system and local database"
-
-A delegates:
-  → B: "pull this month's sales figures from Google Sheets"
-  → C: "get project status and attendance from the OA system"
-  → A: reads local git log for code activity
-
-B uses its own Google credentials → returns sales data
-C uses its own logged-in browser → returns OA data
-A merges all three → generates the report
-```
-
-B can also delegate further. If B needs a chart generated and sees from the team profiles that D has that capability, B delegates to D autonomously — without A needing to orchestrate it.
-
-**The profile bio describes what data and systems each instance can access.** That's how agents decide who to ask.
-
 ## Installation
 
 Just tell your AI:
@@ -84,19 +18,14 @@ Everything works through natural language:
 
 - **"Create a team called my-team"** — creates a team and generates an invite code
 - **"Join team with invite code mc:xxxxx"** — join a teammate's team
-- **"Ask Bob to pull the sales data"** — delegate a task to a teammate's AI
-- **"Show all agents"** — list team members and their data access
-
-## Roadmap
+- **"Ask Bob to summarize the latest report"** — delegate a task to a teammate's AI
+- **"Show all agents"** — list team members and their capabilities
 
-### Async Delegation
-Currently, task delegation is synchronous — the delegating agent waits for the result before continuing. The next major version will support fire-and-forget delegation: dispatch multiple tasks to different agents simultaneously, receive results as push notifications, and aggregate them when all are ready. This enables true parallel execution across agents.
+## How It Works
 
-### Multi-turn Collaboration
-Today each delegation is a single round-trip. Planned support for multi-turn sessions where agents can exchange follow-up messages within the same context — useful for tasks that require clarification, intermediate feedback, or iterative refinement between agents.
+MultiClaws enables multiple OpenClaw instances to collaborate as a team. Each instance acts as both a client (delegating tasks) and a server (receiving tasks from others). Tasks are executed by the remote AI and results are returned directly.
 
-### Permissions
-Currently any agent with a valid invite code can send tasks to your OpenClaw. A permission layer is planned: define which agents are allowed to delegate to you, what kinds of tasks they can request, and whether approval is required before execution.
+Works out of the box on the same local network. Cross-network collaboration is also supported.
 
 ## Documentation
 

package/README.zh-CN.md

@@ -1,75 +1,9 @@
 # MultiClaws
 
-[OpenClaw](https://openclaw.ai) 多智能体协作插件。将多个 OpenClaw 实例组成团队，通过 [A2A 协议](https://google.github.io/A2A/) 让各个 AI 互相委派任务。
+[OpenClaw](https://openclaw.ai) 多智能体协作插件。将多个 OpenClaw 实例组成团队，通过 [A2A 协议](https://google.github.io/A2A/) 互相委派任务。
 
 [English](README.md)
 
-## 核心理念
-
-每个 OpenClaw 实例都是一扇门——只有*那台机器*才能打开的门：本地文件、已登录的账号、连接的设备、内部网络。MultiClaws 把这些孤立的数据孤岛连接起来，让 AI 跨越它们协作完成任务。
-
-**分工的依据不是谁更擅长，而是谁有钥匙。**
-
-- 你的电脑有你的代码仓库和个人邮件
-- 同事的机器有他的 Google Workspace 和内部数据库权限
-- 办公室服务器有生产日志
-
-这些数据互相访问不到。MultiClaws 让每个 Agent 只做它能做的事，把结果汇总回发起方。
-
-## 两个核心产品特色
-
-### 一、档案让每个 OpenClaw 对外可发现
-
-每个 OpenClaw 实例都有一个档案——一段纯文本的 bio，描述这台机器能访问哪些数据和系统。当你的 Agent 需要完成某件事时，它读取团队档案，自己判断找谁。无需手动路由，无需硬编码分配。
-
-档案就是让每个 OpenClaw 对其他人可调用的接口。同事在 bio 里写"我可以访问 Google Workspace 和销售数据表格"——你的 Agent 就能把 Google Sheets 相关任务委派给他，不需要你做任何配置。新队友加入团队，档案出现，你的 Agent 自动开始向他路由任务。
-
-上手只需要对 AI 说一句话，没有配置文件、没有 YAML、不需要了解 A2A 协议。档案是唯一的接口。
-
-### 二、按"谁有钥匙"分工，而不是"谁更擅长"
-
-传统的任务路由假设按能力分工："这个 Agent 擅长数据，那个擅长写作。"对于分布式系统，这是错误的模型。
-
-每个 OpenClaw 只能访问它所在机器能访问的东西。正确的问题不是*谁更有能力*，而是*谁有权限*。MultiClaws 按数据所有权路由任务：同事的 Agent 处理他们的 Google Sheets，因为只有他们登录了；办公室服务器的 Agent 处理生产日志，因为只有它在那个网络里。
-
-**档案里的 bio 是访问权限的声明，不是简历。**
-
-## 案例
-
-*Eric 需要生成一份月度业务复盘报告。*
-
-```
-A（Eric 的 MacBook）
-  → 有：本地 git 记录、个人 Telegram、自己的邮件
-
-B（zxj 的 Windows 电脑）
-  → 有：Google Sheets 销售数据（以 zxj 账号登录）
-
-C（ljl 的机器）
-  → 有：内部 OA 系统（浏览器已登录）、本地 MySQL
-```
-
-Eric 对自己的 AI 说："帮我生成本月复盘报告。"
-
-```
-A 读取团队档案
-  → B 的 bio："可访问 Google Workspace、销售数据表格"
-  → C 的 bio："可访问内部 OA 系统和本地数据库"
-
-A 拆解任务：
-  → 委派 B："从 Google Sheets 拿本月销售数字"
-  → 委派 C："从 OA 系统查项目进度和出勤情况"
-  → 自己读本地 git log 获取代码提交记录
-
-B 用自己的 Google 凭据读取表格 → 返回数据
-C 用自己已登录的浏览器抓取 OA → 返回数据
-A 合并三份数据 → 生成报告
-```
-
-B 还可以进一步委派。如果 B 需要生成图表，看到团队档案里 D 有这个能力，B 会自主委派给 D——不需要 A 来调度。
-
-**档案里的 bio 描述的是每个实例能访问什么数据和系统**，这就是 Agent 决定找谁的依据。
-
 ## 安装
 
 对你的 AI 说：
@@ -84,19 +18,14 @@ AI 会自动完成安装、配置和档案生成，无需手动修改任何文
 
 - **「创建一个叫 my-team 的团队」** — 创建团队并获取邀请码
 - **「用邀请码 mc:xxxxx 加入团队」** — 加入队友的团队
-- **「让 Bob 去拿销售数据」** — 把任务委派给队友的 AI
-- **「显示所有智能体」** — 查看团队成员及其数据访问权限
-
-## 后续计划
+- **「让 Bob 总结一下最新报告」** — 把任务委派给队友的 AI
+- **「显示所有智能体」** — 查看团队成员及其能力
 
-### 异步委派
-当前委派是同步的——发起方等待结果返回后才继续。下一个大版本将支持异步委派：同时向多个 Agent 派发任务，结果通过推送通知返回，全部完成后统一汇总。这将实现真正的跨 Agent 并行执行。
+## 工作原理
 
-### 多轮协作
-当前每次委派是单次请求-响应。计划支持多轮 Session：Agent 之间可以在同一上下文中来回交流，适用于需要补充信息、中间反馈或多轮迭代的任务。
+MultiClaws 让多个 OpenClaw 实例作为一个团队协作。每个实例既可以作为客户端（委派任务），也可以作为服务端（接收他人任务）。任务由远端 AI 执行，结果直接返回。
 
-### 权限管理
-当前持有邀请码的任何 Agent 都可以向你的 OpenClaw 发送任务。计划添加权限层：定义哪些 Agent 可以委派任务给你、允许哪类任务、以及是否需要人工确认才能执行。
+同局域网开箱即用，也支持跨网络协作。
 
 ## 详细文档
 

package/dist/index.js

@@ -4,12 +4,38 @@ const handlers_1 = require("./gateway/handlers");
 const multiclaws_service_1 = require("./service/multiclaws-service");
 const logger_1 = require("./infra/logger");
 const telemetry_1 = require("./infra/telemetry");
+/** Default FRP tunnel config for demo/testing */
+const DEFAULT_TUNNEL = {
+    type: "frp",
+    serverAddr: "39.105.143.2",
+    serverPort: 7000,
+    token: "jushi@5202fRp",
+    portRangeStart: 7011,
+    portRangeEnd: 7020,
+};
 function readConfig(api) {
     const raw = (api.pluginConfig ?? {});
+    let tunnel;
+    const rawTunnel = raw.tunnel;
+    if (rawTunnel && rawTunnel.type === "frp") {
+        tunnel = {
+            type: "frp",
+            serverAddr: typeof rawTunnel.serverAddr === "string" ? rawTunnel.serverAddr : DEFAULT_TUNNEL.serverAddr,
+            serverPort: typeof rawTunnel.serverPort === "number" ? rawTunnel.serverPort : DEFAULT_TUNNEL.serverPort,
+            token: typeof rawTunnel.token === "string" ? rawTunnel.token : DEFAULT_TUNNEL.token,
+            portRangeStart: typeof rawTunnel.portRangeStart === "number" ? rawTunnel.portRangeStart : DEFAULT_TUNNEL.portRangeStart,
+            portRangeEnd: typeof rawTunnel.portRangeEnd === "number" ? rawTunnel.portRangeEnd : DEFAULT_TUNNEL.portRangeEnd,
+        };
+    }
+    else {
+        // No tunnel configured — use built-in default for demo
+        tunnel = { ...DEFAULT_TUNNEL };
+    }
     return {
         port: typeof raw.port === "number" ? raw.port : undefined,
         displayName: typeof raw.displayName === "string" ? raw.displayName : undefined,
         selfUrl: typeof raw.selfUrl === "string" ? raw.selfUrl : undefined,
+        tunnel,
         telemetry: {
             consoleExporter: typeof raw.telemetry?.consoleExporter === "boolean"
                 ? Boolean(raw.telemetry.consoleExporter)
@@ -332,6 +358,7 @@ const plugin = {
                     port: config.port,
                     displayName: config.displayName,
                     selfUrl: config.selfUrl,
+                    tunnel: config.tunnel,
                     gatewayConfig: gatewayConfig ?? undefined,
                     logger: structured.logger,
                 });
@@ -392,7 +419,7 @@ multiclaws 插件刚安装，需要在本次对话中完成以下初始化流程
 2. 向用户展示生成的档案，并逐一确认以下三项（名字和 bio 需要用户明确回答）：
    - **名字**：展示推断出的名字，询问是否需要修改
    - **Bio**：展示生成的 bio，询问是否需要修改
-   - **网络情况**：告知用户「同局域网开箱即用；跨网络需安装 Tailscale 并重启 OpenClaw，下载地址：https://tailscale.com/download」，无需用户回答
+   - **网络情况**：告知用户「所有实例通过 FRP 隧道通信，需在插件配置中设置 tunnel 字段（包含 frps 服务器地址、端口、token 和可用端口范围），frpc 会自动下载安装」，无需用户回答
 
 3. 根据用户对名字和 bio 的回答更新档案内容（如需修改），然后调用 \`multiclaws_profile_set(ownerName="...", bio="...")\` 保存。
 

package/dist/infra/frp.d.ts

@@ -0,0 +1,55 @@
+export type FrpTunnelConfig = {
+    serverAddr: string;
+    serverPort: number;
+    token: string;
+    portRangeStart: number;
+    portRangeEnd: number;
+};
+export type FrpTunnelStatus = {
+    status: "running";
+    publicUrl: string;
+    remotePort: number;
+} | {
+    status: "starting";
+} | {
+    status: "stopped";
+} | {
+    status: "error";
+    reason: string;
+};
+type Logger = {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+};
+/** Check if frpc binary is available in system PATH */
+export declare function detectFrpc(): boolean;
+export declare class FrpTunnelManager {
+    private readonly config;
+    private readonly localPort;
+    private readonly stateDir;
+    private readonly logger;
+    private frpcProcess;
+    private healthCheckTimer;
+    private _status;
+    private _publicUrl;
+    private configPath;
+    private adminPort;
+    constructor(opts: {
+        config: FrpTunnelConfig;
+        localPort: number;
+        stateDir: string;
+        logger?: Logger;
+    });
+    get status(): FrpTunnelStatus;
+    get publicUrl(): string | null;
+    start(): Promise<string>;
+    stop(): Promise<void>;
+    private tryStartWithPort;
+    private waitForProxy;
+    private startHealthCheck;
+    private killProcess;
+    private ensureFrpcBinary;
+    private downloadFrpc;
+}
+export {};

package/dist/infra/frp.js

@@ -0,0 +1,384 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrpTunnelManager = void 0;
+exports.detectFrpc = detectFrpc;
+const node_child_process_1 = require("node:child_process");
+const node_net_1 = __importDefault(require("node:net"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+/* ------------------------------------------------------------------ */
+/*  Constants                                                          */
+/* ------------------------------------------------------------------ */
+const FRP_VERSION = "0.61.1";
+const ADMIN_API_POLL_INTERVAL_MS = 1_000;
+const ADMIN_API_POLL_MAX_RETRIES = 15;
+const HEALTH_CHECK_INTERVAL_MS = 30_000;
+const PROCESS_KILL_TIMEOUT_MS = 3_000;
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                            */
+/* ------------------------------------------------------------------ */
+function run(cmd, timeoutMs = 5_000) {
+    return (0, node_child_process_1.execSync)(cmd, { timeout: timeoutMs, stdio: ["ignore", "pipe", "pipe"] })
+        .toString()
+        .trim();
+}
+/** Check if frpc binary is available in system PATH */
+function detectFrpc() {
+    try {
+        const cmd = process.platform === "win32" ? "where frpc" : "which frpc";
+        run(cmd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Find an available port by briefly binding to port 0 */
+async function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = node_net_1.default.createServer();
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                server.close(() => reject(new Error("failed to get port")));
+                return;
+            }
+            const port = addr.port;
+            server.close(() => resolve(port));
+        });
+        server.on("error", reject);
+    });
+}
+/** Parse remote port from frpc admin API response (format: ":12345" or "[::]:12345") */
+function parseRemotePort(remoteAddr) {
+    const colonIdx = remoteAddr.lastIndexOf(":");
+    if (colonIdx === -1)
+        throw new Error(`unexpected remote_addr format: ${remoteAddr}`);
+    const portStr = remoteAddr.slice(colonIdx + 1);
+    const port = parseInt(portStr, 10);
+    if (isNaN(port) || port <= 0)
+        throw new Error(`invalid port in remote_addr: ${remoteAddr}`);
+    return port;
+}
+/** Get platform identifier for frp release download */
+function getFrpPlatform() {
+    const platform = process.platform;
+    const arch = process.arch;
+    let frpOs;
+    if (platform === "linux")
+        frpOs = "linux";
+    else if (platform === "darwin")
+        frpOs = "darwin";
+    else if (platform === "win32")
+        frpOs = "windows";
+    else
+        throw new Error(`unsupported platform: ${platform}`);
+    let frpArch;
+    if (arch === "x64")
+        frpArch = "amd64";
+    else if (arch === "arm64")
+        frpArch = "arm64";
+    else if (arch === "ia32")
+        frpArch = "386";
+    else
+        throw new Error(`unsupported architecture: ${arch}`);
+    const ext = platform === "win32" ? "zip" : "tar.gz";
+    return { os: frpOs, arch: frpArch, ext };
+}
+/** Shuffle an array in place (Fisher-Yates) */
+function shuffle(arr) {
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+    return arr;
+}
+/** Generate a range of numbers [start, end) */
+function range(start, end) {
+    const result = [];
+    for (let i = start; i < end; i++)
+        result.push(i);
+    return result;
+}
+/* ------------------------------------------------------------------ */
+/*  FrpTunnelManager                                                   */
+/* ------------------------------------------------------------------ */
+class FrpTunnelManager {
+    config;
+    localPort;
+    stateDir;
+    logger;
+    frpcProcess = null;
+    healthCheckTimer = null;
+    _status = { status: "stopped" };
+    _publicUrl = null;
+    configPath = "";
+    adminPort = 0;
+    constructor(opts) {
+        this.config = opts.config;
+        this.localPort = opts.localPort;
+        this.stateDir = opts.stateDir;
+        this.logger = opts.logger ?? {
+            info: () => { },
+            warn: () => { },
+            error: () => { },
+        };
+    }
+    get status() {
+        return this._status;
+    }
+    get publicUrl() {
+        return this._publicUrl;
+    }
+    /* ── Start ─────────────────────────────────────────────────────── */
+    async start() {
+        this._status = { status: "starting" };
+        // 1. Ensure frpc binary exists
+        const frpcPath = await this.ensureFrpcBinary();
+        this.logger.info(`[frp] using frpc binary: ${frpcPath}`);
+        // 2. Find free port for admin API
+        this.adminPort = await findFreePort();
+        // 3. Try ports in random order from range
+        const ports = shuffle(range(this.config.portRangeStart, this.config.portRangeEnd + 1));
+        for (const port of ports) {
+            try {
+                const publicUrl = await this.tryStartWithPort(frpcPath, port);
+                this._publicUrl = publicUrl;
+                this._status = { status: "running", publicUrl, remotePort: port };
+                // Start health monitoring
+                this.startHealthCheck();
+                return publicUrl;
+            }
+            catch (err) {
+                this.logger.warn(`[frp] port ${port} unavailable: ${err instanceof Error ? err.message : String(err)}`);
+                // Kill process if started, try next port
+                await this.killProcess();
+            }
+        }
+        this._status = {
+            status: "error",
+            reason: `all ports in range ${this.config.portRangeStart}-${this.config.portRangeEnd} exhausted`,
+        };
+        throw new Error(`FRP tunnel failed: all ports in range ${this.config.portRangeStart}-${this.config.portRangeEnd} are unavailable`);
+    }
+    /* ── Stop ──────────────────────────────────────────────────────── */
+    async stop() {
+        if (this.healthCheckTimer) {
+            clearInterval(this.healthCheckTimer);
+            this.healthCheckTimer = null;
+        }
+        await this.killProcess();
+        // Cleanup config file
+        if (this.configPath) {
+            try {
+                await promises_1.default.unlink(this.configPath);
+            }
+            catch {
+                // ignore if already removed
+            }
+        }
+        this._status = { status: "stopped" };
+        this._publicUrl = null;
+    }
+    /* ── Private: try a specific port ──────────────────────────────── */
+    async tryStartWithPort(frpcPath, remotePort) {
+        const proxyName = `multiclaws-${(0, node_crypto_1.randomBytes)(4).toString("hex")}`;
+        this.configPath = node_path_1.default.join(this.stateDir, "frpc.toml");
+        const configContent = [
+            `serverAddr = "${this.config.serverAddr}"`,
+            `serverPort = ${this.config.serverPort}`,
+            `auth.token = "${this.config.token}"`,
+            ``,
+            `webServer.addr = "127.0.0.1"`,
+            `webServer.port = ${this.adminPort}`,
+            ``,
+            `[[proxies]]`,
+            `name = "${proxyName}"`,
+            `type = "tcp"`,
+            `localIP = "127.0.0.1"`,
+            `localPort = ${this.localPort}`,
+            `remotePort = ${remotePort}`,
+        ].join("\n");
+        // Ensure stateDir exists
+        await promises_1.default.mkdir(this.stateDir, { recursive: true });
+        await promises_1.default.writeFile(this.configPath, configContent, "utf8");
+        // Spawn frpc
+        this.frpcProcess = (0, node_child_process_1.spawn)(frpcPath, ["-c", this.configPath], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        // Capture stdout/stderr for logging
+        this.frpcProcess.stdout?.on("data", (data) => {
+            const line = data.toString().trim();
+            if (line)
+                this.logger.info(`[frpc] ${line}`);
+        });
+        this.frpcProcess.stderr?.on("data", (data) => {
+            const line = data.toString().trim();
+            if (line)
+                this.logger.warn(`[frpc:stderr] ${line}`);
+        });
+        this.frpcProcess.on("exit", (code, signal) => {
+            if (this._status.status === "running") {
+                this.logger.error(`[frp] frpc process exited unexpectedly (code=${code}, signal=${signal})`);
+                this._status = { status: "error", reason: `frpc exited (code=${code})` };
+            }
+        });
+        // Poll admin API to confirm proxy is running
+        await this.waitForProxy(proxyName);
+        return `http://${this.config.serverAddr}:${remotePort}`;
+    }
+    /* ── Private: poll admin API ──────────────────────────────────── */
+    async waitForProxy(proxyName) {
+        const url = `http://127.0.0.1:${this.adminPort}/api/proxy/tcp`;
+        for (let attempt = 0; attempt < ADMIN_API_POLL_MAX_RETRIES; attempt++) {
+            await new Promise((r) => setTimeout(r, ADMIN_API_POLL_INTERVAL_MS));
+            // Check if process has already exited
+            if (!this.frpcProcess || this.frpcProcess.exitCode !== null) {
+                throw new Error("frpc process exited before proxy became ready");
+            }
+            try {
+                const res = await fetch(url, { signal: AbortSignal.timeout(3_000) });
+                if (!res.ok)
+                    continue;
+                const data = (await res.json());
+                const proxy = data.proxies?.find((p) => p.name === proxyName);
+                if (!proxy)
+                    continue;
+                if (proxy.status === "running") {
+                    this.logger.info(`[frp] proxy "${proxyName}" is running (remote_addr: ${proxy.remote_addr})`);
+                    return;
+                }
+                if (proxy.err) {
+                    throw new Error(`frp proxy error: ${proxy.err}`);
+                }
+                // status might be "new" or "wait_start" — keep polling
+            }
+            catch (err) {
+                if (err instanceof Error && err.message.startsWith("frp proxy error:")) {
+                    throw err;
+                }
+                // fetch failed (admin API not yet ready) — keep polling
+            }
+        }
+        throw new Error("timeout waiting for frpc proxy to become running");
+    }
+    /* ── Private: health check ─────────────────────────────────────── */
+    startHealthCheck() {
+        this.healthCheckTimer = setInterval(async () => {
+            if (this._status.status !== "running")
+                return;
+            try {
+                const res = await fetch(`http://127.0.0.1:${this.adminPort}/api/proxy/tcp`, { signal: AbortSignal.timeout(5_000) });
+                if (!res.ok) {
+                    this.logger.warn("[frp] health check: admin API returned non-OK");
+                }
+            }
+            catch {
+                this.logger.warn("[frp] health check: failed to reach admin API");
+            }
+        }, HEALTH_CHECK_INTERVAL_MS);
+        // Don't prevent Node from exiting
+        if (this.healthCheckTimer.unref) {
+            this.healthCheckTimer.unref();
+        }
+    }
+    /* ── Private: kill process ─────────────────────────────────────── */
+    async killProcess() {
+        const proc = this.frpcProcess;
+        if (!proc)
+            return;
+        this.frpcProcess = null;
+        // Phase 1: graceful kill
+        proc.kill();
+        const exited = await Promise.race([
+            new Promise((resolve) => proc.on("exit", () => resolve(true))),
+            new Promise((resolve) => setTimeout(() => resolve(false), PROCESS_KILL_TIMEOUT_MS)),
+        ]);
+        if (!exited) {
+            // Phase 2: force kill
+            try {
+                if (process.platform === "win32" && proc.pid) {
+                    (0, node_child_process_1.execSync)(`taskkill /pid ${proc.pid} /f /t`, { stdio: "ignore" });
+                }
+                else {
+                    proc.kill("SIGKILL");
+                }
+            }
+            catch {
+                // process may have already exited
+            }
+        }
+    }
+    /* ── Private: ensure frpc binary ───────────────────────────────── */
+    async ensureFrpcBinary() {
+        const ext = process.platform === "win32" ? ".exe" : "";
+        const localBinary = node_path_1.default.join(this.stateDir, `frpc${ext}`);
+        // 1. Check stateDir
+        try {
+            await promises_1.default.access(localBinary);
+            return localBinary;
+        }
+        catch {
+            // not found locally
+        }
+        // 2. Check system PATH
+        if (detectFrpc()) {
+            return "frpc";
+        }
+        // 3. Auto-download
+        this.logger.info(`[frp] frpc not found, downloading v${FRP_VERSION}...`);
+        return await this.downloadFrpc(localBinary);
+    }
+    async downloadFrpc(targetPath) {
+        const { os: frpOs, arch: frpArch, ext } = getFrpPlatform();
+        const archiveName = `frp_${FRP_VERSION}_${frpOs}_${frpArch}`;
+        const url = `https://github.com/fatedier/frp/releases/download/v${FRP_VERSION}/${archiveName}.${ext}`;
+        const downloadDir = node_path_1.default.join(this.stateDir, "frpc-download");
+        await promises_1.default.mkdir(downloadDir, { recursive: true });
+        const archivePath = node_path_1.default.join(downloadDir, `${archiveName}.${ext}`);
+        // Download
+        this.logger.info(`[frp] downloading from ${url}`);
+        const res = await fetch(url);
+        if (!res.ok) {
+            throw new Error(`failed to download frpc: HTTP ${res.status} from ${url}`);
+        }
+        const buffer = Buffer.from(await res.arrayBuffer());
+        await promises_1.default.writeFile(archivePath, buffer);
+        // Extract
+        this.logger.info(`[frp] extracting ${archivePath}`);
+        const binaryName = process.platform === "win32" ? "frpc.exe" : "frpc";
+        try {
+            if (ext === "tar.gz") {
+                (0, node_child_process_1.execSync)(`tar -xzf "${archivePath}" -C "${downloadDir}"`, { stdio: "ignore" });
+            }
+            else {
+                // Windows: use tar (available since Windows 10 1803)
+                (0, node_child_process_1.execSync)(`tar -xf "${archivePath}" -C "${downloadDir}"`, { stdio: "ignore" });
+            }
+            // Move binary to target
+            const extractedBinary = node_path_1.default.join(downloadDir, archiveName, binaryName);
+            await promises_1.default.mkdir(node_path_1.default.dirname(targetPath), { recursive: true });
+            await promises_1.default.copyFile(extractedBinary, targetPath);
+            // Make executable on Unix
+            if (process.platform !== "win32") {
+                await promises_1.default.chmod(targetPath, 0o755);
+            }
+            this.logger.info(`[frp] frpc installed to ${targetPath}`);
+        }
+        finally {
+            // Cleanup download directory
+            try {
+                await promises_1.default.rm(downloadDir, { recursive: true, force: true });
+            }
+            catch {
+                // ignore cleanup errors
+            }
+        }
+        return targetPath;
+    }
+}
+exports.FrpTunnelManager = FrpTunnelManager;

package/dist/service/multiclaws-service.d.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from "node:events";
+import { type FrpTunnelConfig } from "../infra/frp";
 import { type AgentRecord } from "./agent-registry";
 import { type AgentProfile } from "./agent-profile";
 import { type TeamRecord, type TeamMember } from "../team/team-store";
@@ -8,6 +9,9 @@ export type MulticlawsServiceOptions = {
     port?: number;
     displayName?: string;
     selfUrl?: string;
+    tunnel?: FrpTunnelConfig & {
+        type: "frp";
+    };
     gatewayConfig?: GatewayConfig;
     logger?: {
         info: (message: string) => void;
@@ -35,6 +39,7 @@ export declare class MulticlawsService extends EventEmitter {
     private agentCard;
     private readonly clientFactory;
     private readonly httpRateLimiter;
+    private frpTunnel;
     private selfUrl;
     private profileDescription;
     constructor(options: MulticlawsServiceOptions);
@@ -96,7 +101,6 @@ export declare class MulticlawsService extends EventEmitter {
      */
     private processTaskResult;
     private extractArtifactText;
-    private notifyTailscaleSetup;
     /** Fetch with up to 2 retries and exponential backoff. */
     private fetchWithRetry;
     private log;

package/dist/service/multiclaws-service.js

@@ -9,7 +9,7 @@ const node_os_1 = __importDefault(require("node:os"));
 const node_http_1 = __importDefault(require("node:http"));
 const node_path_1 = __importDefault(require("node:path"));
 const promises_1 = __importDefault(require("node:fs/promises"));
-const tailscale_1 = require("../infra/tailscale");
+const frp_1 = require("../infra/frp");
 const json_store_1 = require("../infra/json-store");
 const express_1 = __importDefault(require("express"));
 const server_1 = require("@a2a-js/sdk/server");
@@ -21,7 +21,6 @@ const agent_profile_1 = require("./agent-profile");
 const team_store_1 = require("../team/team-store");
 const tracker_1 = require("../task/tracker");
 const zod_1 = require("zod");
-const gateway_client_1 = require("../infra/gateway-client");
 const rate_limiter_1 = require("../infra/rate-limiter");
 /* ------------------------------------------------------------------ */
 /*  Service                                                            */
@@ -39,6 +38,7 @@ class MulticlawsService extends node_events_1.EventEmitter {
     agentCard = null;
     clientFactory = new client_1.ClientFactory();
     httpRateLimiter = new rate_limiter_1.RateLimiter({ windowMs: 60_000, maxRequests: 60 });
+    frpTunnel = null;
     selfUrl;
     profileDescription = "OpenClaw agent";
     constructor(options) {
@@ -51,33 +51,28 @@ class MulticlawsService extends node_events_1.EventEmitter {
         this.taskTracker = new tracker_1.TaskTracker({
             filePath: node_path_1.default.join(multiclawsStateDir, "tasks.json"),
         });
-        const port = options.port ?? 3100;
-        // selfUrl resolved later in start() after Tailscale detection; use placeholder for now
-        this.selfUrl = options.selfUrl ?? `http://${getLocalIp()}:${port}`;
+        // selfUrl resolved later in start() after FRP tunnel setup
+        this.selfUrl = options.selfUrl ?? "";
     }
     async start() {
         if (this.started)
             return;
-        // Auto-detect Tailscale if selfUrl not explicitly configured
+        // Resolve selfUrl: explicit config > FRP tunnel
         if (!this.options.selfUrl) {
             const port = this.options.port ?? 3100;
-            // Fast path: Tailscale already active — just read from network interfaces, no subprocess
-            const tsIp = (0, tailscale_1.getTailscaleIpFromInterfaces)();
-            if (tsIp) {
-                this.selfUrl = `http://${tsIp}:${port}`;
-                this.log("info", `Tailscale IP detected: ${tsIp}`);
-            }
-            else {
-                // Slow path: Tailscale not active — run full detection and notify user
-                const tailscale = await (0, tailscale_1.detectTailscale)();
-                if (tailscale.status === "ready") {
-                    this.selfUrl = `http://${tailscale.ip}:${port}`;
-                    this.log("info", `Tailscale IP detected: ${tailscale.ip}`);
-                }
-                else {
-                    void this.notifyTailscaleSetup(tailscale);
-                }
+            if (!this.options.tunnel || this.options.tunnel.type !== "frp") {
+                throw new Error("multiclaws requires either 'selfUrl' or 'tunnel' configuration. " +
+                    "Please configure tunnel in plugin settings.");
             }
+            this.frpTunnel = new frp_1.FrpTunnelManager({
+                config: this.options.tunnel,
+                localPort: port,
+                stateDir: node_path_1.default.join(this.options.stateDir, "multiclaws"),
+                logger: this.options.logger,
+            });
+            const publicUrl = await this.frpTunnel.start();
+            this.selfUrl = publicUrl;
+            this.log("info", `FRP tunnel ready: ${publicUrl}`);
         }
         // Load profile for AgentCard description
         let profile = await this.profileStore.load();
@@ -149,6 +144,10 @@ class MulticlawsService extends node_events_1.EventEmitter {
         this.started = false;
         this.taskTracker.destroy();
         this.httpRateLimiter.destroy();
+        if (this.frpTunnel) {
+            await this.frpTunnel.stop();
+            this.frpTunnel = null;
+        }
         await new Promise((resolve) => {
             if (!this.httpServer) {
                 resolve();
@@ -653,49 +652,6 @@ class MulticlawsService extends node_events_1.EventEmitter {
             .map((p) => p.text)
             .join("\n");
     }
-    async notifyTailscaleSetup(tailscale) {
-        let message;
-        if (tailscale.status === "needs_auth") {
-            message = [
-                "🔗 **MultiClaws: Tailscale 登录**",
-                "",
-                "Tailscale 已安装但未登录，跨网络协作需要完成登录。",
-                "",
-                `👉 **请在浏览器打开：** ${tailscale.authUrl}`,
-                "",
-                "登录完成后重启 OpenClaw 即可。",
-                "_(局域网内协作无需此步骤，现在即可使用)_",
-            ].join("\n");
-        }
-        else {
-            // not_installed or unavailable
-            message = [
-                "🌐 **MultiClaws: 跨网络协作提示**",
-                "",
-                "**局域网内已可直接协作，无需任何配置。**",
-                "",
-                "如需跨网络（不同局域网间）协作，请安装 Tailscale：",
-                "https://tailscale.com/download",
-                "",
-                "安装并登录后重启 OpenClaw，将自动配置跨网络连接。",
-            ].join("\n");
-        }
-        // Send to user via gateway (best-effort, don't throw)
-        if (this.options.gatewayConfig) {
-            try {
-                await (0, gateway_client_1.invokeGatewayTool)({
-                    gateway: this.options.gatewayConfig,
-                    tool: "message",
-                    args: { action: "send", message },
-                    timeoutMs: 5_000,
-                });
-            }
-            catch {
-                // Fallback to log
-                this.log("warn", message.replace(/\*\*/g, "").replace(/```[^`]*```/gs, ""));
-            }
-        }
-    }
     /** Fetch with up to 2 retries and exponential backoff. */
     async fetchWithRetry(url, init, retries = 2) {
         let lastError = null;
@@ -720,23 +676,3 @@ class MulticlawsService extends node_events_1.EventEmitter {
     }
 }
 exports.MulticlawsService = MulticlawsService;
-function getLocalIp() {
-    // Prefer Tailscale IP if available
-    const tsIp = (0, tailscale_1.getTailscaleIpFromInterfaces)();
-    if (tsIp)
-        return tsIp;
-    const interfaces = node_os_1.default.networkInterfaces();
-    let fallback;
-    for (const addrs of Object.values(interfaces)) {
-        if (!addrs)
-            continue;
-        for (const addr of addrs) {
-            if (addr.family === "IPv4" && !addr.internal) {
-                if (addr.address.startsWith("192.168."))
-                    return addr.address;
-                fallback ??= addr.address;
-            }
-        }
-    }
-    return fallback ?? node_os_1.default.hostname();
-}

package/openclaw.plugin.json

@@ -20,7 +20,20 @@
       },
       "selfUrl": {
         "type": "string",
-        "description": "Publicly reachable URL for this agent. Auto-detected from hostname if not set."
+        "description": "Publicly reachable URL for this agent. If not set, tunnel configuration is required."
+      },
+      "tunnel": {
+        "type": "object",
+        "description": "FRP tunnel configuration for cross-network connectivity. Required if selfUrl is not set.",
+        "properties": {
+          "type":           { "type": "string", "enum": ["frp"] },
+          "serverAddr":     { "type": "string", "description": "FRP server address (IP or domain)" },
+          "serverPort":     { "type": "integer", "default": 7000, "description": "FRP server bind port" },
+          "token":          { "type": "string", "description": "FRP authentication token" },
+          "portRangeStart": { "type": "integer", "description": "Start of available remote port range" },
+          "portRangeEnd":   { "type": "integer", "description": "End of available remote port range (inclusive)" }
+        },
+        "required": ["type", "serverAddr", "serverPort", "token", "portRangeStart", "portRangeEnd"]
       },
       "telemetry": {
         "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multiclaws",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "MultiClaws plugin for OpenClaw collaboration via A2A protocol",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/multiclaws/SKILL.md

@@ -23,7 +23,7 @@ MultiClaws 让多个 OpenClaw 实例通过 [A2A（Agent-to-Agent）](https://goo
 2. 向用户展示生成的档案，并逐一确认以下三项：
    - **名字**：展示推断出的名字，询问是否需要修改（需用户明确回答）
    - **Bio**：展示生成的 bio，询问是否需要修改（需用户明确回答）
-   - **网络情况**：告知用户「同局域网开箱即用；跨网络需安装 Tailscale 并重启 OpenClaw，下载地址：https://tailscale.com/download」，无需用户回答
+   - **网络情况**：告知用户「所有实例通过 FRP 隧道通信，需在插件配置中设置 tunnel 字段（frps 地址、端口、token、可用端口范围），frpc 会自动下载安装」，无需用户回答
 
 3. 根据用户对名字和 bio 的回答更新内容后，调用 `multiclaws_profile_set(ownerName="...", bio="...")` 保存档案。
 
@@ -153,15 +153,29 @@ multiclaws_profile_show()
 
 ---
 
-## 跨网络
-
-**同局域网：** 开箱即用，无需配置。
-
-**不同网络：** 每人安装 [Tailscale](https://tailscale.com/download) 并登录同一 tailnet，插件自动检测 Tailscale IP。
+## 网络配置
+
+所有实例通过 FRP 隧道通信。需要一台运行 frps 的公网服务器。
+frpc 会在首次启动时自动下载安装，无需手动安装。
+
+在插件配置中添加 tunnel 字段即可：
+```json
+{
+  "tunnel": {
+    "type": "frp",
+    "serverAddr": "你的frps地址",
+    "serverPort": 7000,
+    "token": "你的认证令牌",
+    "portRangeStart": 7011,
+    "portRangeEnd": 7020
+  }
+}
+```
 
 当加入或委派因网络错误失败时（ECONNREFUSED、ETIMEDOUT、fetch failed），引导用户：
 
-> 你和对方不在同一网络。跨网络协作需要每个成员安装 Tailscale：
-> 1. 下载安装：https://tailscale.com/download
-> 2. 登录同一个 Tailscale 账号（或同一 tailnet）
-> 3. 重启 OpenClaw，插件会自动检测 Tailscale IP
+> 网络连接失败，请检查：
+> 1. 确认 frpc 已正常启动（查看日志中的 `[frp] FRP tunnel ready` 信息）
+> 2. 检查插件配置中的 `tunnel.serverAddr` / `tunnel.token` 是否正确
+> 3. 确认 frps 服务器可达（`telnet frps地址 端口`）
+> 4. 重启 OpenClaw