@aspalagin/openclaw-max 0.7.3 → 0.8.1

package/src/api.ts

@@ -9,14 +9,24 @@
  * (Минцифры) 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,
+  type MaxNetwork,
+  MaxNetworkConfigError,
+  scrubProxyCredentials,
+} from './network.js';
+import { getMaxLogger } from './runtime.js';
 import { RUSSIAN_TRUSTED_ROOT_CA, RUSSIAN_TRUSTED_SUB_CA } from './russian-trusted-ca.js';
 import type {
   MaxBotCommand,
@@ -65,12 +75,6 @@ export type {
   MaxVideoInfo,
 } from './types.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
@@ -109,15 +113,39 @@ export function setMaxFetchForTests(fetchImpl: FetchLike | undefined): void {
 }
 
 let cachedDispatcher: Agent | undefined;
+const proxyDispatchers = new Map<string, ProxyAgent>();
+
+/** CA set for MAX hosts: system roots (with NODE_EXTRA_CA_CERTS) + Russian Trusted CA. */
+function maxCaList(): string[] {
+  const tlsWithCaList = tls as unknown as {
+    getCACertificates?: (type: string) => readonly string[];
+  };
+  // 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: string, proxyUrl?: string): Agent | ProxyAgent {
+  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 getMaxDispatcher(): Agent {
+function getDirectMaxDispatcher(): Agent {
   if (!cachedDispatcher) {
-    const tlsWithCaList = tls as unknown as {
-      getCACertificates?: (type: string) => readonly string[];
-    };
-    // 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
@@ -130,7 +158,7 @@ function getMaxDispatcher(): Agent {
         const err = args[0];
         const elapsedMs = Date.now() - startedAt;
         if (err || elapsedMs > MAX_SLOW_CONNECT_MS) {
-          console.error(
+          getMaxLogger().error(
             `[MAX API] connect ${options.hostname} ${err ? 'failed' : 'slow'} dns+tcp+tls=${elapsedMs}ms` +
               (err ? ` (${err.name})` : ''),
           );
@@ -143,12 +171,21 @@ function getMaxDispatcher(): Agent {
   return cachedDispatcher;
 }
 
-function maxFetch(url: string, init: Record<string, unknown>): ReturnType<FetchLike> {
-  if (testFetchOverride) return testFetchOverride(url, init);
-  return undiciFetch(url, {
-    ...init,
-    dispatcher: getMaxDispatcher(),
-  } as Parameters<typeof undiciFetch>[1]) as unknown as ReturnType<FetchLike>;
+async function maxFetch(
+  url: string,
+  init: Record<string, unknown>,
+  proxyUrl?: string,
+): ReturnType<FetchLike> {
+  try {
+    if (testFetchOverride) return await testFetchOverride(url, init);
+    return (await undiciFetch(url, {
+      ...init,
+      dispatcher: getMaxDispatcher(url, proxyUrl),
+    } as Parameters<typeof undiciFetch>[1])) as unknown as Awaited<ReturnType<FetchLike>>;
+  } catch (err) {
+    // Proxy failures may quote the proxy URL; its credentials never leave here.
+    throw scrubProxyCredentials(err, proxyUrl);
+  }
 }
 
 function escapeMultipartHeaderValue(value: string): string {
@@ -184,7 +221,13 @@ function buildMultipartFileBody(
 
 export interface MaxApiOptions {
   token: string;
+  /** Overrides the API base URL of the network settings (tests). */
   baseUrl?: string;
+  /**
+   * Network settings for this client; default: those bound to the token by
+   * resolveMaxAccount (network.ts), else the public endpoint, direct.
+   */
+  network?: MaxNetwork;
   timeoutMs?: number;
   /** Retry attempts for transient errors (429 / 502-504 / network). 0 disables. Default 3. */
   retryAttempts?: number;
@@ -244,6 +287,14 @@ 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<string, number>();
+
+/** @internal Forget remembered bot ids (test isolation). */
+export function resetMaxBotUserIdsForTests(): void {
+  botUserIds.clear();
+}
+
 /** @internal Fresh process-wide send limiter (test isolation). */
 export function resetMaxSendLimiterForTests(): void {
   sharedSendLimiter = new MaxChatSendLimiter();
@@ -293,6 +344,7 @@ export class MaxRequestTimeoutError extends Error {
  * duplicate the message — only a definite 429 (never applied) is retried.
  */
 function isRetryableError(err: unknown, idempotent: boolean): boolean {
+  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) return idempotent;
@@ -312,7 +364,8 @@ const IDEMPOTENT_METHODS = new Set(['GET', 'PUT', 'DELETE']);
 
 export class MaxApi {
   private token: string;
-  private baseUrl: string;
+  private baseUrl: string | undefined;
+  private explicitNetwork: MaxNetwork | undefined;
   private timeoutMs: number;
   private retryAttempts: number;
   private sendLimiter: MaxChatSendLimiter | null;
@@ -323,7 +376,8 @@ 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 =
@@ -332,6 +386,20 @@ export class MaxApi {
 
   // ── HTTP helpers ──
 
+  /**
+   * Current network settings, read per request so a config reload applies to
+   * long-lived clients too. Throws MaxNetworkConfigError for a bad config.
+   */
+  private network(): MaxNetwork {
+    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(): string | undefined {
+    return this.network().proxyUrl;
+  }
+
   private async requestOnce<T>(
     method: string,
     path: string,
@@ -340,7 +408,9 @@ export class MaxApi {
     timeoutMs?: number,
     externalSignal?: AbortSignal,
   ): Promise<T> {
-    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) url.searchParams.set(k, String(v));
@@ -363,15 +433,19 @@ export class MaxApi {
       : controller.signal;
 
     try {
-      const res = await maxFetch(url.toString(), {
-        method,
-        headers: {
-          Authorization: this.token,
-          ...(body ? { 'Content-Type': 'application/json' } : {}),
+      const res = await maxFetch(
+        url.toString(),
+        {
+          method,
+          headers: {
+            Authorization: this.token,
+            ...(body ? { 'Content-Type': 'application/json' } : {}),
+          },
+          body: body ? JSON.stringify(body) : undefined,
+          signal,
         },
-        body: body ? JSON.stringify(body) : undefined,
-        signal,
-      });
+        network.proxyUrl,
+      );
       gotResponse = true;
 
       const json = (await res.json().catch(() => null)) as T;
@@ -381,13 +455,15 @@ 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,
@@ -410,7 +486,7 @@ 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(
+        getMaxLogger().error(
           `[MAX API] ${method} ${path} timed out after ${elapsedMs}ms (phase=${phase})`,
         );
         throw new MaxRequestTimeoutError(method, path, elapsedMs, phase);
@@ -418,7 +494,7 @@ export class MaxApi {
       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(
+        getMaxLogger().error(
           `[MAX API] ${method} ${path} failed after ${elapsedMs}ms: ${(err as Error).name}`,
         );
       }
@@ -458,7 +534,14 @@ export class MaxApi {
   // ── Bot info ──
 
   async getMe(): Promise<MaxUser> {
-    return this.request<MaxUser>('GET', '/me');
+    const me = await this.request<MaxUser>('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(): Promise<number> {
+    return botUserIds.get(this.tokenKey) ?? (await this.getMe()).user_id;
   }
 
   // ── Messages ──
@@ -542,8 +625,20 @@ export class MaxApi {
 
   // ── Chat actions ──
 
-  async sendAction(chatId: number, action: MaxSenderAction): Promise<MaxSimpleResult> {
-    return this.request('POST', `/chats/${chatId}/actions`, undefined, { action });
+  async sendAction(
+    chatId: number,
+    action: MaxSenderAction,
+    opts?: { timeoutMs?: number; retryAttempts?: number; signal?: AbortSignal },
+  ): Promise<MaxSimpleResult> {
+    return this.request(
+      'POST',
+      `/chats/${chatId}/actions`,
+      undefined,
+      { action },
+      opts?.timeoutMs,
+      opts?.retryAttempts,
+      opts?.signal,
+    );
   }
 
   // ── Callbacks ──
@@ -627,19 +722,23 @@ export class MaxApi {
   }
 
   /**
-   * 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: 'image' | 'video' | 'audio' | 'file',
-    data: string | Buffer | Uint8Array,
+    data: Buffer | Uint8Array,
     contentType?: string,
+    fileName = 'file',
   ): Promise<{ token: string; url?: string }> {
     // Step 1: Get upload URL and attachment token.
     // MAX returns the attachment token together with the upload URL. The
@@ -648,68 +747,26 @@ export class MaxApi {
     const uploadInfo = await this.getUploadUrl(type);
     const uploadUrl = uploadInfo.url;
 
-    // Step 2: Load file if data is a path
-    let fileBuffer: Buffer;
-    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: Record<string, string> = {
-          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';
-    }
+    const fileBuffer = Buffer.from(data);
+    const mimeType = contentType ?? 'application/octet-stream';
 
-    // Step 3: POST file as multipart/form-data to upload URL. MAX upload hosts
+    // 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);
 
-    const uploadRes = await maxFetch(uploadUrl, {
-      method: 'POST',
-      headers: {
-        'Content-Type': multipart.contentType,
-        'Content-Length': String(multipart.body.byteLength),
+    const uploadRes = await maxFetch(
+      uploadUrl,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': multipart.contentType,
+          'Content-Length': String(multipart.body.byteLength),
+        },
+        body: multipart.body,
       },
-      body: multipart.body,
-    });
+      this.network().proxyUrl,
+    );
 
     if (!uploadRes.ok) {
       throw new MaxApiError(
@@ -719,7 +776,7 @@ export class MaxApi {
       );
     }
 
-    // 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(() => ({}))) as Record<string, unknown>;

package/src/callbacks.ts

@@ -7,8 +7,9 @@
 import { resolveApprovalOverGateway } from 'openclaw/plugin-sdk/approval-gateway-runtime';
 import { questionGatewayRuntime } from 'openclaw/plugin-sdk/question-gateway-runtime';
 
-import type { ResolvedMaxAccount } from './accounts.js';
+import { admitMaxGroupMessage } from './access-policy.js';
 import type { MaxCallback, MaxMessage } from './api.js';
+import { decodeMaxCommandMenuPayload } from './command-menu.js';
 import { processIncomingMessage } from './inbound.js';
 import type { MaxMonitorOptions } from './monitor-types.js';
 import { decodeMaxPresentationCallback, type MaxPresentationCallback } from './presentation.js';
@@ -53,7 +54,17 @@ export async function processCallback(
   // 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 as const,
+    });
+    await processIncomingMessage(menuMessage, userLocale, opts);
     return;
   }
   // Opaque callback data goes to the agent labelled, never as a slash command.
@@ -68,30 +79,38 @@ export async function processCallback(
 /**
  * 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: ResolvedMaxAccount,
+  opts: MaxMonitorOptions,
+  message: MaxMessage | null,
   senderId: string,
   kind: 'approval' | 'question',
 ): boolean {
+  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: Extract<MaxPresentationCallback, { kind: 'approval' | 'question' }>,
   callback: MaxCallback,
+  message: MaxMessage | null,
   opts: MaxMonitorOptions,
 ): Promise<void> {
   const { account, config, log } = opts;
   const senderId = String(callback.user.user_id);
   let notification: string;
 
-  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}`,
     );
@@ -117,7 +136,7 @@ async function resolveMaxRuntimeControlCallback(
           questionId: action.questionId,
           optionValue: action.optionValue,
           senderId,
-          authorize: () => isMaxRuntimeControlSender(account, senderId, 'question'),
+          authorize: () => isMaxRuntimeControlSender(opts, message, senderId, 'question'),
         });
         notification =
           result.status === 'answered'

package/src/channel-agent-prompt.ts

@@ -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.
  */
 
 import type { ChannelPlugin } from 'openclaw/plugin-sdk/channel-core';
@@ -17,31 +18,19 @@ export const maxAgentPromptAdapter: NonNullable<MaxChannelPlugin['agentPrompt']>
     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/src/channel-config.ts

@@ -13,7 +13,14 @@ import {
   setAccountEnabledInConfigSection,
 } from 'openclaw/plugin-sdk/core';
 
-import { listMaxAccountIds, type ResolvedMaxAccount, resolveMaxAccount } from './accounts.js';
+import {
+  isMaxAccountConfigured,
+  listMaxAccountIds,
+  readMaxAccount,
+  type ResolvedMaxAccount,
+  resolveMaxAccount,
+} from './accounts.js';
+import { resolveMaxTransport } from './monitor-types.js';
 
 type MaxChannelPlugin = ChannelPlugin<ResolvedMaxAccount>;
 
@@ -21,6 +28,24 @@ type MaxChannelPlugin = ChannelPlugin<ResolvedMaxAccount>;
 export const maxConfigAdapter: NonNullable<MaxChannelPlugin['config']> = {
   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 }) =>
@@ -40,14 +65,18 @@ export const maxConfigAdapter: NonNullable<MaxChannelPlugin['config']> = {
       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 }) =>