@foxden-app/foxclaw 0.5.51 → 0.5.53

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 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.53 - 2026-06-20
+
+### 中文
+- 修复单 bot 默认 runtime 的 `telegram-voice-delivery` 无法找到私聊的问题：当 `CODEX_HOME` 不含 bot ID 时，`send-voice` 现在会从唯一配置的 Telegram token 安全补全 bot ID，再读取已经记录的私聊目标。
+- 将内置 `telegram-voice-delivery` Skill 的触发说明、工作流和 UI 元数据改为中文，并明确只有确实没有私聊记录时才要求用户发送 `/status`。
+
+### English
+- Fixed `telegram-voice-delivery` failing to find the private chat in a single-bot default runtime. When `CODEX_HOME` has no bot ID, `send-voice` now safely derives it from the only configured Telegram token before reading the remembered chat target.
+- Localized the bundled `telegram-voice-delivery` skill instructions and UI metadata into Chinese, and clarified that users should only be asked to send `/status` when no private chat is actually remembered.
+
+## 0.5.52 - 2026-06-20
+
+### 中文
+- 新增 `telegram-voice-delivery` Codex Skill；FoxClaw 启动时会把它同步到每个 Telegram runtime 的 `CODEX_HOME`，Codex 生成音频后可自动投递到当前 Telegram 私聊，不再要求用户输入 `/voice file`。
+- 新增 `foxclaw send-voice <path> [caption]` CLI；它会从当前 `CODEX_HOME` 识别 bot，并从 FoxClaw 本地数据库读取该 bot 最近记录的私聊目标。
+- CLI 支持 `--bot-id`、`--chat-id` 显式覆盖，复用 Telegram voice 的格式和 50MB 限制，并且不会输出或暴露 bot token。
+
+### English
+- Added the `telegram-voice-delivery` Codex skill. FoxClaw syncs it into every Telegram runtime's `CODEX_HOME` at startup, allowing Codex to automatically deliver generated audio to the current Telegram private chat without asking the user to enter `/voice file`.
+- Added `foxclaw send-voice <path> [caption]`; it infers the bot from the current `CODEX_HOME` and reads that bot's most recently remembered private chat from the FoxClaw store.
+- The CLI supports explicit `--bot-id` and `--chat-id` overrides, reuses Telegram voice format and 50MB limits, and never prints bot tokens.
+
 ## 0.5.51 - 2026-06-20
 
 ### 中文

package/README.md

@@ -310,7 +310,7 @@ foxclaw weixin-login
 
 ## Codex Skill
 
-仓库自带一个 Codex skill。用法看 [FoxClaw Skill 中文说明](./docs/zh/foxclaw-skill.md)。它可以让 Codex 通过 SSH 在本机或远程 Mac 上 bootstrap FoxClaw——写 `.env`、构建、跑 doctor、装 launchd、引导首次消息验证，一条龙。
+仓库自带 FoxClaw 安装维护 Skill 和 `telegram-voice-delivery` 语音投递 Skill。用法看 [FoxClaw Skill 中文说明](./docs/zh/foxclaw-skill.md)。FoxClaw 启动时会把语音投递 Skill 自动同步到每个 Telegram runtime 的 `CODEX_HOME`；Codex 生成音频后可直接执行 `foxclaw send-voice`，自动把文件送回当前 Telegram 私聊，无需用户再输入 `/voice file`。
 
 ## 故障排查
 

package/README_EN.md

@@ -310,7 +310,7 @@ Weixin runtime files default to `~/.foxclaw/weixin`. When `TG_BOT_TOKENS` is ena
 
 ## Codex Skill
 
-This repo ships a Codex skill at [`skills/foxclaw`](./skills/foxclaw). Use it when you want Codex to bootstrap FoxClaw locally or on another Mac over SSH — write `.env`, build, run doctor, install launchd, and guide first-message validation.
+This repo ships the FoxClaw deployment skill and a [`telegram-voice-delivery`](./skills/telegram-voice-delivery) skill. FoxClaw automatically syncs the delivery skill into every Telegram runtime's `CODEX_HOME` at startup. Codex can then run `foxclaw send-voice` after generating audio and deliver the file to the current Telegram private chat without asking the user to enter `/voice file`.
 
 ## Troubleshooting
 

package/dist/codex_skills.d.ts

@@ -0,0 +1 @@
+export declare function installBundledCodexSkills(packageRoot: string, codexHome: string): string[];

package/dist/codex_skills.js

@@ -0,0 +1,16 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const BUNDLED_CODEX_SKILLS = ['telegram-voice-delivery'];
+export function installBundledCodexSkills(packageRoot, codexHome) {
+    const installed = [];
+    for (const skillName of BUNDLED_CODEX_SKILLS) {
+        const sourceDir = path.join(packageRoot, 'skills', skillName);
+        if (!fs.existsSync(path.join(sourceDir, 'SKILL.md')))
+            continue;
+        const destinationDir = path.join(codexHome, 'skills', skillName);
+        fs.mkdirSync(destinationDir, { recursive: true, mode: 0o700 });
+        fs.cpSync(sourceDir, destinationDir, { recursive: true, force: true });
+        installed.push(skillName);
+    }
+    return installed;
+}

package/dist/controller/controller.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { TELEGRAM_VOICE_MAX_BYTES, TELEGRAM_VOICE_SUPPORTED_EXTENSIONS, telegramVoiceContentType, } from '../voice/files.js';
 import { normalizeLocale, t } from '../i18n.js';
 import { chatGptAuthMetadataMatchesCandidateName, parseChatGptAuthMetadata, readChatGptAuthRecord, readChatGptAuthMetadata, } from '../auth/mirror.js';
 import { readAccessTokenExpiresAtMs } from '../auth/cross_node_sync.js';
@@ -5205,7 +5206,7 @@ export class BridgeSessionCore {
         if (!contentType) {
             await this.sendMessage(scopeId, locale === 'zh'
                 ? '只支持作为 Telegram voice 发送的音频格式：.ogg、.opus、.oga、.mp3、.m4a。'
-                : 'Supported Telegram voice file formats: .ogg, .opus, .oga, .mp3, .m4a.');
+                : `Supported Telegram voice file formats: ${TELEGRAM_VOICE_SUPPORTED_EXTENSIONS}.`);
             return;
         }
         const stat = await fs.stat(filePath).catch(() => null);
@@ -5213,7 +5214,7 @@ export class BridgeSessionCore {
             await this.sendMessage(scopeId, locale === 'zh' ? `找不到音频文件：${filePath}` : `Audio file not found: ${filePath}`);
             return;
         }
-        if (stat.size > 50 * 1024 * 1024) {
+        if (stat.size > TELEGRAM_VOICE_MAX_BYTES) {
             await this.sendMessage(scopeId, locale === 'zh' ? 'Telegram voice 文件不能超过 50MB。' : 'Telegram voice files must be 50MB or smaller.');
             return;
         }
@@ -8496,21 +8497,6 @@ function ensureTurnSegment(active, itemId, phase, outputKind, isPlan) {
     active.segments.push(segment);
     return segment;
 }
-function telegramVoiceContentType(filePath) {
-    const extension = path.extname(filePath).toLowerCase();
-    switch (extension) {
-        case '.ogg':
-        case '.oga':
-        case '.opus':
-            return 'audio/ogg';
-        case '.mp3':
-            return 'audio/mpeg';
-        case '.m4a':
-            return 'audio/mp4';
-        default:
-            return null;
-    }
-}
 function renderCollapsedCommentary(locale, segments) {
     const firstAt = segments[0]?.startedAtMs ?? Date.now();
     const lastSegment = segments[segments.length - 1];

package/dist/main.js

@@ -9,11 +9,14 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { APP_HOME, DEFAULT_CODEX_TELEGRAM_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PATH, DEFAULT_STATUS_PATH, getLoadedEnvPath, loadConfig, loadEnv, } from './config.js';
 import { createAuthRefreshNotificationAggregator, } from './auth/notifications.js';
+import { installBundledCodexSkills } from './codex_skills.js';
 import { acquireProcessLock, LockHeldError } from './lock.js';
 import { readRuntimeStatus, writeRuntimeStatus } from './runtime.js';
 import { buildFoxclawLaunchdPlistText, extractNodePathFromLaunchdPlist, } from './launchd.js';
 import { buildFoxclawSystemdUnitText, buildSystemdRestartHelperArgs, cgroupContainsSystemdUnit, refreshFoxclawExecStartDropIns, removeFoxclawExecStartDropIns, } from './systemd.js';
 import { clearPendingClusterUpdateBroadcast, createSelfUpdateRuntime, inferPnpmHomeFromEntryPoint, performSelfUpdate, readPendingClusterUpdateBroadcast, readSelfUpdateStatus, writeSelfUpdateStatus, } from './update.js';
+import { TELEGRAM_VOICE_MAX_BYTES, TELEGRAM_VOICE_SUPPORTED_EXTENSIONS, telegramVoiceContentType, } from './voice/files.js';
+import { inferTelegramBotId, resolveTelegramVoiceTarget } from './voice/target.js';
 const rawCommand = process.argv[2];
 const command = rawCommand || 'serve';
 loadEnv();
@@ -227,6 +230,11 @@ async function main() {
         await runWeixinLoginCli();
         return;
     }
+    if (command === 'send-voice' || command === 'voice-file') {
+        requireNode24(command);
+        await runSendVoiceCli();
+        return;
+    }
     if (command !== 'serve') {
         console.error(`Unknown command: ${command}`);
         printUsage();
@@ -263,12 +271,91 @@ Usage:
   foxclaw status
   foxclaw start|restart|stop
   foxclaw update
+  foxclaw send-voice <path> [caption]
   foxclaw install-systemd|uninstall-systemd
   foxclaw install-launchd|uninstall-launchd
   foxclaw weixin-login [account-id]
   foxclaw --version
   foxclaw --help`);
 }
+async function runSendVoiceCli() {
+    const parsed = parseSendVoiceCliArgs(process.argv.slice(3));
+    if (!parsed.fileArg) {
+        console.error('Usage: foxclaw send-voice <path> [caption] [--bot-id <bot-id>] [--chat-id <chat-id>]');
+        process.exitCode = 1;
+        return;
+    }
+    const config = loadConfig();
+    const filePath = path.resolve(config.defaultCwd, parsed.fileArg);
+    const contentType = telegramVoiceContentType(filePath);
+    if (!contentType) {
+        throw new Error(`Unsupported Telegram voice file format. Supported formats: ${TELEGRAM_VOICE_SUPPORTED_EXTENSIONS}.`);
+    }
+    const stat = await fs.promises.stat(filePath).catch(() => null);
+    if (!stat?.isFile()) {
+        throw new Error(`Audio file not found: ${filePath}`);
+    }
+    if (stat.size > TELEGRAM_VOICE_MAX_BYTES) {
+        throw new Error('Telegram voice files must be 50MB or smaller.');
+    }
+    const inferredBotId = parsed.botId ?? inferTelegramBotId(process.env.CODEX_HOME) ?? inferTelegramBotId(config.codexHome);
+    const { botId, botToken } = resolveTelegramVoiceTarget(config.tgBotTokens, inferredBotId);
+    const { BridgeStore } = await import('./store/database.js');
+    const store = new BridgeStore(config.storePath);
+    let chatId = parsed.chatId;
+    try {
+        chatId ??= botId ? store.getTelegramPrivateScope(botId)?.chatId ?? null : null;
+    }
+    finally {
+        store.close();
+    }
+    if (!chatId) {
+        const target = botId ? ` for ${botId}` : '';
+        throw new Error(`No remembered Telegram private chat${target}. Send /status to the bot once, or pass --chat-id <chat-id>.`);
+    }
+    const contents = await fs.promises.readFile(filePath);
+    const { callTelegramMultipartApi } = await import('./telegram/api.js');
+    const result = await callTelegramMultipartApi(botToken, 'sendVoice', {
+        chat_id: chatId,
+        caption: parsed.caption || 'FoxClaw voice',
+    }, [{
+            fieldName: 'voice',
+            filename: path.basename(filePath),
+            contents,
+            contentType,
+        }]);
+    if (!result.ok || !result.result) {
+        throw new Error(result.description || 'Telegram sendVoice failed.');
+    }
+    console.log(`Sent Telegram voice message ${result.result.message_id}: ${filePath}`);
+}
+function parseSendVoiceCliArgs(args) {
+    const positional = [];
+    let botId = null;
+    let chatId = null;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--bot-id' || arg === '--chat-id') {
+            const value = args[index + 1]?.trim();
+            if (!value) {
+                throw new Error(`${arg} requires a value.`);
+            }
+            if (arg === '--bot-id')
+                botId = value;
+            else
+                chatId = value;
+            index += 1;
+            continue;
+        }
+        positional.push(arg);
+    }
+    return {
+        fileArg: positional[0]?.trim() || null,
+        caption: positional.slice(1).join(' ').trim(),
+        botId,
+        chatId,
+    };
+}
 function formatRuntimeStatusSummary(status) {
     const lines = [];
     const age = formatAge(status.updatedAt);
@@ -388,6 +475,7 @@ async function runServeCli() {
                 if (!sharedDefaultRuntime) {
                     fs.mkdirSync(home, { recursive: true, mode: 0o700 });
                 }
+                installBundledCodexSkills(packageRoot, home);
                 const runtimeConfig = {
                     ...config,
                     tgBotToken: token,
@@ -670,6 +758,8 @@ async function runServeCli() {
             process.on('SIGTERM', () => void shutdown('SIGTERM'));
             return;
         }
+        const singleCodexHome = config.codexHome ?? path.join(os.homedir(), '.codex');
+        installBundledCodexSkills(packageRoot, singleCodexHome);
         const bot = new TelegramGateway(config.tgBotToken, config.tgAllowedUserId, config.tgAllowedChatId, config.telegramPollIntervalMs, store, logger);
         const app = new CodexAppClient(config.codexCliBin, config.codexAppLaunchCmd, config.codexAppAutolaunch, config.codexAppServerStatePath, config.codexAppServerLogPath, logger);
         const telegramMessaging = new TelegramMessagingPort(bot);

package/dist/voice/files.d.ts

@@ -0,0 +1,3 @@
+export declare const TELEGRAM_VOICE_MAX_BYTES: number;
+export declare const TELEGRAM_VOICE_SUPPORTED_EXTENSIONS = ".ogg, .opus, .oga, .mp3, .m4a";
+export declare function telegramVoiceContentType(filePath: string): string | null;

package/dist/voice/files.js

@@ -0,0 +1,18 @@
+import path from 'node:path';
+export const TELEGRAM_VOICE_MAX_BYTES = 50 * 1024 * 1024;
+export const TELEGRAM_VOICE_SUPPORTED_EXTENSIONS = '.ogg, .opus, .oga, .mp3, .m4a';
+export function telegramVoiceContentType(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    switch (extension) {
+        case '.ogg':
+        case '.oga':
+        case '.opus':
+            return 'audio/ogg';
+        case '.mp3':
+            return 'audio/mpeg';
+        case '.m4a':
+            return 'audio/mp4';
+        default:
+            return null;
+    }
+}

package/dist/voice/target.d.ts

@@ -0,0 +1,6 @@
+export type TelegramVoiceTarget = {
+    botId: string;
+    botToken: string;
+};
+export declare function inferTelegramBotId(codexHome: string | null | undefined): string | null;
+export declare function resolveTelegramVoiceTarget(tokens: string[], requestedBotId: string | null): TelegramVoiceTarget;

package/dist/voice/target.js

@@ -0,0 +1,23 @@
+export function inferTelegramBotId(codexHome) {
+    if (!codexHome)
+        return null;
+    const match = codexHome.match(/(?:^|[\\/])(bot\d+)(?:[\\/]|$)/i);
+    return match?.[1]?.toLowerCase() ?? null;
+}
+export function resolveTelegramVoiceTarget(tokens, requestedBotId) {
+    if (requestedBotId) {
+        const numericId = requestedBotId.replace(/^bot/i, '');
+        const matched = tokens.find(token => token.startsWith(`${numericId}:`));
+        if (matched)
+            return { botId: `bot${numericId}`, botToken: matched };
+        throw new Error(`No configured Telegram token matches ${requestedBotId}. Pass --bot-id for a configured bot.`);
+    }
+    if (tokens.length === 1) {
+        const botToken = tokens[0];
+        const numericId = botToken.slice(0, botToken.indexOf(':'));
+        if (/^\d+$/.test(numericId)) {
+            return { botId: `bot${numericId}`, botToken };
+        }
+    }
+    throw new Error('Cannot infer the Telegram bot from this Codex session. Pass --bot-id <bot-id>.');
+}

package/docs/zh/foxclaw-skill.md

@@ -2,6 +2,8 @@
 
 仓库内置的 `skills/foxclaw` 是给 Codex 使用的安装技能。它的用途是让 Codex 在本机或远程 Mac 上自动完成 FoxClaw bootstrap，包括写 `.env`、安装依赖、构建、跑 `doctor`、安装 launchd 服务，并引导你完成第一次 Telegram 消息验证。
 
+仓库还内置 `skills/telegram-voice-delivery`。FoxClaw 启动时会把它自动同步到每个 Telegram runtime 的 `CODEX_HOME`。当 Codex 已经生成音频时，它会直接运行 `foxclaw send-voice <path> [caption]`，从当前 `CODEX_HOME` 识别 Telegram bot，并将音频投递到该 bot 最近记录的私聊，不需要用户再输入命令。
+
 ## 适合什么时候用
 
 - 你想让 Codex 通过 SSH 帮另一台 Mac 安装 FoxClaw。

package/package.json

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

package/skills/telegram-voice-delivery/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: telegram-voice-delivery
+description: 通过 FoxClaw 将 Codex 已生成或找到的语音、解说、播客等音频文件直接发送到当前 Telegram 会话。需要把音频交付给用户且不应要求用户手动执行 FoxClaw 命令时使用。
+---
+
+# Telegram 语音投递
+
+把已经完成的音频直接发送到当前 FoxClaw Telegram 私聊，不要让用户操作 `/voice`。
+
+## 操作流程
+
+1. 确认音频文件已经完整生成。
+2. 优先使用适合 Telegram 语音播放的 `.ogg` 或 `.opus`；也支持 `.oga`、`.mp3` 和 `.m4a`。
+3. 文件不得超过 50MB。
+4. 执行：
+
+```bash
+foxclaw send-voice "/音频的绝对路径/audio.ogg" "简短说明"
+```
+
+5. 命令成功即表示 Telegram 已接收该语音；随后简短告知用户已经发送。
+
+FoxClaw 会从 `CODEX_HOME` 推断当前 Telegram bot；单 bot 默认 runtime 会从唯一配置的 token 补全 bot ID。随后从本地数据库读取该 bot 最近记录的私聊，并调用 Telegram `sendVoice`。不要读取、打印或泄露 Telegram bot token。
+
+音频已经存在时直接发送，不要重新生成。只有 FoxClaw 明确报告没有记录私聊时，才请用户对当前 bot 发送一次 `/status`；仅在自动会话推断确实不可用时使用 `--bot-id <bot-id>` 或 `--chat-id <chat-id>`，不要凭猜测指定其他 bot。

package/skills/telegram-voice-delivery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Telegram 语音投递"
+  short_description: "把 Codex 已生成的音频直接发送到当前 Telegram 会话"
+  default_prompt: "使用 $telegram-voice-delivery，把已完成的音频文件发送到当前 Telegram 会话。"