Clawdbot iMessage 集成：从零配置到自动回复

概述

Clawdbot 是一款基于命令行的 AI 聊天机器人网关，支持多种消息渠道包括 iMessage、WhatsApp、Telegram、Discord 等。本文记录了在 macOS 上配置 Clawdbot 与 iMessage 集成的完整过程，包括遇到的问题及解决方案。

测试环境：

• macOS 15.7.3 (Darwin 24.6.0)
• Clawdbot 2026.1.24-3
• Node.js 22.22.0
• AI 模型：OpenAI GPT-4o-mini

---

一、安装与初始化

1.1 基础配置

首次运行需要初始化配置：

clawdbot setup
clawdbot config set gateway.mode local
clawdbot gateway install
clawdbot gateway start

遇到的问题： Gateway 启动后提示 token 认证缺失。

解决方案： 通过 clawdbot doctor 诊断并修复配置问题。

1.2 安装 imsg CLI 工具

iMessage 集成依赖第三方工具 imsg：

brew install steipete/tap/imsg

安装完成后需要授予权限：

• Full Disk Access：允许读取 Messages 数据库
• Automation：允许控制 Messages.app 发送消息

---

二、iMessage 通道配置

2.1 添加 iMessage 通道

在 ~/.clawdbot/clawdbot.json 中配置：

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/usr/local/bin/imsg",
      "dbPath": "/Users/<username>/Library/Messages/chat.db",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist"
    }
  }
}

2.2 权限配置（关键步骤）

问题： Gateway 运行时报错 permissionDenied，但终端直接运行 imsg 正常。

原因分析： Terminal 应用已获得 Full Disk Access，但 Gateway 作为 LaunchAgent 运行的 node 进程没有该权限。

解决方案：

1. 打开「系统设置」→「隐私与安全性」→「完全磁盘访问权限」
2. 添加 Node.js 二进制文件（如 /usr/local/opt/node@22/bin/node）
3. 重启 Gateway：clawdbot gateway restart

验证权限：

imsg chats --limit 3
# 正常输出聊天列表即表示权限配置成功

---

三、AI 模型配置

3.1 配置 OpenAI API

# 添加 API Key
clawdbot models auth paste-token --provider openai

# 设置默认模型
clawdbot models set openai/gpt-4o-mini

# 重启 Gateway 使配置生效
clawdbot gateway restart

# 验证配置
clawdbot models status

3.2 模型选择建议

模型	响应速度	适用场景
gpt-4o-mini	~3-5秒	日常聊天（推荐）
gpt-4o	~10-30秒	复杂任务
gpt-4.1	超时风险	不推荐

问题： 使用 gpt-4.1 时频繁超时。

解决方案： 切换到 gpt-4o-mini，响应速度显著提升。

---

四、Pairing 机制

Clawdbot 采用 Pairing（配对）机制保护隐私，防止陌生人滥用机器人。

4.1 工作流程

1. 陌生人发送消息 → Clawdbot 返回配对码
2. 机器人所有者审批：

   clawdbot pairing approve imessage <CODE>
   

3. 审批通过后，该发送者可与机器人正常对话

4.2 管理已授权用户

授权列表存储在：

~/.clawdbot/credentials/imessage-allowFrom.json

文件格式：

{
  "version": 1,
  "allowFrom": ["+8612345678901"]
}

4.3 相关命令

# 查看待审批的配对请求
clawdbot pairing list --channel imessage

# 审批配对
clawdbot pairing approve imessage <CODE>

---

五、Agent 工作区配置

5.1 默认配置问题

Clawdbot 默认工作区（~/clawd/）包含多个 Markdown 文件作为系统提示词：

~/clawd/
├── AGENTS.md      # Agent 行为规范
├── SOUL.md        # 人格设定
├── IDENTITY.md    # 身份信息
├── USER.md        # 用户信息
├── TOOLS.md       # 工具说明
├── BOOTSTRAP.md   # 首次运行指南
└── HEARTBEAT.md   # 心跳配置

问题： 这些文件指示 Agent 先读取文件再响应，导致：

• Agent 优先使用工具调用而非直接回复
• API 返回 payloads: []，无文本响应
• 日志显示 No reply from agent.

5.2 简化配置

为实现简单的聊天回复功能，需要简化工作区配置。

简化后的 AGENTS.md：

# AGENTS.md - Chat Assistant

You are a helpful chat assistant. When someone messages you, respond directly and helpfully.

## Key Rules
1. **Always respond with text** - Don't use tools unless the user specifically asks
2. **Be concise** - Keep responses short and friendly for chat
3. **Be helpful** - Answer questions, have conversations, help with tasks

## For Simple Messages
- "Hello" → Reply with a friendly greeting
- Questions → Answer them directly
- Tasks → Help with them

## Only Use Tools When
- User asks to read/write files
- User asks to search the web
- User asks to do something specific that requires a tool

**Default behavior: Just chat!**

简化后的 SOUL.md：

# SOUL.md - Who You Are

You are a friendly AI assistant. Be helpful, concise, and conversational.

- Respond naturally to messages
- Keep answers short for chat
- Be friendly and helpful
- Don't overthink simple questions

简化后测试：

clawdbot agent --message "Hello!" --channel imessage --to +1234567890 --deliver
# 输出: Hello! How can I assist you today?

---

六、常见问题与解决方案

6.1 “Request timed out” 错误

可能原因：

1. OpenAI API 网络问题（特别是中国大陆用户）
2. 模型响应过慢
3. 系统提示词过长（默认配置约 23k 字符）

解决方案：

• 切换到更快的模型：clawdbot models set openai/gpt-4o-mini
• 简化工作区提示词文件
• 增加 CLI 超时参数：--timeout 120

6.2 自我消息无限循环

问题： 给自己发送 iMessage 时产生无限循环，机器人不断回复自己。

原因： iMessage 将发送给自己的消息同时标记为「已发送」和「已接收」，Clawdbot 将「已接收」的消息视为新消息并响应，触发下一轮循环。

解决方案：

1. 使用其他设备或号码进行测试
2. 从 allowFrom 列表中移除自己的号码：

   # 编辑 ~/.clawdbot/credentials/imessage-allowFrom.json
   # 将 allowFrom 数组清空或移除自己的号码
   

6.3 Agent 无响应 (payloads: [])

问题： Agent 完成运行但不返回文本响应。

诊断方法：

clawdbot agent --message "test" --channel imessage --to +1234567890 --json
# 检查返回结果中的 payloads 和 usage.output

可能原因：

• Agent 正在使用工具调用而非文本回复
• 系统提示词指示 Agent 先执行其他操作

解决方案：

• 简化 AGENTS.md，明确指示「直接回复文本」
• 删除或简化其他提示词文件

6.4 Permission Denied 错误

问题： imsg 在终端正常运行，但 Gateway 报权限错误。

解决方案：

1. 确认 Node.js 二进制文件已添加到 Full Disk Access
2. 找到 Node.js 路径：which node
3. 在系统设置中添加该路径
4. 重启 Gateway

---

七、测试命令速查

健康检查

clawdbot health
clawdbot channels status
clawdbot models status

发送消息

# 直接发送消息（不经过 AI）
clawdbot message send --channel imessage --target +1234567890 --message "Hello"

# 通过 Agent 发送（AI 生成回复）
clawdbot agent --message "Hello" --channel imessage --to +1234567890 --deliver

# 测试 Agent（不发送，仅查看回复）
clawdbot agent --message "Hello" --channel imessage --to +1234567890 --json

日志与调试

# 实时查看日志
clawdbot logs --follow

# 查看 Gateway 日志文件
tail -f ~/.clawdbot/logs/gateway.log

# 查看详细日志
tail -f /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log

配对管理

# 查看待审批请求
clawdbot pairing list --channel imessage

# 审批配对
clawdbot pairing approve imessage <CODE>

Gateway 管理

clawdbot gateway start
clawdbot gateway stop
clawdbot gateway restart

---

八、配置文件参考

主配置文件 (~/.clawdbot/clawdbot.json)

{
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "<your-token>"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-4o-mini"
      },
      "workspace": "/Users/<username>/clawd",
      "maxConcurrent": 4
    }
  },
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/usr/local/bin/imsg",
      "dbPath": "/Users/<username>/Library/Messages/chat.db",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist"
    }
  }
}

API 密钥存储 (~/.clawdbot/agents/main/agent/auth-profiles.json)

{
  "version": 1,
  "profiles": {
    "openai:manual": {
      "type": "token",
      "provider": "openai",
      "token": "sk-proj-..."
    }
  },
  "lastGood": {
    "openai": "openai:manual"
  }
}

---

九、评测总结

优点

项目	评分	说明
多渠道支持	⭐⭐⭐⭐⭐	支持 iMessage、WhatsApp、Telegram、Discord 等 16+ 消息平台
隐私保护	⭐⭐⭐⭐⭐	Pairing 机制防止滥用、完全本地运行
可扩展性	⭐⭐⭐⭐	支持自定义 Skills、Plugins、多 Agent
CLI 工具	⭐⭐⭐⭐	功能完善，命令设计合理
模型灵活性	⭐⭐⭐⭐	支持 OpenAI、Anthropic 等多种 AI 提供商
文档质量	⭐⭐⭐⭐	官方文档较为完善

待改进

项目	说明
权限配置	Node.js 需单独授权 Full Disk Access，新手易困惑
默认模板	工作区模板过于复杂，简单聊天场景需要精简
错误提示	部分错误信息不够直观（如 payloads: []）
自我消息	缺乏内置的自我消息过滤机制，易产生循环
超时处理	CLI 默认超时较短，Agent 运行时间长时易误报

适用场景

• ✅ 个人 AI 助理（通过 iMessage/WhatsApp 等与 AI 对话）
• ✅ 自动化消息处理与回复
• ✅ 跨平台消息网关
• ✅ 开发者构建自定义聊天机器人
• ✅ 隐私敏感用户（数据本地处理）

不适用场景

• ❌ 需要快速上手的非技术用户
• ❌ 无 macOS 设备的用户（iMessage 限制）
• ❌ 需要高并发处理的企业场景

最终评价

Clawdbot 是一款功能强大的本地 AI 聊天网关，尤其适合注重隐私、需要多渠道整合的技术用户。配置过程有一定门槛（尤其是 macOS 权限配置和 Agent 工作区优化），但一旦完成配置，使用体验流畅。

对于想要通过 iMessage 与 AI 对话的 macOS 用户，Clawdbot + imsg 是目前最佳的开源方案之一。

综合评分：4/5 ⭐

---

附录：快速开始指南

如果你想快速开始使用 Clawdbot + iMessage，按以下步骤操作：

# 1. 安装 imsg
brew install steipete/tap/imsg

# 2. 初始化 clawdbot
clawdbot setup
clawdbot config set gateway.mode local

# 3. 配置 iMessage 通道（编辑 ~/.clawdbot/clawdbot.json）

# 4. 授予 Full Disk Access 权限给 Terminal 和 Node.js

# 5. 配置 OpenAI API
clawdbot models auth paste-token --provider openai
clawdbot models set openai/gpt-4o-mini

# 6. 简化工作区（可选但推荐）
# 编辑 ~/clawd/AGENTS.md 和 ~/clawd/SOUL.md

# 7. 启动 Gateway
clawdbot gateway install
clawdbot gateway start

# 8. 测试
clawdbot health
clawdbot agent --message "Hello" --channel imessage --to +1234567890 --deliver

---