NanoClaw 架构分析

1. 全局流程概览

从用户发送一条消息到收到回复，经过以下链路：

2. 消息接入与存储

源码位置：src/index.ts 509-538 行

流程

1. Channel 调用 onMessage 回调，传入 NewMessage
2. Sender 白名单过滤：检查发送者是否在允许列表中。Drop 模式下直接丢弃未授权消息（不入库）
3. storeMessage() 写入 SQLite messages 表
4. storeChatMetadata() 更新聊天元数据（群名、渠道、时间戳，不存消息内容）

数据库 Schema

messages (
  id, chat_jid, sender, sender_name, content,
  timestamp, is_from_me, is_bot_message, attachments
)

chats (
  jid, name, last_message_time, channel, is_group
)

3. 消息轮询主循环

源码位置：src/index.ts 362-461 行

轮询间隔：POLL_INTERVAL = 2000ms

双游标设计

这是整个系统最精妙的设计之一——用两个独立的时间戳游标来保证消息不丢不重：

主循环伪代码

while (true) {
  // 1. 拉取新消息（timestamp > lastTimestamp）
  const { messages, newTimestamp } = getNewMessages(jids, lastTimestamp);

  if (messages.length > 0) {
    // 2. 立即推进"已看到"游标（不等处理）
    lastTimestamp = newTimestamp;
    saveState();

    // 3. 按群分组
    const messagesByGroup = groupBy(messages, 'chatJid');

    for (const [chatJid, groupMessages] of messagesByGroup) {
      // 4. 检查触发词（非主群需要 @机器人名）
      if (needsTrigger && !hasTrigger) continue;

      // 5. 取出该群所有待处理消息（从 lastAgentTimestamp 开始）
      const allPending = getMessagesSince(chatJid, lastAgentTimestamp[chatJid]);

      // 6. 尝试管道到活跃容器
      if (queue.sendMessage(chatJid, formatted)) {
        // ✅ 成功：消息通过 stdin 管道送入正在运行的容器
        lastAgentTimestamp[chatJid] = lastTimestamp;
      } else {
        // ❌ 无活跃容器：排队等待启动
        queue.enqueueMessageCheck(chatJid);
      }
    }
  }

  await sleep(2000);
}

4. GroupQueue — 并发与排队

源码位置：src/group-queue.ts

GroupQueue 是整个系统的调度核心，负责：同一群内消息串行化、跨群容器并发控制。

每个群的状态机

interface GroupState {
  active: boolean;           // 容器是否在运行
  idleWaiting: boolean;      // 是否在等待后续输入（空闲）
  isTaskContainer: boolean;  // 正在跑定时任务还是消息
  runningTaskId: string;     // 当前任务 ID
  pendingMessages: boolean;  // 有消息在等
  pendingTasks: QueuedTask[];// 排队中的定时任务
  process: ChildProcess;     // 进程句柄
  containerName: string;     // Docker 容器名
  retryCount: number;        // 失败重试计数
}

核心调度逻辑

enqueueMessageCheck(groupJid)

if (state.active) {
  state.pendingMessages = true;   // 已有容器跑着，标记等待
  return;
}
if (activeCount >= MAX_CONCURRENT_CONTAINERS) {
  state.pendingMessages = true;
  this.waitingGroups.push(groupJid); // 无空闲槽，排队
  return;
}
this.runForGroup(groupJid, 'messages'); // 有槽位，立即启动

sendMessage(groupJid, text) — 管道消息到活跃容器

// 写入 IPC 文件（原子写入：临时文件 + rename）
// 路径：/data/ipc/{groupFolder}/input/{timestamp}-{random}.json
// 仅在容器 active 且非 task 模式时有效

drainGroup() — 容器退出后的排水逻辑

容器结束后:
  1. 优先处理排队的定时任务（tasks > messages）
  2. 再处理排队的消息
  3. 如果该群没有待处理项：
     → 调用 drainWaiting() 从全局等待队列拉下一个群

5. 多消息并发场景详解

6. Session 生命周期

源码位置：src/index.ts 281-360 行, src/container-runner.ts 117-192 行

Session 复用

// 从 DB 加载 session ID
const sessionId = sessions[group.folder];

// 首次运行：sessionId 为空 → 容器创建新 session
// 后续运行：复用同一个 sessionId → 继承对话历史

// 容器返回新 sessionId → 持久化到 DB
if (output.newSessionId) {
  sessions[group.folder] = output.newSessionId;
  setSession(group.folder, output.newSessionId);
}

每群独立隔离

• 每个群有独立的 .claude/ 目录（挂载为容器内的 /home/node/.claude）
• Session 按 group.folder 隔离存储
• Session 在容器重启间持久化（存在 SQLite 中）

容器空闲超时

容器处理完消息后不会立即退出，而是进入空闲等待状态，等待后续消息管道进来：

• 默认空闲超时：30 分钟（IDLE_TIMEOUT = 1800000ms）
• 30 分钟内有新消息 → 直接管道送入，无需重启
• 30 分钟无消息 → 容器关闭，下次消息重新启动

7. Context Window 与溢出

容器输出限制

CONTAINER_MAX_OUTPUT_SIZE = 10MB

// 超出时（container-runner.ts 381-393）：
if (chunk.length > remaining) {
  stdout += chunk.slice(0, remaining);
  stdoutTruncated = true;
  logger.warn('Container stdout truncated due to size limit');
}
// 容器继续运行，但输出被截断

消息历史限制

• DB 查询最多返回 200 条消息（limit = 200）
• 更早的消息留在 DB 但不会发送给容器
• 无自动清理机制

Claude 自身的 Context Window

NanoClaw 不直接管理 Claude 的 context window。当对话超长时：

• Claude 自身会进行 context compaction（压缩旧对话）
• 压缩可能丢失还未回复的中间状态
• 这是Claude SDK 层面的行为，NanoClaw 无法干预

8. 定时任务与消息队列的交互

源码位置：src/task-scheduler.ts

轮询间隔：SCHEDULER_POLL_INTERVAL = 60000ms（每分钟检查一次）

调度流程

const loop = async () => {
  const dueTasks = getDueTasks(); // WHERE next_run <= NOW AND status = 'active'

  for (const task of dueTasks) {
    // 通过 GroupQueue 排队（和消息共用同一套队列）
    deps.queue.enqueueTask(task.chat_jid, task.id, () => runTask(task, deps));
  }

  setTimeout(loop, 60000);
};

任务 vs 消息的优先级

9. IPC 进程间通信

源码位置：src/ipc.ts

轮询间隔：IPC_POLL_INTERVAL = 1000ms

容器内的 Agent 通过 IPC 文件与宿主通信。Agent 写文件到 /workspace/ipc/（容器内路径），宿主每秒扫描处理。

支持的 IPC 消息类型

原子写入：所有 IPC 文件使用 临时文件 + rename 模式，防止读取到写了一半的文件。

10. 崩溃恢复机制

源码位置：src/index.ts 467-479 行

function recoverPendingMessages(): void {
  for (const [chatJid, group] of Object.entries(registeredGroups)) {
    const sinceTimestamp = lastAgentTimestamp[chatJid] || '';
    const pending = getMessagesSince(chatJid, sinceTimestamp, ASSISTANT_NAME);
    if (pending.length > 0) {
      logger.info({ group: group.name, pendingCount: pending.length },
        'Recovery: found unprocessed messages');
      queue.enqueueMessageCheck(chatJid);
    }
  }
}

启动时调用。利用双游标的间隙（lastTimestamp 已推进但 lastAgentTimestamp 未推进的消息）来恢复未处理的消息。

Agent 失败的回滚策略

11. 容器隔离与安全

源码位置：src/container-runner.ts 60-241 行

主群 vs 非主群的挂载差异

12. 核心参数汇总

13. 关键设计洞察

14. 回答：为什么会出现"被打断"

回到最初的问题——在处理"私聊用户定时任务"的问题时，头像请求"打断"了回复。