multiclaws 0.4.8 → 0.4.10

package/README.md

@@ -1,36 +1,39 @@
 # MultiClaws
 
-让多个 OpenClaw 实例通过 [A2A 协议](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)
 
-对你的 AI 说：
+## Installation
 
-> 请运行 `openclaw plugins install multiclaws`，安装完成后告诉我这个插件能做什么
+Just tell your AI:
 
-AI 会自动完成安装、配置和档案生成，无需手动修改任何文件。
+> Run `openclaw plugins install multiclaws` and tell me what it can do.
 
-## 使用
+Your AI handles the rest — installation, configuration, and profile setup — no manual steps required.
 
-一切通过自然语言完成：
+## Usage
 
-- **「创建一个叫 my-team 的团队」** — 创建团队并获取邀请码
-- **「用邀请码 mc:xxxxx 加入团队」** — 加入队友的团队
-- **「让 Bob 总结一下最新报告」** — 把任务委派给队友的 AI
-- **「显示所有智能体」** — 查看团队成员及其能力
+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 summarize the latest report"** — delegate a task to a teammate's AI
+- **"Show all agents"** — list team members and their capabilities
 
-同局域网开箱即用。不同网络安装 [Tailscale](https://tailscale.com/download)，插件自动检测。
+## How It Works
 
-## 详细文档
+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.
 
-见 [SKILL.md](skills/multiclaws/SKILL.md)。
+Works out of the box on the same local network. Cross-network collaboration is also supported.
 
-## 开发
+## Documentation
+
+See [SKILL.md](skills/multiclaws/SKILL.md) for full details.
+
+## Development
 
 ```bash
-pnpm install
-pnpm run build
-pnpm test
+npm install
+npm run build
 ```

package/README.zh-CN.md

@@ -1,6 +1,8 @@
 # MultiClaws
 
-让多个 OpenClaw 实例通过 [A2A 协议](https://google.github.io/A2A/) 组成团队、互相委派任务。
+[OpenClaw](https://openclaw.ai) 多智能体协作插件。将多个 OpenClaw 实例组成团队，通过 [A2A 协议](https://google.github.io/A2A/) 互相委派任务。
+
+[English](README.md)
 
 ## 安装
 
@@ -19,9 +21,11 @@ AI 会自动完成安装、配置和档案生成，无需手动修改任何文
 - **「让 Bob 总结一下最新报告」** — 把任务委派给队友的 AI
 - **「显示所有智能体」** — 查看团队成员及其能力
 
-## 跨网络
+## 工作原理
+
+MultiClaws 让多个 OpenClaw 实例作为一个团队协作。每个实例既可以作为客户端（委派任务），也可以作为服务端（接收他人任务）。任务由远端 AI 执行，结果直接返回。
 
-同局域网开箱即用。不同网络安装 [Tailscale](https://tailscale.com/download)，插件自动检测。
+同局域网开箱即用，也支持跨网络协作。
 
 ## 详细文档
 
@@ -30,7 +34,6 @@ AI 会自动完成安装、配置和档案生成，无需手动修改任何文
 ## 开发
 
 ```bash
-pnpm install
-pnpm run build
-pnpm test
+npm install
+npm run build
 ```

package/dist/index.js

@@ -6,10 +6,23 @@ const logger_1 = require("./infra/logger");
 const telemetry_1 = require("./infra/telemetry");
 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 : "",
+            serverPort: typeof rawTunnel.serverPort === "number" ? rawTunnel.serverPort : 7000,
+            token: typeof rawTunnel.token === "string" ? rawTunnel.token : "",
+            portRangeStart: typeof rawTunnel.portRangeStart === "number" ? rawTunnel.portRangeStart : 7011,
+            portRangeEnd: typeof rawTunnel.portRangeEnd === "number" ? rawTunnel.portRangeEnd : 7020,
+        };
+    }
     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 +345,7 @@ const plugin = {
                     port: config.port,
                     displayName: config.displayName,
                     selfUrl: config.selfUrl,
+                    tunnel: config.tunnel,
                     gatewayConfig: gatewayConfig ?? undefined,
                     logger: structured.logger,
                 });
@@ -392,7 +406,7 @@ multiclaws 插件刚安装，需要在本次对话中完成以下初始化流程
 2. 向用户展示生成的档案，并逐一确认以下三项（名字和 bio 需要用户明确回答）：
    - **名字**：展示推断出的名字，询问是否需要修改
    - **Bio**：展示生成的 bio，询问是否需要修改
-   - **网络情况**：告知用户「同局域网开箱即用；跨网络需安装 Tailscale（https://tailscale.com/download）并重启 OpenClaw」，无需用户回答
+   - **网络情况**：告知用户「所有实例通过 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/a2a-adapter.js

@@ -110,8 +110,8 @@ class OpenClawAgentExecutor {
         const gateway = this.gatewayConfig;
         const startTime = Date.now();
         let attempt = 0;
-        // Aggressive early polls, then back off: 300ms, 500ms, 1s, 2s, 3s, 3s...
-        const pollDelays = [300, 500, 1000, 2000, 3000];
+        // Start aggressive, max out at 500ms to minimize result latency
+        const pollDelays = [100, 200, 300, 500];
         while (Date.now() - startTime < timeoutMs) {
             const delay = pollDelays[Math.min(attempt, pollDelays.length - 1)];
             await sleep(delay);

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);
@@ -89,9 +94,13 @@ export declare class MulticlawsService extends EventEmitter {
     private fetchMemberDescriptions;
     private syncTeamToRegistry;
     private createA2AClient;
+    /**
+     * Send a message using A2A streaming to minimize latency.
+     * Instead of a single blocking HTTP call, consume the SSE stream and
+     * return the final Task or Message as soon as B signals completion.
+     */
     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();
@@ -618,6 +617,11 @@ class MulticlawsService extends node_events_1.EventEmitter {
     async createA2AClient(agent) {
         return await this.clientFactory.createFromUrl(agent.url);
     }
+    /**
+     * Send a message using A2A streaming to minimize latency.
+     * Instead of a single blocking HTTP call, consume the SSE stream and
+     * return the final Task or Message as soon as B signals completion.
+     */
     processTaskResult(trackId, result) {
         if ("status" in result && result.status) {
             const task = result;
@@ -648,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;
@@ -715,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.8",
+  "version": "0.4.10",
   "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（https://tailscale.com/download）并重启 OpenClaw」，无需用户回答
+   - **网络情况**：告知用户「所有实例通过 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