openclaw-openagent 1.0.1 → 1.0.2

package/dist/src/channel.js

@@ -0,0 +1,488 @@
+/**
+ * OpenAgent Channel Adapter — OpenClaw channel plugin interface
+ *
+ * Assembles the v3 modular architecture:
+ *   auth/ → runtime/ → tim/ → messaging/ → tools
+ *
+ * Gateway lifecycle uses AccountRuntime with transaction-style
+ * start/stop and RuntimeRegistry enforcement.
+ */
+import { isUnconfiguredOasnApiBase, resolveOpenagentAccount, getOpenagentConfig } from './auth/config.js';
+import { registry } from './runtime/registry.js';
+import { AccountRuntime } from './runtime/account.js';
+import { logger } from './util/logger.js';
+const API_BASE = 'https://api.clawlink.club';
+const OASN_TRANSPORT = 'oasn';
+// ── Channel adapter meta ──
+const meta = {
+    id: 'openagent',
+    label: 'OpenAgent',
+    selectionLabel: 'OpenAgent (Agent Network)',
+    detailLabel: 'OpenAgent Agent Network',
+    docsPath: '/channels/openagent',
+    docsLabel: 'openagent',
+    blurb: 'Connect to OASN agent social network via Tencent IM.',
+    aliases: ['openagent', 'agent-network'],
+    order: 90,
+    quickstartAllowFrom: true,
+};
+// ── Channel plugin object ──
+export const openagentPlugin = {
+    id: 'openagent',
+    meta,
+    capabilities: {
+        chatTypes: ['group'],
+        media: false,
+        reactions: true,
+        threads: false,
+        polls: false,
+        nativeCommands: false,
+    },
+    reload: { configPrefixes: ['channels.openagent'] },
+    config: {
+        listAccountIds: (cfgOrCtx) => {
+            const cfg = cfgOrCtx?.cfg
+                || (cfgOrCtx?.['channels'] ? cfgOrCtx : {});
+            const clCfg = getOpenagentConfig(cfg);
+            const keys = Object.keys((clCfg['accounts'] || {}));
+            return keys.length > 0 ? keys : ['default'];
+        },
+        resolveAccount: (cfg, accountId) => resolveOpenagentAccount(cfg, accountId),
+        defaultAccountId: (cfgOrCtx) => {
+            const cfg = cfgOrCtx?.cfg
+                || (cfgOrCtx?.['channels'] ? cfgOrCtx : {});
+            const clCfg = getOpenagentConfig(cfg);
+            const keys = Object.keys((clCfg['accounts'] || {}));
+            return keys.length > 0 ? keys[0] : 'default';
+        },
+        setAccountEnabled: ({ cfg, enabled }) => ({
+            ...cfg,
+            channels: {
+                ...cfg['channels'],
+                openagent: { ...cfg['channels']?.['openagent'], enabled },
+            },
+        }),
+        deleteAccount: ({ cfg }) => {
+            const channels = { ...cfg['channels'] };
+            delete channels['openagent'];
+            return { ...cfg, channels };
+        },
+        isConfigured: (account) => account.configured,
+        describeAccount: (account) => ({
+            accountId: account.accountId,
+            name: account.name,
+            enabled: account.enabled,
+            configured: account.configured,
+            tokenStatus: account.configured ? 'available' : 'missing',
+            transport: account.transport ?? 'oasn',
+            claimStatus: account.status ?? 'unknown',
+        }),
+    },
+    security: {
+        resolveDmPolicy: () => ({
+            policy: 'open',
+            allowFrom: ['*'],
+            policyPath: 'channels.openagent.dm.policy',
+            allowFromPath: 'channels.openagent.dm.allowFrom',
+            normalizeEntry: (raw) => raw.trim(),
+        }),
+    },
+    groups: {
+        resolveRequireMention: () => false,
+    },
+    threading: {
+        resolveReplyToMode: () => 'first',
+    },
+    messaging: {
+        normalizeTarget: (raw) => {
+            const trimmed = raw.trim();
+            if (!trimmed)
+                return undefined;
+            return trimmed.replace(/^(openagent):/i, '').trim() || undefined;
+        },
+        targetResolver: {
+            looksLikeId: (raw) => Boolean(raw.trim()),
+            hint: '<channel-id> e.g. ch-001',
+        },
+    },
+    outbound: {
+        deliveryMode: 'direct',
+        chunkerMode: 'text',
+        textChunkLimit: 3000,
+        sendText: async ({ to, text }) => {
+            logger.info(`[outbound] sendText to=${to} len=${text.length}`);
+            const rt = registry.getDefault();
+            if (!rt?.isRunning) {
+                logger.warn('[outbound] sendText failed: not connected');
+                return { channel: 'openagent', ok: false, messageId: '', error: new Error('OpenAgent not connected') };
+            }
+            // v3.9+ 双轨抽象：群聊外发仅在 TIM 路径有效（IMChannelTransport）。
+            // OASN 路径下没有"主动发群消息"语义 —— ClientAgent 只通过 sendTask
+            // 向远端 ServiceAgent 发起 Invocation，原则上不会触达此分支；
+            // 但若上层误调用，直接告警并返回 ok=false，避免崩溃。
+            if (rt.transportType === 'oasn') {
+                logger.warn(`[outbound] sendText not supported on OASN transport (to=${to})`);
+                return {
+                    channel: 'openagent',
+                    ok: false,
+                    messageId: '',
+                    error: new Error('sendText not supported on OASN transport'),
+                };
+            }
+            try {
+                const result = await rt.sendMessage(to, text);
+                logger.info(`[outbound] sendText OK msgId=${result.messageId}`);
+                return { channel: 'openagent', ok: true, messageId: result.messageId };
+            }
+            catch (err) {
+                logger.error(`[outbound] sendText failed: ${err.message}`);
+                return {
+                    channel: 'openagent', ok: false, messageId: '',
+                    error: err instanceof Error ? err : new Error(String(err)),
+                };
+            }
+        },
+    },
+    status: {
+        defaultRuntime: {
+            accountId: 'default',
+            running: false,
+            lastStartAt: null,
+            lastStopAt: null,
+            lastError: null,
+        },
+        buildChannelSummary: ({ snapshot }) => ({
+            configured: snapshot['configured'] ?? false,
+            running: snapshot['running'] ?? false,
+            connected: snapshot['connected'] ?? false,
+            transport: snapshot['transport'] ?? 'oasn',
+            claimStatus: snapshot['claimStatus'] ?? 'unknown',
+            claimUrl: snapshot['claimUrl'] ?? '',
+            lastStartAt: snapshot['lastStartAt'] ?? null,
+            lastStopAt: snapshot['lastStopAt'] ?? null,
+            lastError: snapshot['lastError'] ?? null,
+            lastInboundAt: snapshot['lastInboundAt'] ?? null,
+            lastOutboundAt: snapshot['lastOutboundAt'] ?? null,
+        }),
+        probeAccount: async () => ({ ok: true }),
+        buildAccountSnapshot: ({ account, runtime }) => ({
+            accountId: account.accountId,
+            name: account.name,
+            enabled: account.enabled,
+            configured: account.configured,
+            tokenStatus: account.configured ? 'available' : 'missing',
+            transport: account.transport ?? 'oasn',
+            claimStatus: runtime && 'claimStatus' in runtime ? runtime.claimStatus : account.status ?? 'unknown',
+            claimUrl: account.claimUrl ?? '',
+            running: runtime?.running ?? false,
+            connected: runtime?.running ?? false,
+            lastStartAt: runtime?.lastStartAt ?? null,
+            lastStopAt: runtime?.lastStopAt ?? null,
+            lastError: runtime?.lastError ?? null,
+        }),
+        // Outbound handlers: intentionally no-op (LLM text is intercepted here)
+        sendText: async () => ({ ok: true }),
+        sendMedia: async () => ({ ok: true }),
+    },
+    // ── Gateway lifecycle ──
+    gateway: {
+        startAccount: async (ctx) => {
+            const { account, abortSignal } = ctx;
+            // Guard is installed in register() (index.ts), not here.
+            // OASN 模式以 CLI install/register/write-config 为首次注册入口。
+            // runtime 只消费已经写入的 agent_id + api_key。
+            const accountConfig = resolveOpenagentAccount(ctx.cfg);
+            if (accountConfig.transport === 'oasn' && isUnconfiguredOasnApiBase(accountConfig.apiBase)) {
+                logger.warn('[channel] OASN api_base not configured; skipping start');
+                ctx.setStatus({
+                    accountId: account.accountId,
+                    running: false,
+                    configured: false,
+                    transport: 'oasn',
+                    claimStatus: accountConfig.status,
+                    lastError: 'OASN api_base is not configured',
+                });
+                return;
+            }
+            if (accountConfig.transport === 'oasn' && !accountConfig.configured) {
+                const message = 'OASN account is not configured; run openclaw-plugin-openagent-cli install to register this device';
+                logger.warn(`[channel] ${message}`);
+                ctx.setStatus({
+                    accountId: account.accountId,
+                    running: false,
+                    configured: false,
+                    transport: 'oasn',
+                    claimStatus: accountConfig.status,
+                    claimUrl: accountConfig.claimUrl,
+                    lastError: message,
+                });
+                return;
+            }
+            if (!account.configured && accountConfig.transport !== 'oasn') {
+                logger.warn('[channel] Not configured; skipping');
+                ctx.setStatus({ accountId: account.accountId, running: false, configured: false });
+                return;
+            }
+            logger.info(`[channel] Starting account '${account.accountId}' for agent ${accountConfig.agentId || account.agentId || '(unconfigured)'}`);
+            const runtime = new AccountRuntime(account.accountId);
+            try {
+                // Register in registry (throws if another account is active)
+                registry.register(runtime);
+                // Transaction-style start
+                await runtime.start({
+                    accountId: account.accountId,
+                    name: 'OpenAgent',
+                    enabled: true,
+                    configured: accountConfig.configured,
+                    agentId: accountConfig.agentId,
+                    apiKey: accountConfig.apiKey,
+                    apiBase: accountConfig.apiBase,
+                    accessApiBase: accountConfig.accessApiBase,
+                    claimUrl: accountConfig.claimUrl,
+                    status: accountConfig.status,
+                    registeredAt: accountConfig.registeredAt,
+                    // v3.9+ 双轨抽象：用 resolveOpenagentAccount 从 raw cfg 解析 transport（不依赖 OpenClaw 框架透传 account.config 自定义字段）
+                    transport: accountConfig.transport,
+                    config: account.config || {},
+                }, {
+                    batchWindowMs: account.config?.['batchWindowMs'] || 20_000,
+                    maxBatchSize: account.config?.['maxBatchSize'] || 20,
+                }, ctx.cfg);
+                ctx.setStatus({
+                    accountId: account.accountId,
+                    running: true,
+                    configured: accountConfig.configured,
+                    transport: runtime.transportType,
+                    claimStatus: runtime.claimStatus,
+                    claimUrl: runtime.claimUrl,
+                    lastStartAt: Date.now(),
+                });
+                logger.info('[channel] Pipeline active: Push mode');
+                // Block until aborted
+                await new Promise((_, reject) => {
+                    if (abortSignal) {
+                        abortSignal.addEventListener('abort', () => {
+                            void runtime.stop().then(() => {
+                                registry.unregister(runtime);
+                                ctx.setStatus({
+                                    accountId: account.accountId,
+                                    running: false,
+                                    lastStopAt: Date.now(),
+                                });
+                                logger.info(`[channel] Account '${account.accountId}' stopped via abort`);
+                                reject(new Error('abort'));
+                            });
+                        }, { once: true });
+                    }
+                });
+            }
+            catch (err) {
+                // Controlled failure: catch registry error or start error
+                const message = err.message;
+                if (message !== 'abort') {
+                    logger.error(`[channel] Start failed: ${message}`);
+                    registry.unregister(runtime);
+                    ctx.setStatus({
+                        accountId: account.accountId,
+                        running: false,
+                        lastError: message,
+                    });
+                }
+            }
+        },
+        stopAccount: async (ctx) => {
+            const rt = registry.getDefault();
+            if (rt) {
+                await rt.stop();
+                registry.unregister(rt);
+            }
+            ctx.setStatus({
+                accountId: ctx.account.accountId,
+                running: false,
+                lastStopAt: Date.now(),
+            });
+        },
+    },
+    // ── Onboarding wizard ──
+    onboarding: {
+        channel: 'openagent',
+        getStatus: async ({ cfg }) => {
+            const account = resolveOpenagentAccount(cfg);
+            const apiBaseMissing = account.transport === 'oasn' && isUnconfiguredOasnApiBase(account.apiBase);
+            const statusLine = buildOnboardingStatusLine(account, apiBaseMissing);
+            return {
+                channel: 'openagent',
+                configured: account.transport === 'oasn' ? account.configured && !apiBaseMissing : account.configured,
+                statusLines: [statusLine],
+                selectionHint: apiBaseMissing
+                    ? 'needs api_base'
+                    : account.transport === 'oasn' && !account.configured
+                        ? 'needs CLI install'
+                        : account.configured ? 'configured' : 'needs credentials',
+                quickstartScore: apiBaseMissing ? 0 : account.configured ? 2 : 0,
+            };
+        },
+        configure: async ({ cfg, prompter }) => {
+            const existing = (cfg['channels']?.['openagent'] || {});
+            const accounts = (existing['accounts'] || {});
+            const firstAccKey = Object.keys(accounts)[0];
+            const fallbackAcc = firstAccKey ? accounts[firstAccKey] : {};
+            const resolved = resolveOpenagentAccount(cfg);
+            if (resolved.transport === OASN_TRANSPORT) {
+                let apiBase = resolved.apiBase;
+                if (isUnconfiguredOasnApiBase(apiBase)) {
+                    apiBase = String(await prompter.text({
+                        message: 'Enter OASN API Base URL',
+                        validate: (v) => {
+                            const value = v?.trim();
+                            if (!value || isUnconfiguredOasnApiBase(value))
+                                return 'Required';
+                            try {
+                                // eslint-disable-next-line no-new
+                                new URL(value);
+                                return undefined;
+                            }
+                            catch {
+                                return 'Must be a valid URL';
+                            }
+                        },
+                    })).trim();
+                }
+                const accessApiBase = String(resolved.accessApiBase
+                    || fallbackAcc['access_api_base']
+                    || fallbackAcc['accessApiBase']
+                    || existing['access_api_base']
+                    || existing['accessApiBase']
+                    || apiBase);
+                let claimUpdates = {};
+                if (resolved.agentId && resolved.apiKey && resolved.status !== 'claimed') {
+                    const ownerEmail = String(await prompter.text({
+                        message: 'Enter Owner email to claim this OASN ClientAgent (leave blank to skip)',
+                        validate: () => undefined,
+                    })).trim();
+                    if (ownerEmail) {
+                        claimUpdates = await claimOasnAgent(apiBase, resolved.apiKey, resolved.agentId, ownerEmail);
+                    }
+                }
+                return {
+                    cfg: {
+                        ...cfg,
+                        channels: {
+                            ...cfg['channels'],
+                            openagent: {
+                                ...existing,
+                                enabled: true,
+                                transport: 'oasn',
+                                api_base: apiBase,
+                                access_api_base: accessApiBase,
+                                accounts: {
+                                    default: compactConfig({
+                                        ...fallbackAcc,
+                                        transport: 'oasn',
+                                        api_base: apiBase,
+                                        access_api_base: accessApiBase,
+                                        agent_id: resolved.agentId || fallbackAcc['agent_id'],
+                                        api_key: resolved.apiKey || fallbackAcc['api_key'],
+                                        claim_url: resolved.claimUrl || fallbackAcc['claim_url'],
+                                        status: claimUpdates.status || resolved.status,
+                                        registered_at: resolved.registeredAt || fallbackAcc['registered_at'],
+                                        ...claimUpdates,
+                                    }),
+                                },
+                            },
+                        },
+                    },
+                    accountId: 'default',
+                };
+            }
+            let agentId = (fallbackAcc['agentId'] || fallbackAcc['agent_id'] || firstAccKey || '');
+            let apiKey = (fallbackAcc['api_key'] || fallbackAcc['apiKey'] || '');
+            const apiBase = (fallbackAcc['apiBase'] || fallbackAcc['api_base'] || API_BASE);
+            if (!agentId) {
+                agentId = String(await prompter.text({
+                    message: 'Enter your OpenAgent Agent ID',
+                    validate: (v) => v?.trim() ? undefined : 'Required',
+                })).trim();
+            }
+            if (!apiKey) {
+                apiKey = String(await prompter.text({
+                    message: 'Enter your OpenAgent API Key',
+                    validate: (v) => v?.trim() ? undefined : 'Required',
+                })).trim();
+            }
+            const cleanedExisting = { ...existing };
+            delete cleanedExisting['agentId'];
+            delete cleanedExisting['apiKey'];
+            delete cleanedExisting['agent_id'];
+            delete cleanedExisting['api_key'];
+            return {
+                cfg: {
+                    ...cfg,
+                    channels: {
+                        ...cfg['channels'],
+                        openagent: {
+                            ...cleanedExisting,
+                            enabled: true,
+                            accounts: {
+                                default: {
+                                    agent_id: agentId,
+                                    api_key: apiKey,
+                                    api_base: apiBase,
+                                },
+                            },
+                        },
+                    },
+                },
+                accountId: 'default',
+            };
+        },
+        disable: (cfg) => ({
+            ...cfg,
+            channels: {
+                ...cfg['channels'],
+                openagent: {
+                    ...cfg['channels']?.['openagent'],
+                    enabled: false,
+                },
+            },
+        }),
+    },
+};
+function buildOnboardingStatusLine(account, apiBaseMissing) {
+    if (account.transport !== 'oasn') {
+        return account.configured
+            ? `OpenAgent: configured (agent=${account.agentId})`
+            : 'OpenAgent: needs agentId + apiKey';
+    }
+    if (apiBaseMissing)
+        return 'OASN: needs api_base';
+    if (!account.configured)
+        return `OASN: run openclaw-plugin-openagent-cli install to register (${account.apiBase})`;
+    const claimHint = account.status === 'claimed'
+        ? 'claimed'
+        : `${account.status}${account.claimUrl ? ` claim=${account.claimUrl}` : ''}`;
+    return `OASN: ${claimHint} (agent=${account.agentId})`;
+}
+function compactConfig(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined && value !== ''));
+}
+async function claimOasnAgent(apiBase, apiKey, agentId, ownerEmail) {
+    const res = await fetch(new URL('/api/agents/claim', apiBase), {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({ agentId, ownerEmail }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+        throw new Error(`claim failed: ${res.status} ${JSON.stringify(body).slice(0, 200)}`);
+    }
+    return {
+        status: 'claim_pending',
+        claim_expires_at: body['expiresAt'] || body['expires_at'],
+        owner_email_masked: body['ownerEmailMasked'] || body['owner_email_masked'],
+    };
+}

package/dist/src/compat.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Runtime host-version compatibility check for openclaw-openagent.
+ *
+ * OpenClaw uses a date-based version format: YYYY.M.DD (e.g. 2026.3.22).
+ * This module parses that format and validates the running host is within
+ * the supported range for this plugin version.
+ *
+ * Ported from openclaw-weixin v2.1.1 src/compat.ts
+ * Reference: docs/reference/plugins/openclaw-weixin-latest-v2.1.1/src/compat.ts
+ */
+export declare const PLUGIN_VERSION = "1.0.0";
+export declare const SUPPORTED_HOST_MIN = "2026.3.22";
+export interface OpenClawVersion {
+    year: number;
+    month: number;
+    day: number;
+}
+/**
+ * Parse an OpenClaw date version string (e.g. "2026.3.22") into components.
+ * Returns null for unparseable strings.
+ */
+export declare function parseOpenClawVersion(version: string): OpenClawVersion | null;
+/**
+ * Compare two parsed versions. Returns -1 | 0 | 1.
+ */
+export declare function compareVersions(a: OpenClawVersion, b: OpenClawVersion): -1 | 0 | 1;
+/**
+ * Check whether a host version string is >= SUPPORTED_HOST_MIN.
+ */
+export declare function isHostVersionSupported(hostVersion: string): boolean;
+/**
+ * Fail-fast guard. Call at the very start of `register()` to prevent the
+ * plugin from loading on an incompatible host.
+ *
+ * @throws {Error} with a human-readable message when the host is out of range.
+ */
+export declare function assertHostCompatibility(hostVersion: string | undefined): void;

package/dist/src/compat.js

@@ -0,0 +1,70 @@
+/**
+ * Runtime host-version compatibility check for openclaw-openagent.
+ *
+ * OpenClaw uses a date-based version format: YYYY.M.DD (e.g. 2026.3.22).
+ * This module parses that format and validates the running host is within
+ * the supported range for this plugin version.
+ *
+ * Ported from openclaw-weixin v2.1.1 src/compat.ts
+ * Reference: docs/reference/plugins/openclaw-weixin-latest-v2.1.1/src/compat.ts
+ */
+import { logger } from './util/logger.js';
+export const PLUGIN_VERSION = '1.0.0';
+export const SUPPORTED_HOST_MIN = '2026.3.22';
+/**
+ * Parse an OpenClaw date version string (e.g. "2026.3.22") into components.
+ * Returns null for unparseable strings.
+ */
+export function parseOpenClawVersion(version) {
+    // Strip any pre-release suffix (e.g. "2026.3.22-beta.1" -> "2026.3.22")
+    const base = version.trim().split('-')[0];
+    const parts = base.split('.');
+    if (parts.length !== 3)
+        return null;
+    const [year, month, day] = parts.map(Number);
+    if (Number.isNaN(year) || Number.isNaN(month) || Number.isNaN(day))
+        return null;
+    return { year, month, day };
+}
+/**
+ * Compare two parsed versions. Returns -1 | 0 | 1.
+ */
+export function compareVersions(a, b) {
+    for (const key of ['year', 'month', 'day']) {
+        if (a[key] < b[key])
+            return -1;
+        if (a[key] > b[key])
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Check whether a host version string is >= SUPPORTED_HOST_MIN.
+ */
+export function isHostVersionSupported(hostVersion) {
+    const host = parseOpenClawVersion(hostVersion);
+    if (!host)
+        return false;
+    const min = parseOpenClawVersion(SUPPORTED_HOST_MIN);
+    return compareVersions(host, min) >= 0;
+}
+/**
+ * Fail-fast guard. Call at the very start of `register()` to prevent the
+ * plugin from loading on an incompatible host.
+ *
+ * @throws {Error} with a human-readable message when the host is out of range.
+ */
+export function assertHostCompatibility(hostVersion) {
+    if (!hostVersion || hostVersion === 'unknown') {
+        logger.warn('[compat] Could not determine host OpenClaw version; skipping compatibility check.');
+        return;
+    }
+    if (isHostVersionSupported(hostVersion)) {
+        logger.info(`[compat] Host OpenClaw ${hostVersion} >= ${SUPPORTED_HOST_MIN}, OK.`);
+        return;
+    }
+    throw new Error(`openclaw-openagent@${PLUGIN_VERSION} requires OpenClaw >=${SUPPORTED_HOST_MIN}, ` +
+        `but found ${hostVersion}. ` +
+        `Please upgrade OpenClaw, or install the legacy version:\n` +
+        `  npm install openclaw-openagent@legacy`);
+}

package/dist/src/config/config-schema.d.ts

@@ -0,0 +1,56 @@
+/**
+ * OpenAgent config schema — Zod-based runtime validation.
+ *
+ * This mirrors the JSON schema in openclaw.plugin.json but provides
+ * type-safe runtime parsing via Zod.
+ *
+ * Uses direct zod dependency (same pattern as openclaw-weixin v2.1.1)
+ * rather than openclaw/plugin-sdk/zod, which is only available in
+ * OpenClaw >= ~2026.3.28 and would break on earlier supported hosts.
+ */
+import { z } from 'zod';
+/** Top-level openagent config schema. */
+export declare const OpenagentConfigSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    agent_id: z.ZodOptional<z.ZodString>;
+    api_key: z.ZodOptional<z.ZodString>;
+    claim_url: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        unregistered: "unregistered";
+        unclaimed: "unclaimed";
+        claim_pending: "claim_pending";
+        claimed: "claimed";
+        credential_expired: "credential_expired";
+        unknown: "unknown";
+    }>>;
+    registered_at: z.ZodOptional<z.ZodString>;
+    transport: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        oasn: "oasn";
+        tim: "tim";
+    }>>>;
+    api_base: z.ZodOptional<z.ZodString>;
+    access_api_base: z.ZodOptional<z.ZodString>;
+    accounts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        transport: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+            oasn: "oasn";
+            tim: "tim";
+        }>>>;
+        agent_id: z.ZodOptional<z.ZodString>;
+        api_key: z.ZodOptional<z.ZodString>;
+        api_base: z.ZodOptional<z.ZodString>;
+        access_api_base: z.ZodOptional<z.ZodString>;
+        claim_url: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodEnum<{
+            unregistered: "unregistered";
+            unclaimed: "unclaimed";
+            claim_pending: "claim_pending";
+            claimed: "claimed";
+            credential_expired: "credential_expired";
+            unknown: "unknown";
+        }>>;
+        registered_at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;

package/dist/src/config/config-schema.js

@@ -0,0 +1,34 @@
+/**
+ * OpenAgent config schema — Zod-based runtime validation.
+ *
+ * This mirrors the JSON schema in openclaw.plugin.json but provides
+ * type-safe runtime parsing via Zod.
+ *
+ * Uses direct zod dependency (same pattern as openclaw-weixin v2.1.1)
+ * rather than openclaw/plugin-sdk/zod, which is only available in
+ * OpenClaw >= ~2026.3.28 and would break on earlier supported hosts.
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Zod config schema
+// ---------------------------------------------------------------------------
+const transportSchema = z.enum(['oasn', 'tim']).default('oasn');
+const openagentAccountSchema = z.object({
+    name: z.string().optional(),
+    enabled: z.boolean().optional(),
+    transport: transportSchema.optional(),
+    agent_id: z.string().optional(),
+    api_key: z.string().optional(),
+    api_base: z.string().optional(),
+    access_api_base: z.string().optional(),
+    claim_url: z.string().optional(),
+    status: z.enum(['unregistered', 'unclaimed', 'claim_pending', 'claimed', 'credential_expired', 'unknown']).optional(),
+    registered_at: z.string().optional(),
+});
+/** Top-level openagent config schema. */
+export const OpenagentConfigSchema = openagentAccountSchema.extend({
+    transport: transportSchema.optional(),
+    api_base: z.string().optional(),
+    access_api_base: z.string().optional(),
+    accounts: z.record(z.string(), openagentAccountSchema).optional(),
+});