@foxden-app/foxclaw 0.5.67 → 0.5.69

package/.env.example

@@ -45,6 +45,11 @@ DEFAULT_APPROVAL_POLICY=on-request
 DEFAULT_SANDBOX_MODE=workspace-write
 TELEGRAM_POLL_INTERVAL_MS=1200
 TELEGRAM_PREVIEW_THROTTLE_MS=800
+# Optional: route Telegram Bot API calls through a Local Bot API Server.
+# Useful for large video/media delivery; official local server supports much
+# larger uploads than the public https://api.telegram.org endpoint.
+# TELEGRAM_BOT_API_BASE_URL=http://127.0.0.1:8081
+# TELEGRAM_BOT_API_TIMEOUT_MS=1800000
 # Delete folded operation-detail messages after the final answer is sent.
 # Set to false if you prefer to keep "read files / edited files / ran command"
 # detail cards in the chat history.

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.69 - 2026-07-11
+
+### 中文
+- 修复 pnpm 11 的自更新路径解析：`pnpm root -g` 在 pnpm 11 返回全局目录本身（例如 `.../global/v11`），而不是旧版返回的 `node_modules` 目录。FoxClaw 现在同时识别两种布局，升级后可以正确执行自检和服务重启。
+
+### English
+- Fixed self-update path resolution for pnpm 11. `pnpm root -g` now returns the global directory itself (for example `.../global/v11`) rather than the `node_modules` directory returned by earlier pnpm versions. FoxClaw now recognizes both layouts and can correctly run post-update checks and restart the service.
+
+## 0.5.68 - 2026-07-01
+
+### 中文
+- 新增 `foxclaw send-media <path> [caption]`，Codex 生成图片、封面、截图、GIF、视频或其他文件后，可以直接投递到当前 Telegram 私聊；FoxClaw 会按文件类型选择 `sendPhoto`、`sendVideo`、`sendAnimation` 或 `sendDocument`。
+- 新增内置 `telegram-media-delivery` skill，并随 Telegram runtime 自动同步到 `CODEX_HOME`，让 Codex 像发送语音一样发送视觉产物；`sendVideo` 默认启用 `supports_streaming=true`，提升 MP4 在 Telegram 客户端中的在线播放体验。
+- Telegram Bot API endpoint 现在可通过 `TELEGRAM_BOT_API_BASE_URL` 配置为 Local Bot API Server，并可用 `TELEGRAM_BOT_API_TIMEOUT_MS` 调大上传超时，适合交付 25 分钟这类大视频。
+
+### English
+- Added `foxclaw send-media <path> [caption]`, allowing Codex-generated images, covers, screenshots, GIFs, videos, and other files to be delivered directly to the current Telegram private chat. FoxClaw selects `sendPhoto`, `sendVideo`, `sendAnimation`, or `sendDocument` by file type.
+- Added the bundled `telegram-media-delivery` skill and sync it into each Telegram runtime's `CODEX_HOME`, so Codex can deliver visual artifacts like it already delivers voice files. `sendVideo` enables `supports_streaming=true` for better inline MP4 playback in Telegram clients.
+- Telegram Bot API endpoint calls can now use `TELEGRAM_BOT_API_BASE_URL` for a Local Bot API Server, with `TELEGRAM_BOT_API_TIMEOUT_MS` for longer uploads, making 25-minute video delivery practical when the file size exceeds public Bot API limits.
+
 ## 0.5.67 - 2026-07-01
 
 ### 中文

package/README.md

@@ -310,7 +310,7 @@ foxclaw weixin-login
 
 ## Codex Skill
 
-仓库自带 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`。
+仓库自带 FoxClaw 安装维护 Skill、`telegram-voice-delivery` 语音投递 Skill 和 `telegram-media-delivery` 媒体投递 Skill。用法看 [FoxClaw Skill 中文说明](./docs/zh/foxclaw-skill.md)。FoxClaw 启动时会把投递 Skill 自动同步到每个 Telegram runtime 的 `CODEX_HOME`；Codex 生成音频、图片、封面、截图或视频后可直接执行 `foxclaw send-voice` / `foxclaw send-media`，自动把文件送回当前 Telegram 私聊。
 
 ## 故障排查
 

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 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`.
+This repo ships the FoxClaw deployment skill, [`telegram-voice-delivery`](./skills/telegram-voice-delivery), and [`telegram-media-delivery`](./skills/telegram-media-delivery). FoxClaw automatically syncs the delivery skills into every Telegram runtime's `CODEX_HOME` at startup. Codex can then run `foxclaw send-voice` or `foxclaw send-media` after generating audio, images, covers, screenshots, or videos and deliver the file to the current Telegram private chat.
 
 ## Troubleshooting
 

package/dist/codex_skills.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-const BUNDLED_CODEX_SKILLS = ['telegram-voice-delivery'];
+const BUNDLED_CODEX_SKILLS = ['telegram-voice-delivery', 'telegram-media-delivery'];
 export function installBundledCodexSkills(packageRoot, codexHome) {
     const installed = [];
     for (const skillName of BUNDLED_CODEX_SKILLS) {

package/dist/main.js

@@ -36,6 +36,7 @@ const PROXY_ENV_KEYS = [
 const STANDARD_NODE_PROXY_ENV_KEYS = ['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy'];
 const LOCAL_AUTH_REFRESH_LEASE_TTL_MS = 10 * 60_000;
 const CLUSTER_UPDATE_BROADCAST_PATH = path.join(APP_HOME, 'runtime', 'pending-cluster-update-broadcast.json');
+const TELEGRAM_PUBLIC_BOT_API_UPLOAD_HINT_BYTES = 50 * 1024 * 1024;
 function createClusterUpdateScheduler(options) {
     let pending = null;
     let timer = null;
@@ -236,6 +237,11 @@ async function main() {
         await runSendVoiceCli();
         return;
     }
+    if (command === 'send-media' || command === 'media-file') {
+        requireNode24(command);
+        await runSendMediaCli();
+        return;
+    }
     if (command !== 'serve') {
         console.error(`Unknown command: ${command}`);
         printUsage();
@@ -273,6 +279,7 @@ Usage:
   foxclaw start|restart|stop
   foxclaw update
   foxclaw send-voice <path> [caption]
+  foxclaw send-media <path> [caption]
   foxclaw install-systemd|uninstall-systemd
   foxclaw install-launchd|uninstall-launchd
   foxclaw weixin-login [account-id]
@@ -330,6 +337,59 @@ async function runSendVoiceCli() {
     }
     console.log(`Sent Telegram voice message ${result.result.message_id}: ${filePath}`);
 }
+async function runSendMediaCli() {
+    const parsed = parseSendVoiceCliArgs(process.argv.slice(3));
+    if (!parsed.fileArg) {
+        console.error('Usage: foxclaw send-media <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 stat = await fs.promises.stat(filePath).catch(() => null);
+    if (!stat?.isFile()) {
+        throw new Error(`Media file not found: ${filePath}`);
+    }
+    const plan = planTelegramOutboundMedia(filePath);
+    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>.`);
+    }
+    if (stat.size > TELEGRAM_PUBLIC_BOT_API_UPLOAD_HINT_BYTES && !isLocalTelegramBotApiConfigured()) {
+        console.warn([
+            `Media is ${formatBytes(stat.size)}. Public Telegram Bot API uploads may reject large files.`,
+            'For long videos, configure TELEGRAM_BOT_API_BASE_URL to a Local Bot API Server.',
+        ].join(' '));
+    }
+    const contents = await fs.promises.readFile(filePath);
+    const { callTelegramMultipartApi } = await import('./telegram/api.js');
+    const fields = {
+        chat_id: chatId,
+        ...(parsed.caption ? { caption: parsed.caption } : {}),
+        ...(plan.kind === 'video' ? { supports_streaming: 'true' } : {}),
+    };
+    const result = await callTelegramMultipartApi(botToken, plan.method, fields, [{
+            fieldName: plan.fieldName,
+            filename: path.basename(filePath),
+            contents,
+            contentType: plan.contentType,
+        }]);
+    if (!result.ok || !result.result) {
+        throw new Error(result.description || `Telegram ${plan.method} failed.`);
+    }
+    console.log(`Sent Telegram ${plan.kind} message ${result.result.message_id}: ${filePath}`);
+}
 function parseSendVoiceCliArgs(args) {
     const positional = [];
     let botId = null;
@@ -357,6 +417,52 @@ function parseSendVoiceCliArgs(args) {
         chatId,
     };
 }
+function planTelegramOutboundMedia(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    switch (extension) {
+        case '.jpg':
+        case '.jpeg':
+            return { kind: 'photo', method: 'sendPhoto', fieldName: 'photo', contentType: 'image/jpeg' };
+        case '.png':
+            return { kind: 'photo', method: 'sendPhoto', fieldName: 'photo', contentType: 'image/png' };
+        case '.webp':
+            return { kind: 'photo', method: 'sendPhoto', fieldName: 'photo', contentType: 'image/webp' };
+        case '.gif':
+            return { kind: 'animation', method: 'sendAnimation', fieldName: 'animation', contentType: 'image/gif' };
+        case '.mp4':
+        case '.m4v':
+            return { kind: 'video', method: 'sendVideo', fieldName: 'video', contentType: 'video/mp4' };
+        case '.mov':
+            return { kind: 'video', method: 'sendVideo', fieldName: 'video', contentType: 'video/quicktime' };
+        case '.pdf':
+            return { kind: 'document', method: 'sendDocument', fieldName: 'document', contentType: 'application/pdf' };
+        case '.json':
+            return { kind: 'document', method: 'sendDocument', fieldName: 'document', contentType: 'application/json' };
+        case '.md':
+            return { kind: 'document', method: 'sendDocument', fieldName: 'document', contentType: 'text/markdown' };
+        case '.txt':
+            return { kind: 'document', method: 'sendDocument', fieldName: 'document', contentType: 'text/plain' };
+        case '.zip':
+            return { kind: 'document', method: 'sendDocument', fieldName: 'document', contentType: 'application/zip' };
+        default:
+            return { kind: 'document', method: 'sendDocument', fieldName: 'document', contentType: 'application/octet-stream' };
+    }
+}
+function isLocalTelegramBotApiConfigured() {
+    const value = process.env.TELEGRAM_BOT_API_BASE_URL?.trim();
+    return Boolean(value && !/^https:\/\/api\.telegram\.org\/?$/i.test(value));
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    const kib = bytes / 1024;
+    if (kib < 1024)
+        return `${kib.toFixed(1)}KiB`;
+    const mib = kib / 1024;
+    if (mib < 1024)
+        return `${mib.toFixed(1)}MiB`;
+    return `${(mib / 1024).toFixed(2)}GiB`;
+}
 function formatRuntimeStatusSummary(status) {
     const lines = [];
     const age = formatAge(status.updatedAt);

package/dist/telegram/api.js

@@ -1,17 +1,15 @@
 import fs from 'node:fs';
+import http from 'node:http';
 import https from 'node:https';
 import path from 'node:path';
 import { pipeline } from 'node:stream/promises';
-const API_HOST = 'api.telegram.org';
+const DEFAULT_API_BASE_URL = 'https://api.telegram.org';
 export async function callTelegramApi(botToken, method, body) {
     const payload = JSON.stringify(body);
+    const endpoint = telegramApiUrl(botToken, method);
     return new Promise((resolve, reject) => {
-        const request = https.request({
-            host: API_HOST,
-            port: 443,
-            path: `/bot${botToken}/${method}`,
+        const request = requestForUrl(endpoint, {
             method: 'POST',
-            family: 4,
             headers: {
                 'content-type': 'application/json',
                 'content-length': Buffer.byteLength(payload),
@@ -32,7 +30,7 @@ export async function callTelegramApi(botToken, method, body) {
             });
         });
         request.on('error', reject);
-        request.setTimeout(20_000, () => {
+        request.setTimeout(telegramApiTimeoutMs(false), () => {
             request.destroy(new Error(`Telegram API request timed out for ${method}`));
         });
         request.write(payload);
@@ -52,13 +50,10 @@ export async function callTelegramMultipartApi(botToken, method, fields, files)
     }
     parts.push(Buffer.from(`--${boundary}--\r\n`, 'utf8'));
     const payload = Buffer.concat(parts);
+    const endpoint = telegramApiUrl(botToken, method);
     return new Promise((resolve, reject) => {
-        const request = https.request({
-            host: API_HOST,
-            port: 443,
-            path: `/bot${botToken}/${method}`,
+        const request = requestForUrl(endpoint, {
             method: 'POST',
-            family: 4,
             headers: {
                 'content-type': `multipart/form-data; boundary=${boundary}`,
                 'content-length': payload.length,
@@ -79,7 +74,7 @@ export async function callTelegramMultipartApi(botToken, method, fields, files)
             });
         });
         request.on('error', reject);
-        request.setTimeout(20_000, () => {
+        request.setTimeout(telegramApiTimeoutMs(true), () => {
             request.destroy(new Error(`Telegram API request timed out for ${method}`));
         });
         request.write(payload);
@@ -98,13 +93,9 @@ export async function downloadTelegramFile(botToken, remoteFilePath, destination
     const tempPath = `${destinationPath}.tmp-${process.pid}-${Date.now()}`;
     let response = null;
     try {
+        const endpoint = telegramFileUrl(botToken, remoteFilePath);
         response = await new Promise((resolve, reject) => {
-            const request = https.get({
-                host: API_HOST,
-                port: 443,
-                path: `/file/bot${botToken}/${remoteFilePath}`,
-                family: 4,
-            }, (incoming) => {
+            const request = getForUrl(endpoint, (incoming) => {
                 const statusCode = incoming.statusCode ?? 500;
                 if (statusCode >= 400) {
                     incoming.resume();
@@ -114,7 +105,7 @@ export async function downloadTelegramFile(botToken, remoteFilePath, destination
                 resolve(incoming);
             });
             request.on('error', reject);
-            request.setTimeout(20_000, () => {
+            request.setTimeout(telegramApiTimeoutMs(true), () => {
                 request.destroy(new Error(`Telegram file download timed out for ${remoteFilePath}`));
             });
         });
@@ -137,3 +128,41 @@ export async function downloadTelegramFile(botToken, remoteFilePath, destination
 function escapeMultipartName(value) {
     return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\r', '').replaceAll('\n', '');
 }
+function telegramApiBaseUrl() {
+    const raw = process.env.TELEGRAM_BOT_API_BASE_URL?.trim() || DEFAULT_API_BASE_URL;
+    return raw.replace(/\/+$/g, '');
+}
+function telegramApiUrl(botToken, method) {
+    return new URL(`${telegramApiBaseUrl()}/bot${botToken}/${method}`);
+}
+function telegramFileUrl(botToken, remoteFilePath) {
+    return new URL(`${telegramApiBaseUrl()}/file/bot${botToken}/${remoteFilePath}`);
+}
+function telegramApiTimeoutMs(multipart) {
+    const raw = Number.parseInt(process.env.TELEGRAM_BOT_API_TIMEOUT_MS ?? '', 10);
+    if (Number.isFinite(raw) && raw > 0) {
+        return raw;
+    }
+    return multipart ? 300_000 : 20_000;
+}
+function requestForUrl(url, options, callback) {
+    const client = url.protocol === 'http:' ? http : https;
+    return client.request({
+        ...options,
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || undefined,
+        path: `${url.pathname}${url.search}`,
+        family: url.hostname === 'localhost' ? undefined : 4,
+    }, callback);
+}
+function getForUrl(url, callback) {
+    const client = url.protocol === 'http:' ? http : https;
+    return client.get({
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || undefined,
+        path: `${url.pathname}${url.search}`,
+        family: url.hostname === 'localhost' ? undefined : 4,
+    }, callback);
+}

package/dist/update.d.ts

@@ -85,5 +85,6 @@ export declare function performSelfUpdate(options: PerformSelfUpdateOptions): Se
 export declare function readPendingClusterUpdateBroadcast(filePath: string): PendingClusterUpdateBroadcast | null;
 export declare function writePendingClusterUpdateBroadcast(filePath: string, value: PendingClusterUpdateBroadcast): void;
 export declare function clearPendingClusterUpdateBroadcast(filePath: string): void;
+export declare function resolveFoxclawEntryPointFromGlobalRoot(globalRoot: string, exists?: (target: string) => boolean): string | null;
 export declare function extractReleaseNotes(changelog: string, version: string, locale: AppLocale): string[] | null;
 export {};

package/dist/update.js

@@ -472,6 +472,15 @@ function runInherited(command, args, env) {
         throw new Error(`${command} ${args.join(' ')} exited with status ${result.status ?? 'unknown'}.`);
     }
 }
+export function resolveFoxclawEntryPointFromGlobalRoot(globalRoot, exists = fs.existsSync) {
+    // pnpm <= 10 prints the global node_modules directory; pnpm >= 11 prints
+    // the global directory itself. Accept both documented layouts.
+    const candidates = [
+        path.join(globalRoot, '@foxden-app', 'foxclaw', 'dist', 'main.js'),
+        path.join(globalRoot, 'node_modules', '@foxden-app', 'foxclaw', 'dist', 'main.js'),
+    ];
+    return candidates.find(candidate => exists(candidate)) ?? null;
+}
 function resolveUpdatedEntryPoint(installer, env) {
     const result = spawnSync(installer.command, installer.rootArgs, { encoding: 'utf8', env });
     if (result.error) {
@@ -484,9 +493,9 @@ function resolveUpdatedEntryPoint(installer, env) {
     if (!globalRoot) {
         throw new Error(`Could not locate the updated global package root using ${installer.manager}.`);
     }
-    const updatedEntryPoint = path.join(globalRoot, '@foxden-app', 'foxclaw', 'dist', 'main.js');
-    if (!fs.existsSync(updatedEntryPoint)) {
-        throw new Error(`Updated FoxClaw entry point was not found at ${updatedEntryPoint}.`);
+    const updatedEntryPoint = resolveFoxclawEntryPointFromGlobalRoot(globalRoot);
+    if (!updatedEntryPoint) {
+        throw new Error(`Updated FoxClaw entry point was not found below ${globalRoot} (checked direct and node_modules layouts).`);
     }
     return updatedEntryPoint;
 }

package/docs/user-manual.md

@@ -250,6 +250,17 @@ Later commands are sorted by recent usage. Plain text, photos, and files continu
 
 These are useful when the phone-side model, permission, or provider behavior does not match what you expected.
 
+### 3.4 Media delivery CLI
+
+Codex can deliver generated files back to the current Telegram private chat without asking you to run a Telegram command manually:
+
+```bash
+foxclaw send-voice /absolute/path/audio.ogg "caption"
+foxclaw send-media /absolute/path/output.mp4 "caption"
+```
+
+`send-media` auto-selects Telegram `sendPhoto`, `sendVideo`, `sendAnimation`, or `sendDocument` based on the file extension. MP4 videos are sent with `supports_streaming=true`, so Telegram clients can play them inline when the file is encoded compatibly. For long videos, prefer H.264/AAC MP4. Public Bot API uploads can reject large files; configure a Local Bot API Server with `TELEGRAM_BOT_API_BASE_URL` and a longer `TELEGRAM_BOT_API_TIMEOUT_MS` when delivering large media.
+
 ## 4. The `/setup` Panel
 
 `/setup` is one of the main mobile panels. Settings are scoped to the chat, so private chat, group, and topic can use different settings.

package/docs/zh/foxclaw-skill.md

@@ -2,7 +2,7 @@
 
 仓库内置的 `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 最近记录的私聊，不需要用户再输入命令。
+仓库还内置 `skills/telegram-voice-delivery` 和 `skills/telegram-media-delivery`。FoxClaw 启动时会把它们自动同步到每个 Telegram runtime 的 `CODEX_HOME`。当 Codex 已经生成音频、图片、封面、截图或视频时，它会直接运行 `foxclaw send-voice <path> [caption]` 或 `foxclaw send-media <path> [caption]`，从当前 `CODEX_HOME` 识别 Telegram bot，并将文件投递到该 bot 最近记录的私聊，不需要用户再输入命令。
 
 ## 适合什么时候用
 

package/docs/zh/user-manual.md

@@ -250,6 +250,17 @@ TG_ALLOWED_TOPIC_ID=42
 
 这些命令适合排查“为什么手机上跑出来的权限、模型或 provider 和预期不同”。
 
+### 3.4 媒体投递 CLI
+
+Codex 可以把已经生成的文件直接送回当前 Telegram 私聊，不需要你手动输入 Telegram 命令：
+
+```bash
+foxclaw send-voice /absolute/path/audio.ogg "说明"
+foxclaw send-media /absolute/path/output.mp4 "说明"
+```
+
+`send-media` 会按文件扩展名自动选择 Telegram `sendPhoto`、`sendVideo`、`sendAnimation` 或 `sendDocument`。MP4 视频会带 `supports_streaming=true`，只要编码兼容，Telegram 客户端就可以内联播放。长视频建议使用 H.264/AAC MP4。公网 Bot API 上传大文件可能被拒绝；需要交付大视频时，建议配置 Local Bot API Server，并设置 `TELEGRAM_BOT_API_BASE_URL` 和更长的 `TELEGRAM_BOT_API_TIMEOUT_MS`。
+
 ## 4. `/setup` 会话设置面板
 
 `/setup` 是手机端最重要的面板之一。它按聊天范围保存设置，私聊、群组、topic 可以有不同设置。

package/package.json

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

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

@@ -0,0 +1,37 @@
+---
+name: telegram-media-delivery
+description: 通过 FoxClaw 将 Codex 已生成或找到的图片、封面、截图、视频、GIF 或其他媒体文件直接发送到当前 Telegram 会话。需要把视觉产物交付给用户且不应要求用户手动执行 FoxClaw 命令时使用。
+---
+
+# Telegram 媒体投递
+
+把已经完成的图片、视频或其他媒体文件直接发送到当前 FoxClaw Telegram 私聊，不要让用户手动下载或操作 `/media`。
+
+## 操作流程
+
+1. 确认文件已经完整生成，并优先使用绝对路径。
+2. 图片优先使用 `.jpg`、`.jpeg`、`.png` 或 `.webp`。
+3. 视频优先使用可流式播放的 `.mp4`，编码建议 H.264/AAC；`.mov` 可尝试发送，但客户端兼容性不如 MP4。
+4. GIF 使用 `.gif`，FoxClaw 会按 Telegram animation 发送。
+5. 执行：
+
+```bash
+foxclaw send-media "/文件的绝对路径/output.mp4" "简短说明"
+```
+
+6. 命令成功即表示 Telegram 已接收媒体；随后简短告知用户已经发送。
+
+FoxClaw 会从 `CODEX_HOME` 推断当前 Telegram bot；单 bot 默认 runtime 会从唯一配置的 token 补全 bot ID。随后从本地数据库读取该 bot 最近记录的私聊，并调用 Telegram `sendPhoto`、`sendVideo`、`sendAnimation` 或 `sendDocument`。不要读取、打印或泄露 Telegram bot token。
+
+文件已经存在时直接发送，不要重新生成。只有 FoxClaw 明确报告没有记录私聊时，才请用户对当前 bot 发送一次 `/status`；仅在自动会话推断确实不可用时使用 `--bot-id <bot-id>` 或 `--chat-id <chat-id>`，不要凭猜测指定其他 bot。
+
+## 大视频
+
+公网 Telegram Bot API 对大文件上传限制更严格。25 分钟视频通常应先压成可流式播放 MP4，并尽量控制体积；如果文件明显超过几十 MB，优先建议 FoxClaw 主机配置 Local Bot API Server，并设置：
+
+```bash
+TELEGRAM_BOT_API_BASE_URL=http://127.0.0.1:8081
+TELEGRAM_BOT_API_TIMEOUT_MS=1800000
+```
+
+Local Bot API Server 支持更大的上传体积；公网 Bot API 失败时，不要反复重试同一个大文件，先压缩或改用本地 Bot API Server。