@foxden-app/foxclaw 0.5.46 → 0.5.48

package/.env.example

@@ -53,6 +53,21 @@ CODEX_CLI_BIN=/absolute/path/to/codex
 # toggle this at runtime and writes AUTH_AUTO_DELETE_NEEDS_REPAIR back here.
 # AUTH_AUTO_DELETE_NEEDS_REPAIR=false
 
+# Optional Telegram voice summaries.
+# When enabled, completed final answers get a "listen" button and /voice can
+# generate Telegram voice messages. SSH mode runs TTS and ffmpeg conversion on
+# the speech host; HTTP mode calls VOICE_TTS_URL and converts locally.
+# VOICE_TTS_ENABLED=false
+# VOICE_TTS_MODE=ssh
+# VOICE_TTS_SSH_HOST=thinkbook16p
+# VOICE_TTS_SSH_DIR=/home/wuya/dev/qwen-speech-server
+# VOICE_TTS_DESIGN_INSTRUCT=用自然清晰的中文女声朗读，语速适中。
+# VOICE_SUMMARY_BUTTON_ENABLED=true
+# VOICE_TEXT_LIMIT=2800
+# VOICE_TTS_URL=https://tts.foxden.app
+# VOICE_TTS_TOKEN=
+# VOICE_FFMPEG_BIN=ffmpeg
+
 # Optional: standard HTTP(S) proxy for Telegram and ChatGPT/Codex backend requests.
 # Put these in the same env file that `foxclaw start` installs into systemd/launchd.
 # FoxClaw passes them to the service and enables Node's env proxy support.

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.5.48 - 2026-06-20
+
+### 中文
+- 新增 Telegram 总结语音能力：最终答复完成后可附带“听总结”按钮，点击后由 FoxClaw 调用语音服务生成 OGG/OPUS 并通过 Telegram `sendVoice` 发回聊天。
+- 新增 `/voice <文本>` 和 `/voice last`，便于直接测试任意文本或最近一次最终总结的朗读效果；微信通道会明确提示当前不支持语音消息。
+- 支持 SSH 语音后端和 HTTP 语音后端两种模式；SSH 模式可直接使用 16p 上的 Qwen TTS 服务和远端 `ffmpeg` 转码，并在 custom speaker 不可用时自动降级到 VoiceDesign endpoint。
+
+### English
+- Added Telegram voice summaries: completed final answers can include a "Listen" button that asks FoxClaw to synthesize OGG/OPUS audio and return it through Telegram `sendVoice`.
+- Added `/voice <text>` and `/voice last` for quick manual checks against arbitrary text or the latest final answer; Weixin scopes now get an explicit unsupported-channel message.
+- Supports both SSH and HTTP speech backends. SSH mode can use the Qwen TTS service and remote `ffmpeg` on the 16p host, and automatically falls back to the VoiceDesign endpoint when custom speakers are unavailable.
+
+## 0.5.47 - 2026-06-20
+
+### 中文
+- 修复远端 auth 候选已成功导入后，`/auth` 面板仍保留旧的 `needs_repair`/禁用状态，导致候选显示问号且无法切换的问题。
+- 远端导入成功现在会恢复该候选的全局状态和各 Telegram runtime 覆盖状态为 active/enabled，确保“确认可用后文件和 UI 状态一致”。
+- 增加 mirror 远端导入 hook 回归测试，避免后续同步链路再次只更新 auth 文件、不恢复健康标记。
+
+### English
+- Fixed `/auth` keeping stale `needs_repair`/disabled state after a remote auth candidate was successfully imported, which left the candidate shown with a question mark and blocked switching.
+- Successful remote imports now restore the candidate's global state and each Telegram runtime override to active/enabled, keeping the UI state aligned with validated auth files.
+- Added a regression test for the mirror remote-import hook so future sync changes do not update auth files without clearing health markers.
+
 ## 0.5.46 - 2026-06-20
 
 ### 中文

package/dist/auth/mirror.d.ts

@@ -61,6 +61,7 @@ export interface AuthMirrorSyncAllResult {
 }
 export interface AuthMirrorHooks {
     onSynced?: (event: AuthMirrorSyncedEvent) => Promise<void> | void;
+    onRemoteImported?: (event: AuthMirrorSyncedEvent) => Promise<void> | void;
 }
 export type AuthMirrorNotification = {
     kind: 'local_synced';

package/dist/auth/mirror.js

@@ -304,6 +304,16 @@ export class AuthCandidateMirror {
                     sourceLabel,
                 };
                 await Promise.allSettled(this.runtimes.map((target) => target.notify?.(notification)));
+                await this.hooks.onRemoteImported?.({
+                    status: this.lastStatus,
+                    record: {
+                        raw,
+                        ...metadata,
+                        candidateName,
+                        sourceRuntimeId: `remote:${source.nodeId}`,
+                        sourceLabel,
+                    },
+                });
                 return {
                     ok: true,
                     imported: true,

package/dist/channels/bridge_messaging_router.d.ts

@@ -17,6 +17,7 @@ export declare class BridgeMessagingRouter {
     sendHtml(scopeId: string, text: string, keyboard?: InlineKeyboard): Promise<number>;
     sendRichHtml(scopeId: string, html: string, fallbackHtml: string, keyboard?: InlineKeyboard): Promise<number>;
     sendRichMarkdown(scopeId: string, markdown: string, fallbackText: string, keyboard?: InlineKeyboard): Promise<number>;
+    sendVoice(scopeId: string, filename: string, contents: Buffer, caption?: string): Promise<number>;
     editPlain(scopeId: string, messageId: number, text: string, keyboard?: InlineKeyboard): Promise<void>;
     editHtml(scopeId: string, messageId: number, text: string, keyboard?: InlineKeyboard): Promise<void>;
     editRichHtml(scopeId: string, messageId: number, html: string, fallbackHtml: string, keyboard?: InlineKeyboard): Promise<void>;

package/dist/channels/bridge_messaging_router.js

@@ -49,6 +49,12 @@ export class BridgeMessagingRouter {
         }
         return this.telegram.sendRichMarkdown(scopeId, markdown, keyboard);
     }
+    sendVoice(scopeId, filename, contents, caption) {
+        if (this.isWeixinScope(scopeId)) {
+            throw new Error(`Voice messages are not supported for Weixin scope ${scopeId}`);
+        }
+        return this.telegram.sendVoice(scopeId, filename, contents, caption);
+    }
     editPlain(scopeId, messageId, text, keyboard) {
         if (this.isWeixinScope(scopeId)) {
             return this.requireWeixinTransport(scopeId).editPlain(scopeId, messageId, text, keyboard);

package/dist/channels/telegram/telegram_messaging_port.d.ts

@@ -15,6 +15,7 @@ export declare class TelegramMessagingPort implements ChannelPort {
     sendHtml(bridgeScopeId: string, text: string, inlineKeyboard?: InlineKeyboard): Promise<number>;
     sendRichHtml(bridgeScopeId: string, html: string, inlineKeyboard?: InlineKeyboard): Promise<number>;
     sendRichMarkdown(bridgeScopeId: string, markdown: string, inlineKeyboard?: InlineKeyboard): Promise<number>;
+    sendVoice(bridgeScopeId: string, filename: string, contents: Buffer, caption?: string): Promise<number>;
     editPlain(bridgeScopeId: string, messageId: number, text: string, inlineKeyboard?: InlineKeyboard): Promise<void>;
     editHtml(bridgeScopeId: string, messageId: number, text: string, inlineKeyboard?: InlineKeyboard): Promise<void>;
     editRichHtml(bridgeScopeId: string, messageId: number, html: string, inlineKeyboard?: InlineKeyboard): Promise<void>;

package/dist/channels/telegram/telegram_messaging_port.js

@@ -24,6 +24,10 @@ export class TelegramMessagingPort {
         const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
         return this.gateway.sendRichMessage(target.chatId, telegramRichMarkdown(markdown, { skipEntityDetection: true }), inlineKeyboard, target.topicId);
     }
+    async sendVoice(bridgeScopeId, filename, contents, caption) {
+        const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
+        return this.gateway.sendVoice(target.chatId, filename, contents, caption, target.topicId);
+    }
     async editPlain(bridgeScopeId, messageId, text, inlineKeyboard) {
         const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
         await this.gateway.editMessage(target.chatId, messageId, text, inlineKeyboard);

package/dist/config.d.ts

@@ -63,6 +63,16 @@ export interface AppConfig {
     authSyncStatePath: string;
     authSyncTempDir: string;
     authAutoDeleteNeedsRepair: boolean;
+    voiceTtsEnabled: boolean;
+    voiceTtsMode: 'http' | 'ssh';
+    voiceTtsUrl: string | null;
+    voiceTtsToken: string | null;
+    voiceTtsSshHost: string;
+    voiceTtsSshDir: string;
+    voiceTtsDesignInstruct: string;
+    voiceFfmpegBin: string;
+    voiceSummaryButtonEnabled: boolean;
+    voiceTextLimit: number;
 }
 export declare function loadConfig(): AppConfig;
 export declare function selectDefaultRuntimeBotToken(configuredTokens: string[], legacyToken: string | null): string | null;

package/dist/config.js

@@ -97,6 +97,16 @@ export function loadConfig() {
         authSyncStatePath: process.env.AUTH_SYNC_STATE_PATH || DEFAULT_AUTH_SYNC_STATE_PATH,
         authSyncTempDir: process.env.AUTH_SYNC_TEMP_DIR || DEFAULT_AUTH_SYNC_TEMP_DIR,
         authAutoDeleteNeedsRepair: boolEnv('AUTH_AUTO_DELETE_NEEDS_REPAIR', false),
+        voiceTtsEnabled: boolEnv('VOICE_TTS_ENABLED', false),
+        voiceTtsMode: parseVoiceTtsMode(process.env.VOICE_TTS_MODE || (process.env.VOICE_TTS_URL?.trim() ? 'http' : 'ssh')),
+        voiceTtsUrl: optional('VOICE_TTS_URL') ?? 'https://tts.foxden.app',
+        voiceTtsToken: optional('VOICE_TTS_TOKEN'),
+        voiceTtsSshHost: process.env.VOICE_TTS_SSH_HOST?.trim() || 'thinkbook16p',
+        voiceTtsSshDir: process.env.VOICE_TTS_SSH_DIR?.trim() || '/home/wuya/dev/qwen-speech-server',
+        voiceTtsDesignInstruct: process.env.VOICE_TTS_DESIGN_INSTRUCT?.trim() || '用自然清晰的中文女声朗读，语速适中。',
+        voiceFfmpegBin: process.env.VOICE_FFMPEG_BIN?.trim() || 'ffmpeg',
+        voiceSummaryButtonEnabled: boolEnv('VOICE_SUMMARY_BUTTON_ENABLED', true),
+        voiceTextLimit: intEnv('VOICE_TEXT_LIMIT', 2800),
     };
     ensureAppDirs(config);
     return config;
@@ -182,6 +192,9 @@ function parseSandboxMode(value) {
         return value;
     return 'workspace-write';
 }
+function parseVoiceTtsMode(value) {
+    return value.trim().toLowerCase() === 'http' ? 'http' : 'ssh';
+}
 function resolveCommand(commandName) {
     try {
         const which = process.platform === 'win32' ? 'where' : 'which';

package/dist/controller/controller.d.ts

@@ -89,6 +89,8 @@ export declare class BridgeSessionCore {
     private approvalTimers;
     private submittedUserInputTimers;
     private restartPreviewRecoveryTimers;
+    private voiceSnippets;
+    private latestVoiceSnippetByScope;
     private selfUpdatePollTimer;
     private proactiveAuthRefreshTimer;
     private proactiveAuthRefreshInProgress;
@@ -316,6 +318,9 @@ export declare class BridgeSessionCore {
     private handleAccountCommand;
     private handleQuotaCommand;
     private handleQuotaNudgeCommand;
+    private handleVoiceCommand;
+    private handleVoiceCallback;
+    private sendVoiceForText;
     private handleLoginDeviceCommand;
     private handleLoginCancelCommand;
     private handleLogoutCommand;
@@ -470,5 +475,8 @@ export declare class BridgeSessionCore {
     private syncSegmentTimeline;
     private shouldPromoteSegmentToRich;
     private promoteSegmentMessagesToRich;
+    private voiceKeyboardForSegment;
+    private registerVoiceSnippet;
+    private pruneVoiceSnippets;
 }
 export { BridgeSessionCore as BridgeController };

package/dist/controller/controller.js

@@ -16,6 +16,7 @@ import { renderTelegramMarkdownRichHtml } from '../telegram/rich_markdown.js';
 import { isDefaultTelegramScope, resolveTelegramAddressing } from '../telegram/addressing.js';
 import { BRIDGE_SCOPE_WEIXIN_PREFIX, parseTelegramTargetFromBridgeScope, parseWeixinBridgeScope } from '../core/bridge_scope.js';
 import { resolveTelegramRenderRoute } from '../telegram/rendering.js';
+import { normalizeVoiceText, synthesizeTelegramVoice } from '../voice/tts.js';
 import { readCodexLocalUsageSnapshot, readCodexLocalUsageStats, writeCodexLocalUsageSnapshot, } from '../codex_app/local_usage.js';
 import { normalizeTurnActivityEvent, } from './activity.js';
 import { normalizeAccessPreset, resolveAccessMode } from './access.js';
@@ -143,6 +144,8 @@ export class BridgeSessionCore {
     approvalTimers = new Map();
     submittedUserInputTimers = new Map();
     restartPreviewRecoveryTimers = new Map();
+    voiceSnippets = new Map();
+    latestVoiceSnippetByScope = new Map();
     selfUpdatePollTimer = null;
     proactiveAuthRefreshTimer = null;
     proactiveAuthRefreshInProgress = false;
@@ -528,6 +531,10 @@ export class BridgeSessionCore {
                 await this.handleQuotaNudgeCommand(scopeId, locale, args);
                 return;
             }
+            case 'voice': {
+                await this.handleVoiceCommand(scopeId, locale, args);
+                return;
+            }
             case 'login':
             case 'login_device': {
                 await this.handleLoginDeviceCommand(scopeId, locale);
@@ -1078,6 +1085,11 @@ export class BridgeSessionCore {
             await this.handleConfigToggleCallback(event, configMatch[1] === 'on', locale);
             return;
         }
+        const voiceMatch = /^voice:([a-f0-9]+)$/.exec(event.data);
+        if (voiceMatch) {
+            await this.handleVoiceCallback(event, voiceMatch[1], locale);
+            return;
+        }
         const settingsMatch = /^settings:(model|effort|access):(.+)$/.exec(event.data);
         if (settingsMatch) {
             await this.handleSettingsCallback(event, settingsMatch[1], settingsMatch[2], locale);
@@ -5162,6 +5174,45 @@ export class BridgeSessionCore {
         await this.app.sendAddCreditsNudgeEmail(creditType);
         await this.sendMessage(scopeId, t(locale, 'quota_nudge_sent'));
     }
+    async handleVoiceCommand(scopeId, locale, args) {
+        const raw = args.join(' ').trim();
+        const snippetId = raw.toLowerCase() === 'last' ? this.latestVoiceSnippetByScope.get(scopeId) ?? null : null;
+        const text = snippetId ? this.voiceSnippets.get(snippetId)?.text ?? '' : raw;
+        if (!text) {
+            await this.sendMessage(scopeId, locale === 'zh' ? '用法：/voice 要朗读的文本，或 /voice last' : 'Usage: /voice text to read, or /voice last');
+            return;
+        }
+        await this.sendVoiceForText(scopeId, locale, text);
+    }
+    async handleVoiceCallback(event, localId, locale) {
+        const snippet = this.voiceSnippets.get(localId);
+        if (!snippet || snippet.scopeId !== event.scopeId) {
+            await this.messaging.answerCallback(event.callbackQueryId, locale === 'zh' ? '这条总结语音已过期' : 'This voice summary has expired');
+            return;
+        }
+        await this.messaging.answerCallback(event.callbackQueryId, locale === 'zh' ? '正在生成语音...' : 'Generating voice...');
+        await this.sendVoiceForText(event.scopeId, locale, snippet.text);
+    }
+    async sendVoiceForText(scopeId, locale, text) {
+        if (scopeId.startsWith(BRIDGE_SCOPE_WEIXIN_PREFIX)) {
+            await this.sendMessage(scopeId, locale === 'zh' ? '当前只有 Telegram 支持语音消息。' : 'Voice messages are currently supported only on Telegram.');
+            return;
+        }
+        if (!this.config.voiceTtsEnabled) {
+            await this.sendMessage(scopeId, locale === 'zh' ? '语音服务未启用。' : 'Voice TTS is not enabled.');
+            return;
+        }
+        try {
+            const voice = await synthesizeTelegramVoice(text, this.config);
+            await this.messaging.sendVoice(scopeId, voice.filename, voice.contents, locale === 'zh' ? 'FoxClaw 总结语音' : 'FoxClaw voice summary');
+        }
+        catch (error) {
+            this.logger.warn('voice.summary_failed', { scopeId, error: toErrorMeta(error) });
+            await this.sendMessage(scopeId, locale === 'zh'
+                ? `语音生成失败：${formatUserError(error)}`
+                : `Voice generation failed: ${formatUserError(error)}`);
+        }
+    }
     async handleLoginDeviceCommand(scopeId, locale) {
         const login = await this.app.startDeviceLogin();
         const oldLoginId = this.pendingLoginsByScope.get(scopeId);
@@ -8286,8 +8337,9 @@ export class BridgeSessionCore {
             if (existing.richHtml === chunk || existing.richFailedForText === chunk) {
                 continue;
             }
+            const keyboard = this.voiceKeyboardForSegment(active, segment, index, chunks.length);
             try {
-                await this.messaging.editRichMarkdown(active.scopeId, existing.messageId, chunk, chunk);
+                await this.messaging.editRichMarkdown(active.scopeId, existing.messageId, chunk, chunk, keyboard);
                 existing.richHtml = chunk;
                 existing.richFailedForText = null;
             }
@@ -8301,7 +8353,7 @@ export class BridgeSessionCore {
                 });
                 const richHtml = renderTelegramMarkdownRichHtml(chunk);
                 try {
-                    await this.messaging.editRichHtml(active.scopeId, existing.messageId, richHtml, escapeTelegramHtml(chunk));
+                    await this.messaging.editRichHtml(active.scopeId, existing.messageId, richHtml, escapeTelegramHtml(chunk), keyboard);
                     existing.richHtml = richHtml;
                     existing.richFailedForText = null;
                     continue;
@@ -8323,6 +8375,52 @@ export class BridgeSessionCore {
             }
         }
     }
+    voiceKeyboardForSegment(active, segment, chunkIndex, chunkCount) {
+        if (!this.config.voiceTtsEnabled
+            || !this.config.voiceSummaryButtonEnabled
+            || active.scopeId.startsWith(BRIDGE_SCOPE_WEIXIN_PREFIX)
+            || active.isObserved
+            || segment.outputKind !== 'final_answer'
+            || chunkIndex !== chunkCount - 1) {
+            return undefined;
+        }
+        const snippetId = segment.voiceSnippetId ?? this.registerVoiceSnippet(active.scopeId, segment.text);
+        segment.voiceSnippetId = snippetId;
+        const locale = this.localeForChat(active.scopeId);
+        return [[{
+                    text: locale === 'zh' ? '🔊 听总结' : '🔊 Listen',
+                    callback_data: `voice:${snippetId}`,
+                }]];
+    }
+    registerVoiceSnippet(scopeId, text) {
+        this.pruneVoiceSnippets();
+        const normalized = normalizeVoiceText(text, this.config.voiceTextLimit);
+        const id = crypto.randomBytes(6).toString('hex');
+        this.voiceSnippets.set(id, { scopeId, text: normalized, createdAt: Date.now() });
+        this.latestVoiceSnippetByScope.set(scopeId, id);
+        return id;
+    }
+    pruneVoiceSnippets() {
+        const expiresBefore = Date.now() - 24 * 60 * 60_000;
+        for (const [id, snippet] of this.voiceSnippets.entries()) {
+            if (snippet.createdAt < expiresBefore) {
+                this.voiceSnippets.delete(id);
+                if (this.latestVoiceSnippetByScope.get(snippet.scopeId) === id) {
+                    this.latestVoiceSnippetByScope.delete(snippet.scopeId);
+                }
+            }
+        }
+        while (this.voiceSnippets.size > 100) {
+            const oldest = [...this.voiceSnippets.entries()]
+                .sort((left, right) => left[1].createdAt - right[1].createdAt)[0];
+            if (!oldest)
+                break;
+            this.voiceSnippets.delete(oldest[0]);
+            if (this.latestVoiceSnippetByScope.get(oldest[1].scopeId) === oldest[0]) {
+                this.latestVoiceSnippetByScope.delete(oldest[1].scopeId);
+            }
+        }
+    }
 }
 function ensureTurnSegment(active, itemId, phase, outputKind, isPlan) {
     let segment = active.segments.find((entry) => entry.itemId === itemId);
@@ -8348,6 +8446,7 @@ function ensureTurnSegment(active, itemId, phase, outputKind, isPlan) {
         startedAtMs: Date.now(),
         completedAtMs: null,
         messages: [],
+        voiceSnippetId: null,
     };
     active.segments.push(segment);
     return segment;

package/dist/main.js

@@ -410,6 +410,7 @@ async function runServeCli() {
                 seeds.push({ id, home, authDir, sharedDefaultRuntime, config: runtimeConfig, bot, app });
             }
             let authSync = null;
+            const authRuntimeIds = seeds.map((runtime) => runtime.id);
             const mirror = new AuthCandidateMirror(canonicalAuthDir, seeds.map((runtime) => ({
                 id: runtime.id,
                 label: runtime.bot.username ? `@${runtime.bot.username}` : runtime.id,
@@ -423,6 +424,9 @@ async function runServeCli() {
                 onSynced: async (event) => {
                     await authSync?.publishCandidate(event.record.candidateName);
                 },
+                onRemoteImported: (event) => {
+                    restoreImportedAuthCandidateState(store, event.record.candidateName, authRuntimeIds);
+                },
             });
             await mirror.initialize();
             activeAuthMirror = mirror;
@@ -757,6 +761,9 @@ async function runServeCli() {
                 onSynced: async (event) => {
                     await singleAuthSync?.publishCandidate(event.record.candidateName);
                 },
+                onRemoteImported: (event) => {
+                    restoreImportedAuthCandidateState(store, event.record.candidateName, ['default']);
+                },
             });
             await singleMirror.initialize();
             activeAuthMirror = singleMirror;
@@ -863,6 +870,14 @@ async function runServeCli() {
         throw error;
     }
 }
+function restoreImportedAuthCandidateState(store, candidateName, runtimeIds) {
+    store.setCodexAuthCandidateState(candidateName, 'active');
+    store.setCodexAuthCandidateDisabled(candidateName, false);
+    for (const runtimeId of runtimeIds) {
+        store.setCodexAuthCandidateState(candidateName, 'active', runtimeId);
+        store.setCodexAuthCandidateDisabled(candidateName, false, runtimeId);
+    }
+}
 function createAuthMirrorNotifier(store, botId, bot, aggregator, options = {}) {
     return async (event) => {
         if (options.suppressBackgroundNotifications?.())

package/dist/telegram/gateway.d.ts

@@ -68,6 +68,7 @@ export declare class TelegramGateway extends EventEmitter {
         callback_data: string;
     }>>, messageThreadId?: number | null): Promise<number>;
     sendDocument(chatId: string, filename: string, contents: Buffer, caption?: string): Promise<number>;
+    sendVoice(chatId: string, filename: string, contents: Buffer, caption?: string, messageThreadId?: number | null): Promise<number>;
     sendMessageDraft(chatId: string, draftId: number, text: string, messageThreadId?: number | null): Promise<void>;
     sendRichMessageDraft(chatId: string, draftId: number, richMessage: TelegramInputRichMessage, messageThreadId?: number | null): Promise<void>;
     editMessage(chatId: string, messageId: number, text: string, inlineKeyboard?: Array<Array<{

package/dist/telegram/gateway.js

@@ -83,6 +83,22 @@ export class TelegramGateway extends EventEmitter {
         }
         return result.result.message_id;
     }
+    async sendVoice(chatId, filename, contents, caption, messageThreadId) {
+        const result = await callTelegramMultipartApi(this.botToken, 'sendVoice', {
+            chat_id: chatId,
+            ...(caption ? { caption } : {}),
+            ...(messageThreadId !== null && messageThreadId !== undefined ? { message_thread_id: String(messageThreadId) } : {}),
+        }, [{
+                fieldName: 'voice',
+                filename,
+                contents,
+                contentType: 'audio/ogg',
+            }]);
+        if (!result.ok || !result.result) {
+            throw new Error(result.description || 'Failed to send Telegram voice message');
+        }
+        return result.result.message_id;
+    }
     async sendMessageDraft(chatId, draftId, text, messageThreadId) {
         const result = await callTelegramApi(this.botToken, 'sendMessageDraft', {
             chat_id: chatId,

package/dist/voice/tts.d.ts

@@ -0,0 +1,8 @@
+import type { AppConfig } from '../config.js';
+export interface VoiceSynthesisResult {
+    filename: string;
+    contents: Buffer;
+    contentType: 'audio/ogg';
+}
+export declare function synthesizeTelegramVoice(text: string, config: AppConfig): Promise<VoiceSynthesisResult>;
+export declare function normalizeVoiceText(text: string, limit: number): string;

package/dist/voice/tts.js

@@ -0,0 +1,205 @@
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export async function synthesizeTelegramVoice(text, config) {
+    if (!config.voiceTtsEnabled) {
+        throw new Error('voice TTS is disabled');
+    }
+    const normalized = normalizeVoiceText(text, config.voiceTextLimit);
+    if (!normalized) {
+        throw new Error('voice text is empty');
+    }
+    const contents = config.voiceTtsMode === 'ssh'
+        ? await synthesizeViaSsh(normalized, config)
+        : await synthesizeViaHttp(normalized, config);
+    return {
+        filename: `foxclaw-summary-${Date.now()}.ogg`,
+        contents,
+        contentType: 'audio/ogg',
+    };
+}
+export function normalizeVoiceText(text, limit) {
+    const normalized = text
+        .replace(/```[\s\S]*?```/g, ' 代码块已省略。 ')
+        .replace(/`([^`]+)`/g, '$1')
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+        .replace(/!\[[^\]]*]\([^)]+\)/g, '')
+        .replace(/^#{1,6}\s+/gm, '')
+        .replace(/[*_~]{1,3}/g, '')
+        .replace(/^\s*[-*+]\s+/gm, ' - ')
+        .replace(/^\s*\d+\.\s+/gm, '')
+        .replace(/\|/g, ' ')
+        .replace(/[ \t]+/g, ' ')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return normalized.length > limit ? `${normalized.slice(0, Math.max(0, limit - 20)).trim()}。后文省略。` : normalized;
+}
+async function synthesizeViaHttp(text, config) {
+    if (!config.voiceTtsUrl) {
+        throw new Error('VOICE_TTS_URL is not configured');
+    }
+    try {
+        return convertToOggOpus(await requestTtsWav(config, '/v1/tts/custom', { text, language: 'zh' }), config.voiceFfmpegBin);
+    }
+    catch (error) {
+        if (!isNoCustomSpeakerError(error)) {
+            throw error;
+        }
+    }
+    const wav = await requestTtsWav(config, '/v1/tts/design', {
+        text,
+        language: 'zh',
+        instruct: config.voiceTtsDesignInstruct,
+    });
+    return convertToOggOpus(wav, config.voiceFfmpegBin);
+}
+async function requestTtsWav(config, pathname, body) {
+    if (!config.voiceTtsUrl) {
+        throw new Error('VOICE_TTS_URL is not configured');
+    }
+    const endpoint = new URL(pathname, config.voiceTtsUrl.endsWith('/') ? config.voiceTtsUrl : `${config.voiceTtsUrl}/`);
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            ...(config.voiceTtsToken ? { authorization: `Bearer ${config.voiceTtsToken}` } : {}),
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        throw new Error(`TTS request failed: ${response.status} ${response.statusText}: ${await response.text().catch(() => '')}`);
+    }
+    return Buffer.from(await response.arrayBuffer());
+}
+function isNoCustomSpeakerError(error) {
+    return error instanceof Error && error.message.includes('no supported speakers');
+}
+async function convertToOggOpus(input, ffmpegBin) {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'foxclaw-voice-'));
+    const inputPath = path.join(root, 'input.wav');
+    const outputPath = path.join(root, 'voice.ogg');
+    try {
+        await fs.writeFile(inputPath, input, { mode: 0o600 });
+        await execFileAsync(ffmpegBin, [
+            '-hide_banner',
+            '-loglevel',
+            'error',
+            '-y',
+            '-i',
+            inputPath,
+            '-ac',
+            '1',
+            '-c:a',
+            'libopus',
+            '-b:a',
+            '32k',
+            outputPath,
+        ], { timeout: 60_000, maxBuffer: 2 * 1024 * 1024 });
+        return await fs.readFile(outputPath);
+    }
+    finally {
+        await fs.rm(root, { recursive: true, force: true }).catch(() => { });
+    }
+}
+async function synthesizeViaSsh(text, config) {
+    const encodedText = Buffer.from(text, 'utf8').toString('base64');
+    const script = String.raw `set -euo pipefail
+TEXT="$(printf '%s' "$1" | base64 -d)"
+SERVICE_DIR="$2"
+cd "$SERVICE_DIR"
+set -a
+. ./.env
+set +a
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+TEXT="$TEXT" python3 - <<'PY' > "$tmp/body.json"
+import json
+import os
+print(json.dumps({"text": os.environ["TEXT"], "language": "zh"}, ensure_ascii=False))
+PY
+status="$(curl -sS -w '%{http_code}' -X POST http://127.0.0.1:18081/v1/tts/custom \
+  -H "Authorization: Bearer $QWEN_SPEECH_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data-binary "@$tmp/body.json" \
+  --output "$tmp/tts.wav")"
+if [[ "$status" != "200" ]]; then
+  if grep -q 'no supported speakers' "$tmp/tts.wav"; then
+    INSTRUCT="$3" TEXT="$TEXT" python3 - <<'PY' > "$tmp/body.json"
+import json
+import os
+print(json.dumps({
+    "text": os.environ["TEXT"],
+    "language": "zh",
+    "instruct": os.environ["INSTRUCT"],
+}, ensure_ascii=False))
+PY
+    status="$(curl -sS -w '%{http_code}' -X POST http://127.0.0.1:18081/v1/tts/design \
+      -H "Authorization: Bearer $QWEN_SPEECH_API_TOKEN" \
+      -H "Content-Type: application/json" \
+      --data-binary "@$tmp/body.json" \
+      --output "$tmp/tts.wav")"
+  fi
+fi
+if [[ "$status" != "200" ]]; then
+  python3 - "$tmp/tts.wav" <<'PY' >&2
+import pathlib
+import sys
+sys.stdout.buffer.write(pathlib.Path(sys.argv[1]).read_bytes())
+PY
+  exit 22
+fi
+ffmpeg -nostdin -hide_banner -loglevel error -y -i "$tmp/tts.wav" -ac 1 -c:a libopus -b:a 32k "$tmp/voice.ogg"
+python3 - "$tmp/voice.ogg" <<'PY'
+import pathlib
+import sys
+sys.stdout.buffer.write(pathlib.Path(sys.argv[1]).read_bytes())
+PY
+`;
+    return runSshBinary([
+        config.voiceTtsSshHost,
+        'bash',
+        '-s',
+        '--',
+        encodedText,
+        config.voiceTtsSshDir,
+        config.voiceTtsDesignInstruct,
+    ], script);
+}
+async function runSshBinary(args, stdin) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('ssh', args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        const stdout = [];
+        const stderr = [];
+        const timer = setTimeout(() => {
+            child.kill('SIGTERM');
+            reject(new Error('remote TTS timed out'));
+        }, 120_000);
+        child.stdout.on('data', (chunk) => {
+            stdout.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                reject(new Error(`remote TTS failed with exit ${code}: ${Buffer.concat(stderr).toString('utf8').trim()}`));
+                return;
+            }
+            const output = Buffer.concat(stdout);
+            if (output.length === 0) {
+                reject(new Error(`remote TTS returned empty audio: ${Buffer.concat(stderr).toString('utf8').trim()}`));
+                return;
+            }
+            resolve(output);
+        });
+        child.stdin.end(stdin);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.5.46",
+  "version": "0.5.48",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",