内容
# 克劳德代码 iMessage 连接器
将 iMessage 连接到您的克劳德代码会话中，使用 MCP 服务器。
克劳德 iMessage MCP 服务器连接到 Linq iMessage API，并为克劳德提供工具来回复、反应或编辑 iMessage。当您向 Linq 号码发送短信时，服务器将消息转发到您的克劳德代码会话。
## 先决条件
- [克劳德代码](https://claude.ai/code) v2.1.80+
- [Node.js](https://nodejs.org) >= 22
## 快速设置
单用户设置的默认配对流程。有关多用户和策略选项，请参见[访问控制](#访问控制)。
### 1. 获取 Linq 号码
您需要一个 Linq API 令牌和电话号码。有两个选项：
**选项 A：免费沙盒（推荐试用）**
安装 [Linq CLI](https://github.com/linq-team/linq-cli) 并注册一个沙盒号码（3 小时到期，通过 GitHub 身份验证）：
```bash
# 安装 CLI
curl -fsSL https://raw.githubusercontent.com/linq-team/linq-cli/main/install.sh | sh
# 注册 - 打开浏览器进行 GitHub 身份验证，分配一个沙盒号码
linq signup
# 查看您的令牌和电话号码
linq profile
```
**选项 B：现有的 Linq 账户**
从 [Linq 仪表板](https://zero.linqapp.com/api-tooling/) 获取您的令牌。您的电话号码列在您的账户下。
### 2. 安装插件
这些是克劳德代码命令 - 运行 `claude` 以启动会话：
```bash
/plugin marketplace add linq-team/claude-code-imessage-channel
/plugin install imessage@linq
```
### 3. 提供服务器您的凭证
```bash
/imessage:configure <您的Linq令牌>
/imessage:configure <您的Linq电话号码>
```
写入 `LINQ_TOKEN=...` 和 `LINQ_FROM_PHONE=...` 到 `~/.claude/channels/imessage/.env`。您也可以手动编写该文件，或在 shell 环境中设置变量 - shell 优先。
### 4. 重新启动并带有通道标志
服务器如果没有此标志将无法连接 - 退出您的会话并启动一个新的：
```bash
claude --dangerously-load-development-channels plugin:imessage@linq
```
> **注意：** 不要从插件仓库目录启动 - 本地 `.mcp.json` 将冲突。请从其他目录启动（例如 `~/Desktop`，您的项目文件夹等）。
### 5. 配对
在上一步骤中启动克劳德代码后，使用 iMessage 给您的 Linq 号码发送短信 - 您将收到一个 6 位配对代码。在您的克劳德代码会话中：
```bash
/imessage:access pair <代码>
```
您的下一条短信将到达助手。
### 6. 锁定
配对用于捕获电话号码。一旦您进入，请切换到允许列表，以免陌生人收到配对代码回复：
```bash
/imessage:access policy allowlist
```
### 可选：设置启动问候语
这样克劳德在启动时会自动发送短信给您：
```bash
/imessage:access recipient +1XXXXXXXXXX
```
重新启动克劳德代码并带有通道标志。克劳德在启动时发送短信给您。
## 访问控制
Linq 号码可以通过 iMessage 公共访问。任何知道该号码的人都可以发送短信，并且如果没有门控，这些消息会直接流入您的助手会话。访问模型决定了谁可以通过。
默认情况下，来自未知发送者的短信会触发**配对**：服务器用 6 位代码回复并丢弃消息。您可以通过在助手会话中运行 `/imessage:access pair <代码>` 来批准他们。一旦批准，他们的消息就会通过。
所有状态都存储在 `~/.claude/channels/imessage/access.json` 中。`/imessage:access` 技能命令会编辑此文件；服务器会在每个传入消息时重新读取它，因此更改立即生效，无需重启。
### 一览
| | |
|-|-|
| 默认策略 | `pairing` |
| 发送者 ID | E.164 格式的电话号码（例如 `+1XXXXXXXXXX`） |
| 配置文件 | `~/.claude/channels/imessage/access.json` |
### 直接消息策略
`dmPolicy` 控制来自不在允许列表中的发送者的消息处理方式。
| 策略 | 行为 |
|--------|----------|
| `pairing`（默认） | 用配对代码回复，丢弃消息。通过 `/imessage:access pair <代码>` 批准。 |
| `allowlist` | 静默丢弃。无回复。适用于共享号码且配对回复会吸引垃圾信息。 |
| `open` | 任何人都可以发送消息。无过滤。 |
| `disabled` | 丢弃所有消息，包括允许列表中的发送者。 |
```bash
/imessage:access policy allowlist
```
### 电话号码
iMessage 使用电话号码作为标识符。允许列表存储 E.164 格式的号码（例如 `+1XXXXXXXXXX`）。配对会自动捕获号码。
```bash
/imessage:access allow +1XXXXXXXXXX
/imessage:access remove +1XXXXXXXXXX
```
### 投递
使用 `/imessage:access set <键> <值>` 配置传入行为。
**ackReaction** - 消息接收时发送的 tapback。iMessage 支持：`like`、`love`、`laugh`、`dislike`、`emphasize`、`question`。空字符串禁用。
```bash
/imessage:access set ackReaction love
/imessage:access set ackReaction ""
```
**pollInterval** - 服务器检查新消息的频率，单位为毫秒。默认 `3000`。
```bash
/imessage:access set pollInterval 5000
```
### 技能参考
| 命令 | 效果 |
|---------|--------|
| `/imessage:access` | 打印当前状态：策略、允许列表、待配对。 |
| `/imessage:access pair a4f91c` | 批准配对代码。将发送者添加到 `allowFrom`。 |
| `/imessage:access deny a4f91c` | 丢弃待处理代码。发送者不会收到通知。 |
| `/imessage:access allow +1XXXXXXXXXX` | 直接添加电话号码。 |
| `/imessage:access remove +1XXXXXXXXXX` | 从允许列表中移除。 |
| `/imessage:access policy allowlist` | 设置 dmPolicy。值：`pairing`、`allowlist`、`open`、`disabled`。 |
| `/imessage:access recipient +1XXXXXXXXXX` | 设置启动问候语的默认收件人。 |
| `/imessage:access set ackReaction love` | 设置配置键：`ackReaction`、`pollInterval`。 |
| `/imessage:access clear` | 删除 access.json，重置为默认值。 |
### 配置文件
`~/.claude/channels/imessage/access.json`。不存在的文件等同于具有空列表的 `pairing` 策略，因此第一条短信会触发配对。
```json
{
"dmPolicy": "pairing",
"allowFrom": ["+1XXXXXXXXXX"],
"defaultRecipient": "+1XXXXXXXXXX",
"pendingPairings": {
"a4f91c": { "phone": "+1XXXXXXXXXX", "createdAt": "2026-03-20T..." }
},
"ackReaction": "love",
"pollInterval": 3000
}
```
## 配置
凭证存储在 `~/.claude/channels/imessage/.env` 中：
```
LINQ_TOKEN=您的API令牌
LINQ_FROM_PHONE=+1XXXXXXXXXX
```
使用 `/imessage:configure` 管理：
| 命令 | 效果 |
|---------|--------|
| `/imessage:configure` | 显示当前状态（令牌设置？电话号码设置？）。 |
| `/imessage:configure <令牌>` | 将令牌保存到 `.env`。 |
| `/imessage:configure +1XXXXXXXXXX` | 将电话号码保存到 `.env`。 |
| `/imessage:configure clear` | 删除所有凭证。 |
环境变量（`LINQ_TOKEN`、`LINQ_FROM_PHONE` 等）覆盖 `.env` 文件。
## 暴露给助手的工具
| 工具 | 目的 |
|------|---------|
| `reply` | 回复传入的 iMessage。需要 `chat_id` + `text`。可选：`effect`、`reply_to`、`files`、`text_decorations`。返回已发送的消息 ID。 |
| `send` | 发送到任何电话号码。需要 `to` + `text`。可选：`effect`、`files`、`text_decorations`。返回 `chat_id` + `message_id`。 |
| `react` | 对消息 ID 的 tapback 反应。值：`like`、`love`、`laugh`、`dislike`、`emphasize`、`question`。 |
| `edit_message` | 编辑以前发送的消息。对“working…” → 结果进度更新很有用。 |
| `send_link` | 发送带有丰富链接预览卡的 URL。需要 `chat_id` + `url`。链接必须是唯一内容。 |
| `check_capability` | 检查电话号码是否支持 iMessage 或 RCS。需要 `phone`，可选 `service`（`imessage` 或 `rcs`）。 |
传入消息会自动触发打字指示器 - iMessage 在助手处理响应时会显示打字。
## 无历史记录或搜索
Linq API 会轮询最近的消息，但不提供完整的聊天历史记录或搜索。服务器只会在消息到达时看到它们 - 如果助手需要更早的上下文，它将要求您粘贴或总结。
## 工作原理
```
您的手机 → iMessage → Linq API → 轮询器 → 克劳德代码会话
克劳德回复 → Linq API → iMessage → 您的手机
```
通道服务器每 3 秒轮询一次 Linq API 以获取新消息（可通过 `pollInterval` 配置）。无需 webhook URL、无需 ngrok、无需端口转发。如果您更喜欢实时交付，则可以使用端口 9998 上的 webhook 监听器作为备用方案。
当克劳德启动时，它会自动设置一个联系人卡片（带有徽标的“克劳德代码”），以便收件人在 iMessage 中看到友好的名称。
## 照片
传入的照片下载到 `~/.claude/channels/imessage/inbox/`，本地路径包含在通道通知中，以便助手可以读取。iMessage 会压缩照片 - 如果您需要原始文件，请改为发送文档。
## 效果
使用可选的 `effect` 参数为任何发出的消息添加 iMessage 效果：
- **屏幕效果：** `confetti`、`fireworks`、`lasers`、`sparkles`、`celebration`、`hearts`、`love`、`balloons`、`happy_birthday`、`echo`、`spotlight`
- **气泡效果：** `slam`、`loud`、`gentle`、`invisible`
每条消息只能使用一种效果。效果仅在 iOS/macOS 上可见。
## 文本装饰
使用 `text_decorations` 参数样式化文本。每个装饰指定一个字符范围和样式或动画。
- **样式：** `bold`、`italic`、`strikethrough`、`underline`
- **动画：** `big`、`small`、`shake`、`nod`、`explode`、`ripple`、`bloom`、`jitter`
示例：发送“hello world”，其中“hello”为粗体 → `text_decorations: [{"range": [0, 5], "style": "bold"}]`
样式范围可以重叠，但动画不能与其他动画或样式重叠。文本装饰仅适用于 iMessage 收件人。
## 功能
- **双向 iMessage** - 文本输入，获得 iMessage 回复
- **文件附件** - 通过本地文件路径发送图像、视频、音频、文档
- **传入照片** - 下载到 `~/.claude/channels/imessage/inbox/`，克劳德可以查看
- **iMessage 效果** - 烟花、激光、slam、gentle 等 12 种屏幕/气泡效果
- **线程回复** - 使用 `reply_to` 回复特定消息
- **SMS/RCS 备用** - 消息首先尝试 iMessage，自动备用
- **访问控制** - 配对流程、允许列表、开放或禁用策略
- **已读回执** - 当您的消息收到时自动发送
- **打字指示器** - 显示打字时克劳德处理
- **Tapback 反应** - 克劳德可以用 like、love、laugh 等反应
- **确认反应** - 消息接收时可配置的 tapback
- **流式编辑** - 发送“working…”然后更新原位（iOS 16+）
- **文本装饰** - 粗体、斜体、删除线、下划线 + 动画（shake、explode、ripple 等）
- **丰富链接预览** - 使用 `send_link` 发送带有预览卡的 URL
- **能力检查** - 在发送前验证 iMessage/RCS 支持
- **联系人卡片** - 自动设置为“克劳德代码”并带有徽标
- **无需 ngrok** - 基于轮询，适用于任何防火墙
## 插件结构
```
claude-code-imessage-channel/
├── .claude-plugin/
│ ├── plugin.json # 插件清单
│ └── marketplace.json # 市场目录
├── .mcp.json # MCP 服务器配置
├── skills/
│ ├── access/
│ │ └── SKILL.md # 访问控制技能
│ ├── configure/
│ │ └── SKILL.md # 配置技能
│ └── imessage/
│ └── SKILL.md # 使用提示技能
├── src/
│ └── channel.ts # 通道服务器
├── CLAUDE.md
├── package.json
└── tsconfig.json
```
## 要求
- Node.js >= 22
- 克劳德代码 v2.1.80+，支持通道
- 具有 API 令牌和电话号码的 [Linq](https://linqapp.com) 账户
## 贡献
我们使用 PR 工作流程，`dev` 作为工作分支。
```bash
# 克隆并设置
git clone https://github.com/linq-team/claude-code-imessage-channel.git
cd claude-code-imessage-channel
git checkout dev
npm install
# 创建功能分支
git checkout -b feat/my-feature
# 进行更改、构建、测试
npm run build
# 推送并打开 PR 对抗 dev
git push origin feat/my-feature
# 然后在 GitHub 上打开 PR：base=dev
```
### 分支策略
| 分支 | 目的 |
|--------|---------|
| `main` | 生产环境。受保护 - 需要 1 次审查。仅从 `dev` 合并。 |
| `dev` | 工作分支。PR 首先在此合并。 |
| `feat/*` | 功能分支从 `dev` 分支。 |
| `fix/*` | 从 `dev` 分支修复错误。 |
### 提交消息
使用约定提交：`feat:`、`fix:`、`docs:`、`chore:`、`refactor:`、`test:`
### 提交 PR 前
1. `npm run build` 通过
2. 差异中无机密信息或 PII
3. 如果您添加/更改配置或功能，请更新 README
## 许可证
MIT
