NanoClaw 原始碼解讀：用極簡架構打造安全的個人 AI 助理

WhatsApp (baileys) ──▶ SQLite ──▶ Polling Loop ──▶ Container (Claude Agent SDK) ──▶ Response
                                                        │
                                                        ▼
                                                  IPC via Filesystem
                                                        │
                                                        ▼
                                              Host 處理 messages/tasks

nanoclaw/
├── src/                        # Host process（全部核心邏輯）
│   ├── index.ts                # 入口：WhatsApp 連線、訊息路由、IPC watcher
│   ├── container-runner.ts     # 容器生命週期：mount 組裝、spawn、輸出解析
│   ├── db.ts                   # SQLite schema 與所有查詢
│   ├── task-scheduler.ts       # 排程任務引擎
│   ├── mount-security.ts       # 掛載安全驗證（allowlist 機制）
│   ├── config.ts               # 常數與環境變數
│   ├── types.ts                # TypeScript 型別定義
│   └── utils.ts                # JSON 讀寫工具
├── container/                  # 容器映像
│   ├── Dockerfile              # Agent 執行環境
│   └── agent-runner/src/       # 容器內程式碼
│       ├── index.ts            # Agent 啟動器（Claude Agent SDK query）
│       └── ipc-mcp.ts          # MCP Server：agent 的對外通訊介面
├── groups/                     # 每個群組的隔離記憶空間
│   ├── main/CLAUDE.md          # 主頻道 prompt（有管理員權限）
│   └── global/CLAUDE.md        # 全域共享 prompt
└── .claude/skills/             # Claude Code Skills（擴展機制）
    ├── setup/SKILL.md
    ├── customize/SKILL.md
    ├── debug/SKILL.md
    └── add-gmail/SKILL.md
Code language: PHP (php)

async function startMessageLoop(): Promise<void> {
  if (messageLoopRunning) {
    logger.debug('Message loop already running, skipping duplicate start');
    return;
  }
  messageLoopRunning = true;

  while (true) {
    try {
      const jids = Object.keys(registeredGroups);
      const { messages } = getNewMessages(jids, lastTimestamp, ASSISTANT_NAME);

      for (const msg of messages) {
        try {
          await processMessage(msg);
          // Only advance timestamp after successful processing for at-least-once delivery
          lastTimestamp = msg.timestamp;
          saveState();
        } catch (err) {
          logger.error({ err, msg: msg.id }, 'Error processing message, will retry');
          break;  // Stop processing this batch - failed message will be retried next loop
        }
      }
    } catch (err) {
      logger.error({ err }, 'Error in message loop');
    }
    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
  }
}
Code language: JavaScript (javascript)

function buildVolumeMounts(
  group: RegisteredGroup,
  isMain: boolean,
): VolumeMount[] {
  const mounts: VolumeMount[] = [];

  if (isMain) {
    // Main gets the entire project root mounted
    mounts.push({
      hostPath: projectRoot,
      containerPath: '/workspace/project',
      readonly: false,
    });
    mounts.push({
      hostPath: path.join(GROUPS_DIR, group.folder),
      containerPath: '/workspace/group',
      readonly: false,
    });
  } else {
    // Other groups only get their own folder
    mounts.push({
      hostPath: path.join(GROUPS_DIR, group.folder),
      containerPath: '/workspace/group',
      readonly: false,
    });
    // Global memory directory (read-only for non-main)
    const globalDir = path.join(GROUPS_DIR, 'global');
    if (fs.existsSync(globalDir)) {
      mounts.push({
        hostPath: globalDir,
        containerPath: '/workspace/global',
        readonly: true,
      });
    }
  }

  // Per-group IPC namespace: each group gets its own IPC directory
  const groupIpcDir = path.join(DATA_DIR, 'ipc', group.folder);
  mounts.push({
    hostPath: groupIpcDir,
    containerPath: '/workspace/ipc',
    readonly: false,
  });
  // ...
}

function writeIpcFile(dir: string, data: object): string {
  fs.mkdirSync(dir, { recursive: true });
  const filename = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`;
  const filepath = path.join(dir, filename);

  // Atomic write: temp file then rename
  const tempPath = `${filepath}.tmp`;
  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2));
  fs.renameSync(tempPath, filepath);
  return filename;
}
Code language: JavaScript (javascript)

// Authorization: verify this group can send to this chatJid
const targetGroup = registeredGroups[data.chatJid];
if (isMain || (targetGroup && targetGroup.folder === sourceGroup)) {
  await sendMessage(data.chatJid, `${ASSISTANT_NAME}: ${data.text}`);
} else {
  logger.warn(
    { chatJid: data.chatJid, sourceGroup },
    'Unauthorized IPC message attempt blocked',
  );
}
Code language: JavaScript (javascript)

const OUTPUT_START_MARKER = '---NANOCLAW_OUTPUT_START---';
const OUTPUT_END_MARKER = '---NANOCLAW_OUTPUT_END---';

// Extract JSON between sentinel markers for robust parsing
const startIdx = stdout.indexOf(OUTPUT_START_MARKER);
const endIdx = stdout.indexOf(OUTPUT_END_MARKER);

let jsonLine: string;
if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
  jsonLine = stdout.slice(startIdx + OUTPUT_START_MARKER.length, endIdx).trim();
} else {
  // Fallback: last non-empty line (backwards compatibility)
  const lines = stdout.trim().split('\n');
  jsonLine = lines[lines.length - 1];
}

const output: ContainerOutput = JSON.parse(jsonLine);
Code language: JavaScript (javascript)

const DEFAULT_BLOCKED_PATTERNS = [
  '.ssh', '.gnupg', '.gpg', '.aws', '.azure', '.gcloud',
  '.kube', '.docker', 'credentials', '.env', '.netrc',
  '.npmrc', '.pypirc', 'id_rsa', 'id_ed25519',
  'private_key', '.secret',
];
Code language: JavaScript (javascript)

function findAllowedRoot(realPath: string, allowedRoots: AllowedRoot[]): AllowedRoot | null {
  for (const root of allowedRoots) {
    const expandedRoot = expandPath(root.path);
    const realRoot = getRealPath(expandedRoot);
    if (realRoot === null) continue;

    // Check if realPath is under realRoot
    const relative = path.relative(realRoot, realPath);
    if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
      return root;
    }
  }
  return null;
}
Code language: JavaScript (javascript)

export function createIpcMcp(ctx: IpcMcpContext) {
  return createSdkMcpServer({
    name: 'nanoclaw',
    version: '1.0.0',
    tools: [
      tool('send_message', 'Send a message to the current WhatsApp group...', {
        text: z.string().describe('The message text to send')
      }, async (args) => {
        const data = { type: 'message', chatJid, text: args.text, ... };
        const filename = writeIpcFile(MESSAGES_DIR, data);
        return { content: [{ type: 'text', text: `Message queued for delivery (${filename})` }] };
      }),

      tool('schedule_task',
        `Schedule a recurring or one-time task...
         CONTEXT MODE - Choose based on task type:
         • "group": Task runs in the group's conversation context...
         • "isolated": Task runs in a fresh session...`,
        { prompt: z.string(), schedule_type: z.enum(['cron', 'interval', 'once']), ... },
        async (args) => { /* validation + IPC write */ }
      ),
      // list_tasks, pause_task, resume_task, cancel_task, register_group...
    ]
  });
}
Code language: JavaScript (javascript)

for await (const message of query({
  prompt,
  options: {
    cwd: '/workspace/group',
    resume: input.sessionId,
    allowedTools: [
      'Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep',
      'WebSearch', 'WebFetch',
      'mcp__nanoclaw__*'
    ],
    permissionMode: 'bypassPermissions',
    allowDangerouslySkipPermissions: true,
    settingSources: ['project'],
    mcpServers: { nanoclaw: ipcMcp },
    hooks: { PreCompact: [{ hooks: [createPreCompactHook()] }] }
  }
})) { ... }
Code language: JavaScript (javascript)

function createPreCompactHook(): HookCallback {
  return async (input, _toolUseId, _context) => {
    const preCompact = input as PreCompactHookInput;
    const transcriptPath = preCompact.transcript_path;

    if (!transcriptPath || !fs.existsSync(transcriptPath)) return {};

    const content = fs.readFileSync(transcriptPath, 'utf-8');
    const messages = parseTranscript(content);

    const summary = getSessionSummary(sessionId, transcriptPath);
    const name = summary ? sanitizeFilename(summary) : generateFallbackName();

    const conversationsDir = '/workspace/group/conversations';
    fs.mkdirSync(conversationsDir, { recursive: true });

    const date = new Date().toISOString().split('T')[0];
    const filename = `${date}-${name}.md`;
    fs.writeFileSync(filePath, markdown);
    return {};
  };
}
Code language: JavaScript (javascript)

# Andy

You are Andy, a personal assistant...

## Long Tasks
If a request requires significant work, use `mcp__nanoclaw__send_message` to acknowledge first:
1. Send a brief message: what you understood and what you'll do
2. Do the work
3. Exit with the final answer

## Memory
The `conversations/` folder contains searchable history of past conversations.
When you learn something important:
- Create files for structured data (e.g., `customers.md`, `preferences.md`)
- Add recurring context directly to this CLAUDE.md
Code language: PHP (php)

---
name: customize
description: Add new capabilities or modify NanoClaw behavior...
---

# NanoClaw Customization

## Key Files
| File | Purpose |
|------|---------|
| `src/config.ts` | Assistant name, trigger pattern, directories |
| `src/index.ts` | Message routing, WhatsApp connection, agent invocation |

## Common Customization Patterns

### Adding a New Input Channel (e.g., Telegram, Slack, Email)

Questions to ask:
- Which channel?
- Same trigger word or different?
- Same memory hierarchy or separate?

Implementation pattern:
1. Find/add MCP server for the channel
2. Add connection and message handling in `src/index.ts`
3. Store messages in the database
4. Ensure responses route back to correct channel
Code language: PHP (php)

const envContent = fs.readFileSync(envFile, 'utf-8');
const allowedVars = ['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY'];
const filteredLines = envContent.split('\n').filter((line) => {
  const trimmed = line.trim();
  if (!trimmed || trimmed.startsWith('#')) return false;
  return allowedVars.some((v) => trimmed.startsWith(`${v}=`));
});

if (filteredLines.length > 0) {
  fs.writeFileSync(path.join(envDir, 'env'), filteredLines.join('\n') + '\n');
  mounts.push({
    hostPath: envDir,
    containerPath: '/workspace/env-dir',
    readonly: true,
  });
}
Code language: JavaScript (javascript)

# Sources env from mounted /workspace/env-dir/env if it exists
# (workaround for Apple Container -i bug)
[ -f /workspace/env-dir/env ] && export $(cat /workspace/env-dir/env | xargs)
Code language: PHP (php)

tool('schedule_task',
  `...CONTEXT MODE - Choose based on task type:
   • "group" (recommended for most tasks): Task runs in the group's conversation context...
   • "isolated": Task runs in a fresh session...

   If unsure which mode to use, ask the user. Examples:
   - "Remind me about our discussion" → group (needs conversation context)
   - "Check the weather every morning" → isolated (self-contained task)`,
  ...
)
Code language: JavaScript (javascript)