@aspalagin/openclaw-max 0.7.2 → 0.8.0

package/dist/src/api.js

@@ -9,17 +9,16 @@
  * (Минцифры) CA, which is not in the default Node trust store. Requests go
  * through a dedicated undici dispatcher whose CA set = system roots + Russian
  * Trusted Root/Sub CA. Trust is scoped to this client only, never process-wide.
+ * With an account proxy (httpProxy) the same CA set verifies MAX inside the
+ * CONNECT tunnel; the base URL and proxy come from network.ts.
  */
 import { createHash, randomBytes } from 'node:crypto';
 import * as tls from 'node:tls';
 import { retryAsync } from 'openclaw/plugin-sdk/runtime-env';
-import { Agent, buildConnector, fetch as undiciFetch } from 'undici';
+import { Agent, buildConnector, fetch as undiciFetch, ProxyAgent } from 'undici';
+import { bypassesProxy, lookupMaxNetwork, MaxNetworkConfigError, scrubProxyCredentials, } from './network.js';
+import { getMaxLogger } from './runtime.js';
 import { RUSSIAN_TRUSTED_ROOT_CA, RUSSIAN_TRUSTED_SUB_CA } from './russian-trusted-ca.js';
-/**
- * platform-api.max.ru is shut down on 2026-07-19; platform-api2.max.ru is the
- * canonical endpoint since June 2026.
- */
-const BASE_URL = 'https://platform-api2.max.ru';
 /**
  * Default per-request deadline. Raised from 10s after an intermittent in-process
  * stall aborted sends at exactly 10s ("This operation was aborted") while the
@@ -40,12 +39,34 @@ export function setMaxFetchForTests(fetchImpl) {
     testFetchOverride = fetchImpl;
 }
 let cachedDispatcher;
-function getMaxDispatcher() {
+const proxyDispatchers = new Map();
+/** CA set for MAX hosts: system roots (with NODE_EXTRA_CA_CERTS) + Russian Trusted CA. */
+function maxCaList() {
+    const tlsWithCaList = tls;
+    // getCACertificates("default") includes NODE_EXTRA_CA_CERTS additions when available
+    const systemCas = tlsWithCaList.getCACertificates?.('default') ?? tls.rootCertificates;
+    return [...systemCas, RUSSIAN_TRUSTED_ROOT_CA, RUSSIAN_TRUSTED_SUB_CA];
+}
+/**
+ * Dispatcher for one MAX request: through the account proxy (one ProxyAgent
+ * per proxy URL; the MAX CA set goes to requestTls — the TLS session with MAX
+ * runs inside the tunnel), or direct. Loopback targets (a local test stand)
+ * never use the proxy: over plain http the proxy would see the bot token.
+ */
+export function getMaxDispatcher(url, proxyUrl) {
+    if (proxyUrl && !bypassesProxy(url)) {
+        let proxied = proxyDispatchers.get(proxyUrl);
+        if (!proxied) {
+            proxied = new ProxyAgent({ uri: proxyUrl, requestTls: { ca: maxCaList() } });
+            proxyDispatchers.set(proxyUrl, proxied);
+        }
+        return proxied;
+    }
+    return getDirectMaxDispatcher();
+}
+function getDirectMaxDispatcher() {
     if (!cachedDispatcher) {
-        const tlsWithCaList = tls;
-        // getCACertificates("default") includes NODE_EXTRA_CA_CERTS additions when available
-        const systemCas = tlsWithCaList.getCACertificates?.('default') ?? tls.rootCertificates;
-        const ca = [...systemCas, RUSSIAN_TRUSTED_ROOT_CA, RUSSIAN_TRUSTED_SUB_CA];
+        const ca = maxCaList();
         // Wrap the TLS connector to time the DNS+TCP+TLS phase, scoped to this
         // dispatcher only (never process-wide). Diagnosing the intermittent
         // "This operation was aborted" needs to separate a connect stall from a
@@ -57,7 +78,7 @@ function getMaxDispatcher() {
                 const err = args[0];
                 const elapsedMs = Date.now() - startedAt;
                 if (err || elapsedMs > MAX_SLOW_CONNECT_MS) {
-                    console.error(`[MAX API] connect ${options.hostname} ${err ? 'failed' : 'slow'} dns+tcp+tls=${elapsedMs}ms` +
+                    getMaxLogger().error(`[MAX API] connect ${options.hostname} ${err ? 'failed' : 'slow'} dns+tcp+tls=${elapsedMs}ms` +
                         (err ? ` (${err.name})` : ''));
                 }
                 callback(...args);
@@ -67,13 +88,19 @@ function getMaxDispatcher() {
     }
     return cachedDispatcher;
 }
-function maxFetch(url, init) {
-    if (testFetchOverride)
-        return testFetchOverride(url, init);
-    return undiciFetch(url, {
-        ...init,
-        dispatcher: getMaxDispatcher(),
-    });
+async function maxFetch(url, init, proxyUrl) {
+    try {
+        if (testFetchOverride)
+            return await testFetchOverride(url, init);
+        return (await undiciFetch(url, {
+            ...init,
+            dispatcher: getMaxDispatcher(url, proxyUrl),
+        }));
+    }
+    catch (err) {
+        // Proxy failures may quote the proxy URL; its credentials never leave here.
+        throw scrubProxyCredentials(err, proxyUrl);
+    }
 }
 function escapeMultipartHeaderValue(value) {
     return value
@@ -144,6 +171,12 @@ export class MaxChatSendLimiter {
     }
 }
 let sharedSendLimiter = new MaxChatSendLimiter();
+/** The bot's own user id per token digest, remembered from any GET /me (the start probe). */
+const botUserIds = new Map();
+/** @internal Forget remembered bot ids (test isolation). */
+export function resetMaxBotUserIdsForTests() {
+    botUserIds.clear();
+}
 /** @internal Fresh process-wide send limiter (test isolation). */
 export function resetMaxSendLimiterForTests() {
     sharedSendLimiter = new MaxChatSendLimiter();
@@ -193,6 +226,8 @@ export class MaxRequestTimeoutError extends Error {
  * duplicate the message — only a definite 429 (never applied) is retried.
  */
 function isRetryableError(err, idempotent) {
+    if (err instanceof MaxNetworkConfigError)
+        return false;
     // A client-side timeout is safe to retry only for idempotent methods here; the
     // send path handles its own single, duplicate-safe retry for POST /messages.
     if (err instanceof MaxRequestTimeoutError)
@@ -215,6 +250,7 @@ const IDEMPOTENT_METHODS = new Set(['GET', 'PUT', 'DELETE']);
 export class MaxApi {
     token;
     baseUrl;
+    explicitNetwork;
     timeoutMs;
     retryAttempts;
     sendLimiter;
@@ -224,15 +260,30 @@ export class MaxApi {
         this.token = opts.token;
         this.sendLimiter = opts.sendLimiter === undefined ? sharedSendLimiter : opts.sendLimiter;
         this.tokenKey = createHash('sha256').update(opts.token).digest('hex').slice(0, 12);
-        this.baseUrl = opts.baseUrl ?? BASE_URL;
+        this.baseUrl = opts.baseUrl?.replace(/\/+$/, '');
+        this.explicitNetwork = opts.network;
         this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         const envAttempts = Number(process.env.OPENCLAW_MAX_RETRY_ATTEMPTS);
         this.retryAttempts =
             opts.retryAttempts ?? (Number.isFinite(envAttempts) && envAttempts >= 0 ? envAttempts : 3);
     }
     // ── HTTP helpers ──
+    /**
+     * Current network settings, read per request so a config reload applies to
+     * long-lived clients too. Throws MaxNetworkConfigError for a bad config.
+     */
+    network() {
+        const network = this.explicitNetwork ?? lookupMaxNetwork(this.token);
+        return this.baseUrl ? { ...network, apiBaseUrl: this.baseUrl } : network;
+    }
+    /** Proxy for media downloads of this account (runtime media fetch), if any. */
+    mediaProxyUrl() {
+        return this.network().proxyUrl;
+    }
     async requestOnce(method, path, params, body, timeoutMs, externalSignal) {
-        const url = new URL(path, this.baseUrl);
+        const network = this.network();
+        // Appended, not resolved: a base URL may carry a path prefix.
+        const url = new URL(`${network.apiBaseUrl}${path}`);
         if (params) {
             for (const [k, v] of Object.entries(params)) {
                 if (v != null)
@@ -262,7 +313,7 @@ export class MaxApi {
                 },
                 body: body ? JSON.stringify(body) : undefined,
                 signal,
-            });
+            }, network.proxyUrl);
             gotResponse = true;
             const json = (await res.json().catch(() => null));
             const elapsedMs = Date.now() - startedAt;
@@ -270,12 +321,12 @@ export class MaxApi {
             // it is excluded here; every other call reaching the server slowly is a
             // fingerprint that points away from a connect hang.
             if (elapsedMs > MAX_SLOW_REQUEST_MS && path !== '/updates') {
-                console.error(`[MAX API] ${method} ${path} slow: ${elapsedMs}ms (status ${res.status})`);
+                getMaxLogger().error(`[MAX API] ${method} ${path} slow: ${elapsedMs}ms (status ${res.status})`);
             }
             if (!res.ok) {
                 // Never log the request body: it may carry the webhook secret (POST
                 // /subscriptions) or private message text. Log only method+path+status.
-                console.error(`[MAX API] ${method} ${path} → ${res.status}`);
+                getMaxLogger().error(`[MAX API] ${method} ${path} → ${res.status}`);
                 const error = new MaxApiError(`MAX API ${method} ${path} → ${res.status}`, res.status, json);
                 const retryAfter = res.headers?.get?.('retry-after');
                 if (retryAfter) {
@@ -295,13 +346,13 @@ export class MaxApi {
                 // opaque "This operation was aborted" into a typed, loggable timeout
                 // that records whether a response had started.
                 const phase = gotResponse ? 'reading-body' : 'awaiting-response';
-                console.error(`[MAX API] ${method} ${path} timed out after ${elapsedMs}ms (phase=${phase})`);
+                getMaxLogger().error(`[MAX API] ${method} ${path} timed out after ${elapsedMs}ms (phase=${phase})`);
                 throw new MaxRequestTimeoutError(method, path, elapsedMs, phase);
             }
             if (!isAbort && !(err instanceof MaxApiError)) {
                 // Network-level failure (DNS/TCP/TLS/reset): record timing so a connect
                 // stall is distinguishable from a response-wait stall in the log.
-                console.error(`[MAX API] ${method} ${path} failed after ${elapsedMs}ms: ${err.name}`);
+                getMaxLogger().error(`[MAX API] ${method} ${path} failed after ${elapsedMs}ms: ${err.name}`);
             }
             throw err;
         }
@@ -326,7 +377,14 @@ export class MaxApi {
     }
     // ── Bot info ──
     async getMe() {
-        return this.request('GET', '/me');
+        const me = await this.request('GET', '/me');
+        if (typeof me?.user_id === 'number')
+            botUserIds.set(this.tokenKey, me.user_id);
+        return me;
+    }
+    /** The bot's own user id: remembered from a GET /me with this token, else fetched once. */
+    async getBotUserId() {
+        return botUserIds.get(this.tokenKey) ?? (await this.getMe()).user_id;
     }
     // ── Messages ──
     async sendMessage(body, params) {
@@ -383,8 +441,8 @@ export class MaxApi {
         return this.request('DELETE', `/chats/${chatId}/pin`);
     }
     // ── Chat actions ──
-    async sendAction(chatId, action) {
-        return this.request('POST', `/chats/${chatId}/actions`, undefined, { action });
+    async sendAction(chatId, action, opts) {
+        return this.request('POST', `/chats/${chatId}/actions`, undefined, { action }, opts?.timeoutMs, opts?.retryAttempts, opts?.signal);
     }
     // ── Callbacks ──
     async answerCallback(callbackId, body) {
@@ -442,70 +500,28 @@ export class MaxApi {
         return this.request('POST', `/uploads`, { type });
     }
     /**
-     * Upload media file to MAX.
+     * Upload media bytes to MAX.
      * MAX upload requires multipart/form-data with field "data".
      * Response contains a token (in photos/videos/etc) to use in attachments.
+     * Takes bytes only: local files are read by the callers through the host
+     * media access policy (allowed roots, host reader), never by path here.
      *
      * @param type Media type (image, video, audio, file)
-     * @param data File path (string) or buffer (Buffer/Uint8Array)
-     * @param contentType MIME type (optional, auto-detected for common types)
+     * @param data File contents
+     * @param contentType MIME type (default application/octet-stream)
+     * @param fileName File name for the multipart part (default "file")
      * @returns Upload result with token (for use in attachment payload)
      */
-    async uploadMedia(type, data, contentType) {
+    async uploadMedia(type, data, contentType, fileName = 'file') {
         // Step 1: Get upload URL and attachment token.
         // MAX returns the attachment token together with the upload URL. The
         // following upload host may answer with XML like `<retval>1</retval>` and
         // does not repeat that token.
         const uploadInfo = await this.getUploadUrl(type);
         const uploadUrl = uploadInfo.url;
-        // Step 2: Load file if data is a path
-        let fileBuffer;
-        let mimeType = contentType;
-        let fileName = 'file';
-        if (typeof data === 'string') {
-            // File path — read from disk
-            const fs = await import('fs/promises');
-            const path = await import('path');
-            fileBuffer = await fs.readFile(data);
-            fileName = path.basename(data);
-            // Auto-detect MIME type if not provided
-            if (!mimeType) {
-                const ext = data.split('.').pop()?.toLowerCase();
-                const mimeMap = {
-                    jpg: 'image/jpeg',
-                    jpeg: 'image/jpeg',
-                    png: 'image/png',
-                    gif: 'image/gif',
-                    webp: 'image/webp',
-                    heic: 'image/heic',
-                    heif: 'image/heif',
-                    tif: 'image/tiff',
-                    tiff: 'image/tiff',
-                    bmp: 'image/bmp',
-                    mp4: 'video/mp4',
-                    mov: 'video/quicktime',
-                    avi: 'video/x-msvideo',
-                    mkv: 'video/x-matroska',
-                    webm: 'video/webm',
-                    mp3: 'audio/mpeg',
-                    wav: 'audio/wav',
-                    ogg: 'audio/ogg',
-                    m4a: 'audio/mp4',
-                    aac: 'audio/aac',
-                    flac: 'audio/flac',
-                    opus: 'audio/opus',
-                    pdf: 'application/pdf',
-                    txt: 'text/plain',
-                };
-                mimeType = ext ? mimeMap[ext] : 'application/octet-stream';
-            }
-        }
-        else {
-            // Already a buffer
-            fileBuffer = Buffer.from(data);
-            mimeType = mimeType ?? 'application/octet-stream';
-        }
-        // Step 3: POST file as multipart/form-data to upload URL. MAX upload hosts
+        const fileBuffer = Buffer.from(data);
+        const mimeType = contentType ?? 'application/octet-stream';
+        // Step 2: POST file as multipart/form-data to upload URL. MAX upload hosts
         // reject Node's native FormData in some cases with 412, while curl-style
         // multipart with a known Content-Length is accepted.
         const multipart = buildMultipartFileBody('data', fileName, mimeType, fileBuffer);
@@ -516,11 +532,11 @@ export class MaxApi {
                 'Content-Length': String(multipart.body.byteLength),
             },
             body: multipart.body,
-        });
+        }, this.network().proxyUrl);
         if (!uploadRes.ok) {
             throw new MaxApiError(`MAX media upload failed: ${uploadRes.status}`, uploadRes.status, await uploadRes.text().catch(() => null));
         }
-        // Step 4: Parse response to extract token
+        // Step 3: Parse response to extract token
         // Image response: { photos: { "<id>": { token: "...", url: "..." } } }
         // Video/audio/file may respond with a top-level token or a similar nested map
         const result = (await uploadRes.json().catch(() => ({})));

package/dist/src/callbacks.js

@@ -5,6 +5,8 @@
  */
 import { resolveApprovalOverGateway } from 'openclaw/plugin-sdk/approval-gateway-runtime';
 import { questionGatewayRuntime } from 'openclaw/plugin-sdk/question-gateway-runtime';
+import { admitMaxGroupMessage } from './access-policy.js';
+import { decodeMaxCommandMenuPayload } from './command-menu.js';
 import { processIncomingMessage } from './inbound.js';
 import { decodeMaxPresentationCallback } from './presentation.js';
 /**
@@ -37,7 +39,17 @@ export async function processCallback(callback, message, userLocale, opts) {
     // plain channelData.max.buttons payloads keep arriving as message text.
     const presentationCallback = decodeMaxPresentationCallback(payload);
     if (presentationCallback?.kind === 'approval' || presentationCallback?.kind === 'question') {
-        await resolveMaxRuntimeControlCallback(presentationCallback, callback, opts);
+        await resolveMaxRuntimeControlCallback(presentationCallback, callback, message, opts);
+        return;
+    }
+    // Command menu choices re-enter as that command's text; inbound checks the
+    // sender's command rights and whether core still offers the choice.
+    const menuCommand = decodeMaxCommandMenuPayload(payload);
+    if (menuCommand) {
+        const menuMessage = Object.assign(buildCallbackMessage(callback, message, menuCommand), {
+            __maxCommandMenu: true,
+        });
+        await processIncomingMessage(menuMessage, userLocale, opts);
         return;
     }
     // Opaque callback data goes to the agent labelled, never as a slash command.
@@ -49,19 +61,27 @@ export async function processCallback(callback, message, userLocale, opts) {
 /**
  * Approvals and ask_user answers are operator actions: only senders listed
  * explicitly in the account's allowFrom may press them (a wildcard is enough
- * for questions, never for approvals).
+ * for questions, never for approvals). A wildcard answer in a group also
+ * needs the group policy and its sender allowlist; with the chat unknown
+ * (the keyboard message is gone) the wildcard is not enough.
  */
-function isMaxRuntimeControlSender(account, senderId, kind) {
+function isMaxRuntimeControlSender(opts, message, senderId, kind) {
+    const { account, config } = opts;
     const allowFrom = (account.config.allowFrom ?? []).map((entry) => String(entry).trim().replace(/^max:/i, ''));
     if (allowFrom.includes(senderId))
         return true;
-    return kind === 'question' && allowFrom.includes('*');
+    if (kind !== 'question' || !allowFrom.includes('*') || !message)
+        return false;
+    const { chat_id: chatId, chat_type: chatType } = message.recipient;
+    if (chatType !== 'chat' && chatType !== 'channel')
+        return true;
+    return admitMaxGroupMessage(account, config, chatId, senderId).admitted;
 }
-async function resolveMaxRuntimeControlCallback(action, callback, opts) {
+async function resolveMaxRuntimeControlCallback(action, callback, message, opts) {
     const { account, config, log } = opts;
     const senderId = String(callback.user.user_id);
     let notification;
-    if (!isMaxRuntimeControlSender(account, senderId, action.kind)) {
+    if (!isMaxRuntimeControlSender(opts, message, senderId, action.kind)) {
         log?.warn(`[${account.accountId}] MAX ${action.kind} button pressed by unauthorized sender ${senderId}`);
         notification = 'You are not allowed to answer this.';
     }
@@ -87,7 +107,7 @@ async function resolveMaxRuntimeControlCallback(action, callback, opts) {
                     questionId: action.questionId,
                     optionValue: action.optionValue,
                     senderId,
-                    authorize: () => isMaxRuntimeControlSender(account, senderId, 'question'),
+                    authorize: () => isMaxRuntimeControlSender(opts, message, senderId, 'question'),
                 });
                 notification =
                     result.status === 'answered'

package/dist/src/channel-agent-prompt.js

@@ -1,6 +1,7 @@
 /**
  * Agent prompt hints of the MAX channel: stickers, location, contact, pin,
- * button types and presentation for the message tool.
+ * button types, presentation, voice, inline files, silent sends, local file
+ * roots and action scope for the message tool.
  */
 /** message tool hints for MAX-specific actions. */
 export const maxAgentPromptAdapter = {
@@ -8,31 +9,19 @@ export const maxAgentPromptAdapter = {
         // Compact sticker emoji map: top 50 emojis → sticker codes
         // Codes are hex IDs derived from listmax.ru external_id: parseInt(extId).toString(16)
         const emojiMap = '😂:109550b5 😊:109971b5 😍:10931eb5 🥰:10931eb5 😢:109330b5 😭:109330b5 😡:10941fb5 😱:109302b5 🤔:109308b5 👍:109368b5 👎:109323b5 ❤️:10931eb5 🔥:b4867ebb 💪:c1254bbb 🎉:10933cb5 😘:10931eb5 🤗:109b94b5 😎:10931db5 🙄:c14211bb 😴:10936eb5 😤:10941fb5 🤮:6b8bb 🤯:109302b5 😳:109302b5 🥳:10933cb5 💀:b4863ebb 🙈:b4850cbb 😏:11e4c60bb 😅:109550b5 🤣:109550b5 😋:109d2db5 😜:455b5 🤷:10d5cf5bb 😫:10936eb5 😩:10997db5 🥺:109356b5 😌:14aae3bb 😒:109323b5 🤪:455b5 😇:11e4dedbb 🙏:50cb5 💔:10997db5 👀:b48534bb ✨:11e43b2bb 😈:10941fb5 🤝:109368b5 🤦:502b5 😬:5dab4b5 🤩:5dabfb5 😶:2ae2b5';
-        // Also try to load full sticker-emoji-map.json for extended catalog
-        let extendedHint = '';
-        try {
-            const fs = require('fs');
-            const path = require('path');
-            const candidates = [
-                path.join(__dirname, '..', 'sticker-emoji-map.json'),
-                path.join(process.cwd(), 'projects', 'openclaw-max', 'sticker-emoji-map.json'),
-            ];
-            for (const p of candidates) {
-                if (fs.existsSync(p)) {
-                    extendedHint = ' Full emoji→sticker map available at: ' + p;
-                    break;
-                }
-            }
-        }
-        catch { }
         return [
             '- MAX stickers: use `message(action="sticker", target="CHAT_ID", stickerId="CODE")`. Pick a sticker code matching the mood from the emoji map below. Each entry is emoji:hexCode.',
-            `- Sticker emoji map: ${emojiMap}${extendedHint}`,
+            `- Sticker emoji map: ${emojiMap}`,
             '- MAX location: use `message(action="sendAttachment", target="CHAT_ID", type="location", latitude="55.75", longitude="37.62")` to send a native map pin.',
             '- MAX contact: use `message(action="sendAttachment", target="CHAT_ID", type="contact", contactName="Name", vcfPhone="+70001234567")` to send a native contact card.',
             '- MAX pin: use `message(action="pin", target="CHAT_ID", messageId="MID")` to pin a message; `message(action="unpin", target="CHAT_ID")` to unpin.',
             '- MAX buttons support types: callback (default), link, message (sends the button text as a user message — great for suggested replies), clipboard (copies payload), open_app (webApp = public name of the bot wired to the mini app), request_contact, request_geo_location. Pass via buttons=[[{"text":"...","type":"message"}]].',
             '- MAX rich messages: prefer `presentation` (title/tone, text, context, divider, table/chart as monospace text, buttons and select as an inline keyboard); `pin=true` pins the sent message.',
+            '- MAX voice: `asVoice=true` on `send`/`sendAttachment` with an audio file (mp3, m4a, wav, ogg, opus) sends it as a MAX audio message instead of a file.',
+            '- MAX files without a path: `sendAttachment` takes `buffer` (base64 or a data URL) with `filename` and `contentType`.',
+            '- MAX quiet sends: `silent=true` sends without a notification (MAX channels always notify).',
+            '- MAX local files: only files under the media roots OpenClaw allows for this agent (its workspace and media directories) can be sent; a path outside them is refused — save the file there first.',
+            "- MAX action scope: `send`, `sendAttachment`, `sticker`, `edit`, `delete`, `pin` and `unpin` work in the current chat and in chats the channel access policy admits, or on the owner's request (channels.max.actionScope). A refusal is a tool error: report it, do not retry in another chat.",
         ];
     },
 };

package/dist/src/channel-config.js

@@ -3,11 +3,29 @@
  * and resolution, enable/delete, allowFrom formatting, `openclaw channels add`.
  */
 import { applyAccountNameToChannelSection, DEFAULT_ACCOUNT_ID, deleteAccountFromConfigSection, migrateBaseNameToDefaultAccount, normalizeAccountId, setAccountEnabledInConfigSection, } from 'openclaw/plugin-sdk/core';
-import { listMaxAccountIds, resolveMaxAccount } from './accounts.js';
+import { isMaxAccountConfigured, listMaxAccountIds, readMaxAccount, resolveMaxAccount, } from './accounts.js';
+import { resolveMaxTransport } from './monitor-types.js';
 /** Accounts under channels.max (top level = default account, plus channels.max.accounts). */
 export const maxConfigAdapter = {
     listAccountIds: (cfg) => listMaxAccountIds(cfg),
     resolveAccount: (cfg, accountId) => resolveMaxAccount({ cfg, accountId }),
+    // Read-only status (openclaw status / channels status, doctor): where the
+    // token comes from and whether it is usable in this command path, never
+    // the token itself. A SecretRef the command cannot read is
+    // configured_unavailable, not "not configured".
+    inspectAccount: (cfg, accountId) => {
+        const account = readMaxAccount({ cfg, accountId });
+        return {
+            accountId: account.accountId,
+            ...(account.name ? { name: account.name } : {}),
+            enabled: account.enabled,
+            configured: isMaxAccountConfigured(account),
+            tokenSource: account.tokenSource,
+            tokenStatus: account.tokenStatus,
+            mode: resolveMaxTransport(account.config),
+            ...(account.stateReason ? { stateReason: account.stateReason } : {}),
+        };
+    },
     defaultAccountId: () => DEFAULT_ACCOUNT_ID,
     setAccountEnabled: ({ cfg, accountId, enabled }) => setAccountEnabledInConfigSection({
         cfg,
@@ -22,13 +40,17 @@ export const maxConfigAdapter = {
         accountId,
         clearBaseFields: ['botToken', 'tokenFile', 'name'],
     }),
-    isConfigured: (account) => Boolean(account.token?.trim()),
+    // An unresolved SecretRef token counts as configured: startAccount then
+    // fails with its config path instead of the account being silently skipped.
+    isConfigured: (account) => isMaxAccountConfigured(account),
     describeAccount: (account) => ({
         accountId: account.accountId,
         name: account.name,
         enabled: account.enabled,
-        configured: Boolean(account.token?.trim()),
+        configured: isMaxAccountConfigured(account),
         tokenSource: account.tokenSource,
+        tokenStatus: account.tokenStatus,
+        ...(account.stateReason ? { stateReason: account.stateReason } : {}),
     }),
     resolveAllowFrom: ({ cfg, accountId }) => (resolveMaxAccount({ cfg, accountId }).config.allowFrom ?? []).map(String),
     formatAllowFrom: ({ allowFrom }) => allowFrom

package/dist/src/channel-lifecycle.js

@@ -3,8 +3,11 @@
  * monitor) and logout, status snapshots, probes and group audits (health).
  */
 import { DEFAULT_ACCOUNT_ID } from 'openclaw/plugin-sdk/core';
+import { describeMaxInheritedOpenAccess } from './access-policy.js';
+import { isMaxAccountConfigured, MaxSecretConfigError, resolveMaxAccountNetwork, } from './accounts.js';
 import { MaxApi } from './api.js';
 import { startMaxPolling } from './monitor.js';
+import { DEFAULT_MAX_API_BASE_URL, redactProxyUrl } from './network.js';
 import { writeMaxConfig } from './runtime.js';
 /** Runtime snapshots, GET /me probe and a membership audit of configured groups. */
 export const maxStatusAdapter = {
@@ -23,6 +26,7 @@ export const maxStatusAdapter = {
         // compares them with the live runtime and treats a missing value as stale.
         ...(snapshot.lifecycle !== undefined ? { lifecycle: snapshot.lifecycle } : {}),
         ...(typeof snapshot.connected === 'boolean' ? { connected: snapshot.connected } : {}),
+        ...(snapshot.mode ? { mode: snapshot.mode } : {}),
         lastStartAt: snapshot.lastStartAt ?? null,
         lastStopAt: snapshot.lastStopAt ?? null,
         lastError: snapshot.lastError ?? null,
@@ -44,11 +48,15 @@ export const maxStatusAdapter = {
         accountId: account.accountId,
         name: account.name,
         enabled: account.enabled,
-        configured: Boolean(account.token?.trim()),
+        configured: isMaxAccountConfigured(account),
         tokenSource: account.tokenSource,
+        tokenStatus: account.tokenStatus,
+        ...(account.stateReason ? { stateReason: account.stateReason } : {}),
         running: runtime?.running ?? false,
         ...(runtime?.lifecycle !== undefined ? { lifecycle: runtime.lifecycle } : {}),
         ...(typeof runtime?.connected === 'boolean' ? { connected: runtime.connected } : {}),
+        // Transport the running task reported ("webhook" or "polling").
+        ...(runtime?.mode ? { mode: runtime.mode } : {}),
         lastStartAt: runtime?.lastStartAt ?? null,
         lastStopAt: runtime?.lastStopAt ?? null,
         lastError: runtime?.lastError ?? null,
@@ -138,7 +146,9 @@ export const maxStatusAdapter = {
                     channel: 'max',
                     accountId: snapshot.accountId,
                     kind: 'config',
-                    message: 'MAX bot token not configured',
+                    message: snapshot.stateReason
+                        ? `MAX bot token not configured: ${snapshot.stateReason}`
+                        : 'MAX bot token not configured',
                     fix: 'Set channels.max.botToken or MAX_BOT_TOKEN env var',
                 });
             }
@@ -150,12 +160,25 @@ export const maxStatusAdapter = {
 export const maxGatewayAdapter = {
     startAccount: async (ctx) => {
         const account = ctx.account;
+        // Path and ref only; the gateway normally isolates such an account itself.
+        if (account.secretErrors?.botToken) {
+            throw new MaxSecretConfigError(account.secretErrors.botToken);
+        }
+        // A named account open only through channel-level (or default) policies.
+        const inheritedOpen = describeMaxInheritedOpenAccess(ctx.cfg, account);
+        if (inheritedOpen)
+            ctx.log?.warn(`[${account.accountId}] ${inheritedOpen}`);
         const token = account.token.trim();
+        // A bad apiBaseUrl/httpProxy stops the account with a clear error rather
+        // than letting it connect directly or to the wrong host.
+        const network = resolveMaxAccountNetwork(account);
+        const route = (network.apiBaseUrl !== DEFAULT_MAX_API_BASE_URL ? ` api=${network.apiBaseUrl}` : '') +
+            (network.proxyUrl ? ` proxy=${redactProxyUrl(network.proxyUrl)}` : '');
         let botLabel = '';
         let botUserId;
         let botUsername;
         try {
-            const probeApi = new MaxApi({ token, timeoutMs: 3000 });
+            const probeApi = new MaxApi({ token, timeoutMs: 3000, network });
             const me = await probeApi.getMe();
             if (me.username) {
                 botLabel = ` (@${me.username})`;
@@ -166,8 +189,8 @@ export const maxGatewayAdapter = {
         catch {
             // probe failed, continue anyway
         }
-        ctx.log?.info(`[${account.accountId}] Starting MAX provider${botLabel}`);
-        const api = new MaxApi({ token });
+        ctx.log?.info(`[${account.accountId}] Starting MAX provider${botLabel}${route}`);
+        const api = new MaxApi({ token, network });
         // Register bot commands if configured
         const commands = ctx.cfg.channels?.max?.commands;
         if (commands?.length) {