@wu529778790/open-im 1.10.9-beta.1 → 1.10.9-beta.11

package/README.md

@@ -4,6 +4,10 @@
 
 Multi-platform IM bridge for AI CLI tools. Connect Telegram, Feishu, WeCom, DingTalk, QQ, and WeChat (WorkBuddy) to Claude Code, Codex, and CodeBuddy — use your AI coding assistant from any phone or chat window.
 
+## Architecture
+
+![Open-IM Architecture](./diagram/architecture/open-im-architecture.svg)
+
 ## Features
 
 - **Six IM platforms** — Telegram, Feishu, WeCom, DingTalk, QQ, WorkBuddy
@@ -62,6 +66,27 @@ After `start`, the CLI prints the dashboard URL (default **`http://127.0.0.1:392
 
 Session state is stored in **`~/.open-im/data/sessions.json`** (per user, not IM chat logs).
 
+## Session continuity
+
+open-im and Claude Code CLI share the same session storage. When you work in the same directory, you can seamlessly switch between phone and computer.
+
+**Phone → Computer:** open-im automatically resumes the latest CLI session in the same directory — no configuration needed.
+
+**Computer → Phone:** use `claude --continue` (or `claude -c`) to pick up the conversation that was continued on open-im.
+
+```
+# On computer
+cd /my-project && claude        # work as usual, then Ctrl+C
+
+# On phone (via IM)
+"help me fix the login bug"     # open-im auto-resumes the same session
+
+# Back on computer
+claude -c                       # continues the phone conversation
+```
+
+> **Note:** only one side can be active at a time. Exit the CLI before sending messages from the phone, and vice versa.
+
 ## Configuration
 
 ### Per-platform AI

package/README.zh-CN.md

@@ -4,6 +4,10 @@
 
 多平台 IM 桥接：把 Telegram、飞书、企业微信、钉钉、QQ、微信（WorkBuddy）接到 Claude Code、Codex、CodeBuddy，在手机或聊天里使用 AI 编程助手。
 
+## 架构
+
+![Open-IM 架构图](./diagram/architecture/open-im-architecture.svg)
+
 ## 功能特性
 
 - **六个 IM 平台** — Telegram、飞书、企业微信、钉钉、QQ、WorkBuddy
@@ -62,6 +66,27 @@ npx @wu529778790/open-im start
 
 会话状态保存在 **`~/.open-im/data/sessions.json`**（按用户，与 IM 聊天记录无关）。
 
+## 会话接力
+
+open-im 和 Claude Code CLI 共享同一份 session 存储。在同一个目录下，手机和电脑可以无缝切换。
+
+**手机接电脑：** open-im 自动恢复同目录下最新的 CLI session，无需配置。
+
+**电脑接手机：** 使用 `claude --continue`（或 `claude -c`）接上 open-im 端的对话。
+
+```bash
+# 电脑端
+cd /my-project && claude        # 正常工作，退出时 Ctrl+C
+
+# 手机端（IM 消息）
+"帮我修复登录 bug"              # open-im 自动接续同一个 session
+
+# 回到电脑端
+claude -c                       # 接上手机端的对话
+```
+
+> **注意：** 同一时刻只能有一端活跃。从手机发消息前先退出 CLI，反之亦然。
+
 ## 配置说明
 
 ### 按平台指定 AI

package/dist/adapters/claude-sdk-adapter.d.ts

@@ -9,6 +9,18 @@
  * 认证：ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN
  */
 import type { ToolAdapter, RunCallbacks, RunOptions, RunHandle } from './tool-adapter.interface.js';
+interface ClaudeSessionMeta {
+    sessionId: string;
+    mtime: number;
+    filePath: string;
+    size: number;
+}
+/**
+ * 扫描 ~/.claude/projects/<encoded-path>/ 找到最新的 CLI session。
+ * 只返回 JSONL 文件（排除子目录如 subagents/），按修改时间倒序。
+ * @param homeOverride 测试用：覆盖 homedir() 的返回值
+ */
+export declare function findLatestClaudeSession(workDir: string, homeOverride?: string): ClaudeSessionMeta | undefined;
 /**
  * 由 initAdapters 根据配置调用。ttlMinutes≤0 时关闭空闲回收（仍受 MAX_ACTIVE_SESSIONS 限制）。
  */
@@ -26,3 +38,4 @@ export declare class ClaudeSDKAdapter implements ToolAdapter {
     static removeSession(sessionId: string): void;
     run(prompt: string, sessionId: string | undefined, workDir: string, callbacks: RunCallbacks, options?: RunOptions): RunHandle;
 }
+export {};

package/dist/adapters/claude-sdk-adapter.js

@@ -9,7 +9,8 @@
  * 认证：ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN
  */
 import { unstable_v2_createSession, unstable_v2_resumeSession } from '@anthropic-ai/claude-agent-sdk';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, closeSync } from 'fs';
+import { execSync } from 'child_process';
 import { homedir } from 'os';
 import { join } from 'path';
 import { createLogger } from '../logger.js';
@@ -46,9 +47,141 @@ function loadUserPluginSettings() {
 }
 // Pre-load user plugin settings to cache Claude Code user preferences
 loadUserPluginSettings();
+// ── 扫描 Claude Code CLI 的最新 session，支持手机/电脑无缝切换 ──
+/**
+ * 将 workDir（如 /Users/mac/github/open-im）转换为 Claude Code 的项目路径编码
+ * ~/.claude/projects/-Users-mac-github-open-im/
+ */
+function workDirToProjectPath(workDir) {
+    // Claude Code 将路径中的 / 替换为 -，leading - 保留
+    // /Users/mac/github/open-im → -Users-mac-github-open-im
+    return workDir.replace(/\//g, '-');
+}
+/**
+ * 检查 CLI 进程是否**正在活跃使用**某个 session。
+ *
+ * 仅当同时满足以下两个条件时返回 true：
+ *   1. 存在包含该 sessionId 的 claude 进程（通过 ps 检测）
+ *   2. session 文件在最近 30 秒内被修改过（说明 CLI 正在处理消息）
+ *
+ * 如果 CLI 只是挂在终端等待用户输入，进程仍在但文件长时间未变，
+ * 此时安全允许 open-im 接管 session（无缝切换）。
+ *
+ * 注意：仅支持 macOS/Linux，Windows 上会静默返回 false
+ */
+function isCliSessionActive(sessionId, sessionFilePath) {
+    try {
+        // macOS/Linux: 用 ps 搜索包含该 sessionId 的 claude 进程
+        // 排除 open-im 自己的 SDK 子进程（路径含 claude-agent-sdk），只匹配用户交互式 CLI
+        // -F 固定字符串匹配，避免正则意外；-- 防止 sessionId 被误认为 flag
+        const result = execSync(`ps -axo pid,command 2>/dev/null | grep -v grep | grep "claude" | grep -v "claude-agent-sdk" | grep -F -- "${sessionId}" || true`, { encoding: 'utf-8', timeout: 3000 });
+        if (result.trim().length === 0)
+            return false;
+        // 进程存在，但可能只是 idle 在终端等输入。检查文件 mtime：
+        // 如果 session 文件超过 30 秒未修改，说明 CLI 没在活跃处理。
+        if (sessionFilePath) {
+            try {
+                const stat = statSync(sessionFilePath);
+                const ageMs = Date.now() - stat.mtimeMs;
+                if (ageMs > 30_000) {
+                    log.info(`CLI process found for ${sessionId} but session file idle for ${Math.round(ageMs / 1000)}s, treating as inactive`);
+                    return false;
+                }
+            }
+            catch {
+                // stat 失败时保守地认为活跃
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 扫描 ~/.claude/projects/<encoded-path>/ 找到最新的 CLI session。
+ * 只返回 JSONL 文件（排除子目录如 subagents/），按修改时间倒序。
+ * @param homeOverride 测试用：覆盖 homedir() 的返回值
+ */
+export function findLatestClaudeSession(workDir, homeOverride) {
+    const projectDir = join(homeOverride ?? homedir(), '.claude', 'projects', workDirToProjectPath(workDir));
+    if (!existsSync(projectDir)) {
+        log.info(`No Claude Code project dir found: ${projectDir}`);
+        return undefined;
+    }
+    try {
+        const entries = readdirSync(projectDir, { withFileTypes: true });
+        const sessions = [];
+        for (const entry of entries) {
+            // 只处理 .jsonl 文件，跳过子目录（如 subagents/）和 memory 目录
+            if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
+                continue;
+            const sessionId = entry.name.replace('.jsonl', '');
+            // 校验 UUID 格式
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(sessionId))
+                continue;
+            const filePath = join(projectDir, entry.name);
+            try {
+                const stat = statSync(filePath);
+                // 跳过空文件
+                if (stat.size === 0)
+                    continue;
+                sessions.push({ sessionId, mtime: stat.mtimeMs, filePath, size: stat.size });
+            }
+            catch {
+                continue;
+            }
+        }
+        if (sessions.length === 0) {
+            log.info(`No session files found in ${projectDir}`);
+            return undefined;
+        }
+        // 按修改时间倒序，最新的在前
+        sessions.sort((a, b) => b.mtime - a.mtime);
+        const latest = sessions[0];
+        log.info(`Found latest Claude Code session: ${latest.sessionId} (mtime: ${new Date(latest.mtime).toISOString()}, size: ${latest.size})`);
+        return latest;
+    }
+    catch (err) {
+        log.warn(`Failed to scan Claude Code project dir: ${err}`);
+        return undefined;
+    }
+}
+/**
+ * 从 JSONL 文件的第一行提取 sessionId，验证文件内容与文件名一致。
+ * 只读取前 4KB，避免大文件全量读入内存。
+ */
+function validateSessionFile(filePath, expectedSessionId) {
+    let fd;
+    try {
+        fd = openSync(filePath, 'r');
+        const buf = Buffer.alloc(4096);
+        const bytesRead = readSync(fd, buf, 0, 4096, 0);
+        if (bytesRead === 0)
+            return false;
+        const firstLine = buf.toString('utf-8', 0, bytesRead).split('\n')[0];
+        if (!firstLine)
+            return false;
+        const firstEntry = JSON.parse(firstLine);
+        return firstEntry.sessionId === expectedSessionId;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
 // 存储所有活跃的 SDKSession 对象，key 为 sessionId
 // 使用 Map 而不是 Set，因为我们需要通过 sessionId 获取 session
 const activeSessions = new Map();
+// 记录每个 session 创建/恢复时的 workDir，防止跨 workDir 复用已固定 cwd 的子进程
+const sessionWorkDirs = new Map();
 // 存储正在进行的流式迭代器，用于中断
 const activeStreams = new Set();
 // 空闲会话清理：跟踪最后使用时间，定期清除超时会话
@@ -92,34 +225,53 @@ const cleanupInterval = setInterval(() => {
                 activeSessions.delete(id);
             }
             sessionLastUsed.delete(id);
+            sessionWorkDirs.delete(id);
             log.info(`Cleaned up idle session (unused ${Math.round((now - lastUsed) / 60000)}min): ${id}`);
         }
     }
 }, CLEANUP_INTERVAL_MS);
 cleanupInterval.unref(); // 不阻止进程退出
 /**
- * Serializes process.chdir() calls across concurrent users.
+ * 串行化进程级 process.chdir() —— 同一时刻仅一个 chdir 生效。
  *
- * process.chdir() is a process-wide global side effect — only one chdir can
- * be active at a time. The SDK's createSession/resumeSession do not accept a
- * `cwd` parameter, so we must chdir before calling them. This mutex ensures
- * concurrent requests don't race on the working directory.
+ * SDK V2 的 createSession/resumeSession 不接受 cwd 参数；且 send()/stream()
+ * 会以「调用时的 process.cwd()」派生 Claude Code 子进程。必须用互斥锁串行化
+ * 「整个 turn 的 cwd 切换」，否则并发多用户会让工具跑错目录。
  *
- * **TODO:** Remove this mutex entirely once @anthropic-ai/claude-agent-sdk
- * supports a `cwd` option in createSession/resumeSession. Track upstream:
+ * **TODO:** SDK 支持 cwd 选项后移除此锁。upstream:
  * https://github.com/anthropics/claude-agent-sdk/issues
  */
 let chdirMutex = Promise.resolve();
 function withChdirMutex(fn) {
     const previous = chdirMutex;
-    let resolve;
-    chdirMutex = new Promise((r) => { resolve = r; });
-    return previous.then(() => {
+    let release;
+    chdirMutex = new Promise((r) => { release = r; });
+    return previous.then(async () => {
         try {
-            return fn();
+            return await fn();
         }
         finally {
-            resolve();
+            release();
+        }
+    });
+}
+/**
+ * 在持有全局 chdir 互斥锁期间，把进程 cwd 切到 workDir 执行 fn，结束后恢复。
+ * 用于包裹 session.send()+stream()，确保子进程在正确 workDir 派生。
+ */
+function runWithWorkDir(workDir, fn) {
+    return withChdirMutex(async () => {
+        const originalCwd = process.cwd();
+        if (workDir && workDir !== originalCwd) {
+            process.chdir(workDir);
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            if (workDir && workDir !== originalCwd) {
+                process.chdir(originalCwd);
+            }
         }
     });
 }
@@ -201,18 +353,21 @@ async function getOrCreateSession(sessionId, workDir, model, permissionMode, onS
                 process.chdir(workDir);
             }
             if (sessionId) {
-                // 优先复用内存中已有的 SDKSession，避免每次都启动新进程
+                // 优先复用内存中已有的 SDKSession，避免每次都启动新进程。
+                // 仅当 workDir 与创建时一致才复用：否则子进程 cwd 已固定在旧目录，
+                // 需走 resume 重新派生（在当前 workDir 启动新子进程）。
                 const existing = activeSessions.get(sessionId);
-                if (existing) {
+                if (existing && sessionWorkDirs.get(sessionId) === workDir) {
                     log.info(`Reusing existing in-memory session: ${sessionId}`);
                     sessionLastUsed.set(sessionId, Date.now());
                     return { session: existing, sessionId };
                 }
-                // 内存中没有，尝试通过 resume 恢复（会启动新 CLI 进程）
+                // 内存中没有（或 workDir 变了），尝试通过 resume 恢复（会启动新 CLI 进程）
                 try {
                     log.info(`Attempting to resume session: ${sessionId}`);
                     session = unstable_v2_resumeSession(sessionId, sessionOptions);
                     activeSessions.set(sessionId, session);
+                    sessionWorkDirs.set(sessionId, workDir);
                     sessionLastUsed.set(sessionId, Date.now());
                     log.info(`Successfully resumed session: ${sessionId}`);
                     return { session, sessionId };
@@ -222,12 +377,43 @@ async function getOrCreateSession(sessionId, workDir, model, permissionMode, onS
                     // 恢复失败，创建新会话
                 }
             }
+            // 没有指定 sessionId 时，尝试自动恢复 Claude Code CLI 的最新 session
+            // 实现手机/电脑无缝切换：同目录下默认共享同一个对话
+            if (!sessionId) {
+                const latest = findLatestClaudeSession(workDir);
+                if (latest) {
+                    // 检测 CLI 是否正在使用该 session（用于日志，不阻止 resume）
+                    const cliActive = isCliSessionActive(latest.sessionId, latest.filePath);
+                    if (cliActive) {
+                        log.info(`CLI is actively using session ${latest.sessionId}, attempting resume anyway (SDK handles concurrency)`);
+                    }
+                    // 验证文件内容一致性
+                    if (validateSessionFile(latest.filePath, latest.sessionId)) {
+                        try {
+                            log.info(`Auto-resuming latest CLI session: ${latest.sessionId}${cliActive ? ' (CLI active)' : ''}`);
+                            session = unstable_v2_resumeSession(latest.sessionId, sessionOptions);
+                            activeSessions.set(latest.sessionId, session);
+                            sessionWorkDirs.set(latest.sessionId, workDir);
+                            sessionLastUsed.set(latest.sessionId, Date.now());
+                            log.info(`Successfully auto-resumed CLI session: ${latest.sessionId}`);
+                            return { session, sessionId: latest.sessionId };
+                        }
+                        catch (err) {
+                            log.warn(`Failed to auto-resume CLI session ${latest.sessionId}, creating new one: ${err}`);
+                        }
+                    }
+                    else {
+                        log.warn(`Session file validation failed for ${latest.sessionId}, skipping`);
+                    }
+                }
+            }
             // 创建新会话
             session = unstable_v2_createSession(sessionOptions);
             // 新会话的 sessionId 需要从第一个消息中获取
             // 暂时返回 undefined，稍后在 init 消息中获取
             const tempId = `pending-${++sessionSeq}`;
             activeSessions.set(tempId, session);
+            sessionWorkDirs.set(tempId, workDir);
             sessionLastUsed.set(tempId, Date.now());
             log.info(`Created new session (tempId: ${tempId})`);
             return { session, sessionId: tempId, wasReused: false };
@@ -267,6 +453,7 @@ export class ClaudeSDKAdapter {
         }
         activeSessions.clear();
         sessionLastUsed.clear();
+        sessionWorkDirs.clear();
     }
     /**
      * Remove a specific session from the in-memory cache and close it.
@@ -281,6 +468,7 @@ export class ClaudeSDKAdapter {
             catch { /* ignore */ }
             activeSessions.delete(sessionId);
             sessionLastUsed.delete(sessionId);
+            sessionWorkDirs.delete(sessionId);
             log.info(`Explicitly removed session: ${sessionId}`);
         }
     }
@@ -320,12 +508,16 @@ export class ClaudeSDKAdapter {
                 }
                 runningSessions.add(returnedId);
                 trackedRunningId = returnedId;
-                // 发送用户消息
-                await session.send(prompt);
-                // 获取响应流
-                const stream = session.stream();
-                currentStream = stream;
-                activeStreams.add(stream);
+                // 在持有 chdir 锁期间完成 send() + stream() 获取：SDK V2 会以当前
+                // process.cwd() 派生 Claude Code 子进程，必须保证此刻 cwd 为 workDir。
+                // 锁串行化后，并发多用户的子进程不会在错误的目录派生。
+                const stream = await runWithWorkDir(workDir, async () => {
+                    await session.send(prompt);
+                    const s = session.stream();
+                    currentStream = s;
+                    activeStreams.add(s);
+                    return s;
+                });
                 let accumulated = '';
                 let accumulatedThinking = '';
                 const toolStats = {};
@@ -348,13 +540,19 @@ export class ClaudeSDKAdapter {
                                 // 更新 sessionId 映射
                                 // 清理 pending 临时 ID（actualSessionId 尚未赋值时用 pendingTempId）
                                 const idToClean = actualSessionId ?? pendingTempId;
+                                const inheritedWorkDir = idToClean ? sessionWorkDirs.get(idToClean) : undefined;
                                 if (idToClean?.startsWith('pending-')) {
                                     activeSessions.delete(idToClean);
                                 }
                                 activeSessions.set(newSessionId, session);
+                                if (inheritedWorkDir !== undefined) {
+                                    sessionWorkDirs.set(newSessionId, inheritedWorkDir);
+                                }
                                 sessionLastUsed.set(newSessionId, Date.now());
-                                if (idToClean)
+                                if (idToClean) {
                                     sessionLastUsed.delete(idToClean);
+                                    sessionWorkDirs.delete(idToClean);
+                                }
                                 // 更新 runningSessions：移除旧 ID，添加新 ID
                                 if (idToClean)
                                     runningSessions.delete(idToClean);

package/dist/adapters/registry.js

@@ -3,6 +3,7 @@ import { ClaudeSDKAdapter, configureClaudeSdkSessionIdle } from './claude-sdk-ad
 import { CodexAdapter } from './codex-adapter.js';
 import { CodeBuddyAdapter } from './codebuddy-adapter.js';
 import { createLogger } from '../logger.js';
+import { destroyAllLiveChildren } from '../shared/process-kill.js';
 const log = createLogger('Registry');
 const adapters = new Map();
 export function initAdapters(config) {
@@ -30,5 +31,7 @@ export function getAdapter(aiCommand) {
 }
 export function cleanupAdapters() {
     ClaudeSDKAdapter.destroy();
+    // 强制终止仍在运行的 CLI 子进程（Codex/CodeBuddy），避免僵尸 / 孤儿
+    destroyAllLiveChildren();
     adapters.clear();
 }

package/dist/cli.js

@@ -97,21 +97,28 @@ async function cmdStop() {
 }
 async function cmdRestart() {
     const status = getManagerStatus();
+    let restartedExistingInstance = false;
     if (status.pid) {
         await stopBackgroundService();
         const stopped = await stopManagerProcess();
         console.log("\nopen-im stopped.");
         console.log(`  pid: ${stopped.pid}`);
+        restartedExistingInstance = true;
     }
     else {
-        console.log("open-im is not running in the background. Starting a new instance.");
+        console.log("\nopen-im is not running in the background.");
     }
     if (!(await ensureConfigured("start"))) {
         process.exit(1);
     }
     await checkAndUpdate();
     const child = await startManagerProcess(process.cwd());
-    console.log("\nopen-im restarted in the background.");
+    if (restartedExistingInstance) {
+        console.log("\nopen-im restarted in the background.");
+    }
+    else {
+        console.log("\nopen-im started in the background.");
+    }
     console.log(`  pid: ${child.pid}`);
     logWebDashboardAndApi();
     process.exit(0);

package/dist/codebuddy/cli-runner.js

@@ -3,6 +3,7 @@ import { accessSync, constants } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { createLogger } from '../logger.js';
 import { processEnvForNonClaudeCliChild } from '../config/file-io.js';
+import { killProcessTree, trackChild } from '../shared/process-kill.js';
 const log = createLogger('CodeBuddyCli');
 export function buildCodeBuddyArgs(prompt, sessionId, options) {
     const args = ['--print', '--output-format', 'stream-json'];
@@ -200,10 +201,14 @@ export function runCodeBuddy(cliPath, prompt, sessionId, workDir, callbacks, opt
     log.info(`Spawning CodeBuddy CLI: path=${normalizedCliPath}, cwd=${workDir}, session=${sessionId ?? 'new'}, args=${args.join(' ')}`);
     const child = spawn(spawnCmd, spawnArgs, {
         cwd: workDir,
+        // Unix 上放入独立进程组，使 abort/关停能用 process.kill(-pid) 杀掉整棵子树（含 MCP/shell 孙进程）
+        detached: process.platform !== 'win32',
         stdio: ['ignore', 'pipe', 'pipe'],
         env,
         windowsHide: process.platform === 'win32',
     });
+    trackChild(child);
+    let cliTimeoutHandle = null;
     let accumulated = '';
     let accumulatedThinking = '';
     let completed = false;
@@ -311,6 +316,10 @@ export function runCodeBuddy(cliPath, prompt, sessionId, workDir, callbacks, opt
         }
     });
     child.on('close', (code) => {
+        if (cliTimeoutHandle) {
+            clearTimeout(cliTimeoutHandle);
+            cliTimeoutHandle = null;
+        }
         if (completed)
             return;
         if (stdoutState.buffer.trim()) {
@@ -343,16 +352,36 @@ export function runCodeBuddy(cliPath, prompt, sessionId, workDir, callbacks, opt
         });
     });
     child.on('error', (err) => {
+        if (cliTimeoutHandle) {
+            clearTimeout(cliTimeoutHandle);
+            cliTimeoutHandle = null;
+        }
         if (completed)
             return;
         completed = true;
         callbacks.onError(`Failed to start CodeBuddy CLI: ${err.message}`);
     });
+    // 墙钟超时：防止 CLI 挂死永久占用用户队列槽
+    const cliTimeoutMs = Number(process.env.OPEN_IM_CLI_TIMEOUT_MS) || 30 * 60 * 1000;
+    cliTimeoutHandle = setTimeout(() => {
+        if (completed)
+            return;
+        log.warn(`CodeBuddy CLI 超过 ${cliTimeoutMs}ms，强制终止 (pid=${child.pid})`);
+        completed = true;
+        killProcessTree(child);
+        callbacks.onError(`CodeBuddy CLI 运行超时（${Math.round(cliTimeoutMs / 1000)}s），已终止。请重试。`);
+    }, cliTimeoutMs);
+    cliTimeoutHandle.unref();
     return {
         abort: () => {
+            if (completed)
+                return;
             completed = true;
-            if (!child.killed)
-                child.kill('SIGTERM');
+            if (cliTimeoutHandle) {
+                clearTimeout(cliTimeoutHandle);
+                cliTimeoutHandle = null;
+            }
+            killProcessTree(child);
         },
     };
 }

package/dist/codex/cli-runner.js

@@ -7,6 +7,7 @@ import { dirname, join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { createLogger } from '../logger.js';
 import { processEnvForNonClaudeCliChild } from '../config/file-io.js';
+import { killProcessTree, trackChild } from '../shared/process-kill.js';
 const log = createLogger('CodexCli');
 const windowsCodexLaunchCache = new Map();
 const SUPPORTED_IMAGE_EXTENSIONS = new Set([
@@ -201,10 +202,13 @@ export function runCodex(cliPath, prompt, sessionId, workDir, callbacks, options
             : args;
     const child = spawn(spawnCmd, spawnArgs, {
         cwd: workDir,
+        // Unix 上放入独立进程组，使 abort/关停能用 process.kill(-pid) 杀掉整棵子树（含 MCP/shell 孙进程）
+        detached: process.platform !== 'win32',
         stdio: ['pipe', 'pipe', 'pipe'],
         env,
         windowsHide: process.platform === 'win32',
     });
+    trackChild(child);
     child.stdin?.write(prompt);
     child.stdin?.end();
     let accumulated = '';
@@ -327,7 +331,12 @@ export function runCodex(cliPath, prompt, sessionId, workDir, callbacks, options
     let exitCode = null;
     let rlClosed = false;
     let childClosed = false;
+    let cliTimeoutHandle = null;
     const finalize = () => {
+        if (cliTimeoutHandle) {
+            clearTimeout(cliTimeoutHandle);
+            cliTimeoutHandle = null;
+        }
         if (!rlClosed || !childClosed)
             return;
         if (completed)
@@ -387,12 +396,29 @@ export function runCodex(cliPath, prompt, sessionId, workDir, callbacks, options
         childClosed = true;
         finalize();
     });
+    // 墙钟超时：防止 CLI 挂死（网络卡住、工具死循环等）永久占用用户队列槽
+    const cliTimeoutMs = Number(process.env.OPEN_IM_CLI_TIMEOUT_MS) || 30 * 60 * 1000;
+    cliTimeoutHandle = setTimeout(() => {
+        if (completed)
+            return;
+        log.warn(`Codex CLI 超过 ${cliTimeoutMs}ms，强制终止 (pid=${child.pid})`);
+        completed = true;
+        rl.close();
+        killProcessTree(child);
+        callbacks.onError(`Codex CLI 运行超时（${Math.round(cliTimeoutMs / 1000)}s），已终止。请重试。`);
+    }, cliTimeoutMs);
+    cliTimeoutHandle.unref();
     return {
         abort: () => {
+            if (completed)
+                return;
             completed = true;
+            if (cliTimeoutHandle) {
+                clearTimeout(cliTimeoutHandle);
+                cliTimeoutHandle = null;
+            }
             rl.close();
-            if (!child.killed)
-                child.kill('SIGTERM');
+            killProcessTree(child);
         },
     };
 }

package/dist/config/file-io.d.ts

@@ -19,8 +19,11 @@ export declare function getClaudeSdkRuntimeIssue(): string | null;
 export declare function parseCommaSeparated(value: string): string[];
 /**
  * 将最新的 Claude 认证环境变量按优先级合并到 process.env。
- * 优先级：shell 环境变量 > ~/.open-im/config.json 的 tools.claude.env >
- * 本机 Claude 配置（~/.claude/settings.json，与 Claude Code 共用）。
- * 多数用户只维护本机 settings；每次创建 Claude SDK 会话前调用，本机文件变更后下次会话即生效。
+ * 优先级：shell 环境变量 > 本机 Claude 配置（~/.claude/settings.json，与 Claude Code 共用）>
+ * ~/.open-im/config.json 的 tools.claude.env。
+ *
+ * 设计意图：用户只需维护 ~/.claude/settings.json（与 Claude Code CLI 共用），
+ * open-im 自动跟随本地 Claude 配置，无需单独配置。config.json 的 tools.claude.env
+ * 仅作为兜底，供没有本地 Claude 安装的场景使用。
  */
 export declare function refreshClaudeEnvToProcess(): void;