内容
# Claude 代码的 LINE 频道
[繁體中文](README.zh-TW.md) | | [日本語](README.ja.md) | [한국어](README.ko.md)
通过 LINE Messaging API 将 LINE 消息推送到您的 Claude Code 会话中，以便 Claude 可以实时接收和回复您的 LINE 消息。
---
## 目录
- [要求](#要求)
- [先决条件](#先决条件)
- [安装 Claude Code](#1-安装-claude-code)
- [安装 Bun](#2-安装-bun)
- [安装 ngrok](#3-安装-ngrok)
- [创建 LINE 机器人](#4-创建-line-机器人)
- [设置](#设置)
- [克隆仓库](#1-克隆仓库)
- [保存 LINE 凭证](#2-保存-line-凭证)
- [添加 MCP 服务器](#3-添加-mcp-服务器)
- [启动 ngrok](#4-启动-ngrok)
- [配置 LINE Webhook](#5-配置-line-webhook)
- [启动 Claude Code](#6-启动-claude-code)
- [配对您的 LINE 账户](#7-配对您的-line-账户)
- [始终在线的 Webhook 服务（自动启动）](#始终在线的-webhook-服务自动启动)
- [添加更多用户](#添加更多用户)
- [访问策略](#访问策略)
- [发送消息](#发送消息)
- [图像备份到 Google Drive](#图像备份到-google-drive)
- [环境变量](#环境变量)
- [通过 LINE 进行远程权限审批](#通过-line-进行远程权限审批)
- [故障排除](#故障排除)
---
## 要求
- **操作系统**：Windows / macOS / Linux
- **Claude Code** v2.1.80+，使用 claude.ai 账户登录（不是 API 密钥）
- **Bun** 运行时
- **ngrok** 账户（免费层即可）
- **LINE Developers** 账户（免费）
---
## 先决条件
### 1. 安装 Claude Code
```bash
npm install -g @anthropic-ai/claude-code
```
然后登录：
```bash
claude
```
按照提示使用您的 claude.ai 账户登录。
---
### 2. 安装 Bun
**macOS / Linux：**
```bash
curl -fsSL https://bun.sh/install | bash
```
**Windows (PowerShell)：**
```powershell
powershell -c "irm bun.sh/install.ps1 | iex"
```
验证安装：
```bash
bun --version
```
---
### 3. 安装 ngrok
在 [https://ngrok.com](https://ngrok.com) 注册一个免费账户，然后：
**macOS (Homebrew)：**
```bash
brew install ngrok
```
**Windows：**
从 [https://ngrok.com/download](https://ngrok.com/download) 下载，解压并添加到 PATH。
**设置您的 authtoken** （从 [ngrok 仪表盘](https://dashboard.ngrok.com/get-started/your-authtoken) 复制）：
```bash
ngrok config add-authtoken YOUR_AUTHTOKEN
```
---
### 4. 创建 LINE 机器人
1. 访问 [LINE Developers Console](https://developers.line.biz/console/) 并登录
2. 点击 **创建提供者** 并输入名称（例如 `我的 Claude 机器人`）
3. 点击 **创建新频道** → 选择 **Messaging API**
4. 填写必填字段（频道名称，描述，类别）并创建
获取您的凭证：
- **频道密钥**：频道 → **基本设置** 标签 → 复制 `频道密钥`
- **频道访问令牌**：频道 → **Messaging API** 标签 → 滚动到底部 → 点击 **发布** → 复制令牌
在 **Messaging API** 标签中，禁用以下内容以防止自动回复干扰：
- **自动回复消息** → **禁用**
- **欢迎消息** → **禁用**
---
## 设置
### 1. 克隆仓库
```bash
git clone https://github.com/Moksa1123/claude-channel-line
cd claude-channel-line
```
---
### 2. 保存 LINE 凭证
凭证存储在 `~/.claude/channels/line/.env` 中，**不会** 提交到 git。
**macOS / Linux：**
```bash
mkdir -p ~/.claude/channels/line
cat > ~/.claude/channels/line/.env << EOF
LINE_CHANNEL_ACCESS_TOKEN=您的频道访问令牌
LINE_CHANNEL_SECRET=您的频道密钥
EOF
```
**Windows (PowerShell)：**
```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\channels\line"
@"
LINE_CHANNEL_ACCESS_TOKEN=您的频道访问令牌
LINE_CHANNEL_SECRET=您的频道密钥
"@ | Set-Content "$env:USERPROFILE\.claude\channels\line\.env"
```
---
### 3. 添加 MCP 服务器
**macOS / Linux：**
```bash
claude mcp add line bun "/path/to/claude-channel-line/server.ts"
```
**Windows：**
```powershell
claude mcp add line bun "C:/path/to/claude-channel-line/server.ts"
```
> 将路径替换为实际的克隆仓库位置。
验证是否添加成功：
```bash
claude mcp list
```
您应该在列表中看到 `line`。
---
### 4. 启动 ngrok
打开一个 **单独的终端窗口** 并运行：
```bash
ngrok http 8789
```
您应该看到类似的内容：
```
Forwarding https://xxxx.ngrok-free.app -> http://localhost:8789
```
复制 `https://xxxx.ngrok-free.app` URL — 您将在下一步中使用它。
> **注意**：保持 ngrok 窗口打开。关闭它将断开隧道。URL 每次重启 ngrok 时都会更改（免费计划），因此您需要每次都更新 LINE 控制台中的 Webhook URL。
---
### 5. 配置 LINE Webhook
回到 [LINE Developers Console](https://developers.line.biz/console/)，打开您的频道：
1. 点击 **Messaging API** 标签
2. 找到 **Webhook URL** 字段并点击 **编辑**
3. 输入：`https://xxxx.ngrok-free.app/webhook`（用您的 ngrok URL 替换）
4. 点击 **更新**
5. 启用 **使用 webhook** 切换按钮
6. 点击 **验证** → 应该显示 **成功**
---
### 6. 启动 Claude Code
打开一个 **新的终端窗口** 并运行：
```bash
claude --dangerously-load-development-channels server:line
```
Claude Code 将连接到 LINE MCP 服务器并开始监听消息。
> **重要**：您必须在每次启动 Claude Code 时包含 `--dangerously-load-development-channels server:line`。如果没有此标志运行 `claude` 将不会接收 LINE 消息。
> **Windows 注意**：在常规终端（PowerShell / CMD）中运行此命令，而不是在 Claude Code 内部。
---
### 7. 配对您的 LINE 账户
1. 打开 LINE 并找到您的机器人（**机器人基本 ID** 在 LINE Developers Console → Messaging API 中显示）
2. 向机器人发送任意消息，例如 `hi`
3. 机器人将回复配对代码：
```
配对代码：A1B2C3
在 Claude Code 中运行：
/line:access pair A1B2C3
```
4. 查找该配对代码的用户 ID：
**macOS / Linux：**
```bash
cat ~/.claude/channels/line/pending/A1B2C3.json
```
**Windows (PowerShell)：**
```powershell
Get-Content "$env:USERPROFILE\.claude\channels\line\pending\A1B2C3.json"
```
输出：
```json
{
"userId": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"expires": 1234567890000
}
```
5. 通过编辑 `~/.claude/channels/line/access.json` 将用户 ID 添加到允许列表：
**macOS / Linux：**
```bash
cat > ~/.claude/channels/line/access.json << EOF
{
"policy": "allowlist",
"allowlist": ["Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"]
}
EOF
```
**Windows (PowerShell)：**
```powershell
@"
{
"policy": "allowlist",
"allowlist": ["Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"]
}
"@ | Set-Content "$env:USERPROFILE\.claude\channels\line\access.json"
```
6. 发送另一条 LINE 消息 — Claude 现在将接收并回复它！
---
## 始终在线的 Webhook 服务（自动启动）
默认情况下，webhook 服务器在 Claude Code 的 MCP 进程中运行 — **当 Claude Code 关闭时停止**，导致 LINE 接收到 502 错误。
`webhook-service.ts` 是一个独立的服务器，即使在 Claude Code 未运行时，也能保持 webhook 的活跃。传入的消息会排队在 `~/.claude/channels/line/messages/` 中，并在 Claude Code 启动时自动拾取。
队列处理包括以下可靠性功能：
- **20 秒启动延迟** — 等待 MCP 连接稳定后再处理排队消息
- **离线消息通知** — 在重新连接时，推送一条 LINE 消息，列出任何错过消息，以便用户知道丢失了什么
- **自动重试（3 次）** — 失败的消息传递最多重试 3 次，然后再丢弃
- **过期回复令牌清理** — 早于 25 秒的回复令牌自动清除（LINE 令牌在 30 秒后过期）
- **2 秒关闭监视狗** — 防止 MCP 断开连接时的僵尸进程（匹配官方 Telegram/Discord 插件模式）
### Windows
从项目目录运行安装脚本（自动检测 bun 路径并创建启动条目）：
```powershell
powershell -ExecutionPolicy Bypass -File "autostart\windows\install.ps1"
```
这会在启动文件夹中创建一个后台 `.vbs` 脚本，并立即启动服务 — 无需重启。
---
### macOS
```bash
chmod +x autostart/macos/install.sh
./autostart/macos/install.sh
```
使用 launchd Launch Agent。自动检测 bun 路径并注册服务以启动登录。
要停止：
```bash
launchctl stop com.line-webhook
launchctl unload ~/Library/LaunchAgents/com.line-webhook.plist
```
---
### Linux (systemd)
```bash
chmod +x autostart/linux/install.sh
./autostart/linux/install.sh
```
使用 systemd 用户服务。自动检测 bun 路径并在登录时启用服务。
查看日志：
```bash
systemctl --user status line-webhook
journalctl --user -u line-webhook -f
```
---
## 添加更多用户
要允许其他人使用机器人：
1. 让他们添加机器人为好友并发送消息 — 他们将收到配对代码
2. 让他们与您分享配对代码
3. 在 `~/.claude/channels/line/pending/<code>.json` 中查找他们的用户 ID
4. 将他们的用户 ID 添加到 `access.json` 中的允许列表：
```json
{
"policy": "allowlist",
"allowlist": [
"U您的用户 ID",
"U他们的用户 ID"
]
}
```
---
## 访问策略
编辑 `~/.claude/channels/line/access.json` 中的 `policy` 字段：
| 策略 | 行为 | 何时使用 |
|--------|----------|-------------|
| `pairing` | 任何消息机器人的人都会收到配对代码（默认） | 初始设置，添加新用户 |
| `allowlist` | 只有 allowlist 中的用户 ID 才能发送消息；其他消息被静默丢弃 | 正常使用 — 推荐 |
| `open` | 任何人都可以发送消息 | 不推荐 — 无访问控制 |
---
## 发送消息
Claude 可以使用以下消息类型回复 LINE 用户：
| 工具 | 类型 | 描述 |
|------|------|-------------|
| `reply` | 文本 | 普通文本消息（自动在 5,000 个字符处分割，最多 5 个块） |
| `reply_image` | 图片 | 通过 HTTPS URL 发送图片 |
| `reply_flex` | Flex 消息 | 丰富的卡片布局 — 支持按钮，链接，图片和轮播（气泡 / 轮播） |
| `reply_mixed` | 混合 | 在单个调用中发送最多 5 条任意类型消息 |
> **注意**：`reply_token` 在接收消息后 30 秒内有效。过期后，Claude 自动切换到使用 `user_id` 的推送模式。
---
## 图片备份到 Google Drive
当用户通过 LINE 发送图片时，`webhook-service.ts` 可以自动下载并将它们上传到 Google Drive 作为备份。每个图片都以时间戳命名（`LINE_YYYYMMDD_HHMMSS.jpg`），用户会收到一个包含 Drive 链接的确认回复。
### 设置
1. **Google OAuth2 凭证**：将您的凭证文件放在：
```
~/.google_workspace_mcp/credentials/<您的电子邮件>.json
```
文件必须包含有效的 `refresh_token`，`client_id` 和 `client_secret`。
2. **配置目标文件夹**：在 `webhook-service.ts` 中将 `GDRIVE_FOLDER_ID` 常量设置为要上传图片的 Google Drive 文件夹 ID。
> 要查找文件夹 ID，请在 Google Drive 中打开文件夹并复制 URL 的最后一部分：`https://drive.google.com/drive/folders/<FOLDER_ID>`
### 工作原理
1. 用户在 LINE 聊天中发送图片
2. `webhook-service.ts` 从 LINE 的内容 API 下载图片二进制数据
3. 图片通过 Google Drive API 上传到配置的 Google Drive 文件夹
4. 用户收到一条 LINE 回复，确认备份并提供指向 Google Drive 文件的直接链接
---
## 通过 LINE 进行远程权限审批
通过手机批准或拒绝 Claude Code 工具调用。当 Claude 尝试进行危险操作（例如 shell 命令）时，会通过 LINE 推送带有允许/拒绝按钮的 Flex 消息。安全操作（只读命令）会自动批准。
### 工作原理
1. Claude 调用 Bash 命令（例如 `git push`）
2. `approve-hook.ts` 通过 PreToolUse 钩子拦截
3. 安全命令（`git status`，`ls` 等）立即通过
4. 危险命令会将带有命令详细信息的 Flex 卡片推送到 LINE
5. 您在手机上点击 **允许** 或 **拒绝**
6. 60 秒超时 — 如果没有响应，则自动拒绝
### 设置
将钩子添加到您的 Claude Code 设置（`~/.claude/settings.json`）：
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bun /path/to/claude-channel-line/approve-hook.ts",
"timeout": 120
}
]
}
]
}
}
```
### 配置
编辑 `~/.claude/channels/line/approve-config.json`:
```json
{
"scope": "line-only"
}
```
| 范围 | 行为 |
|-------|----------|
| `line-only` | 仅限使用 `LINE_APPROVE=1` 启动的会话触发 LINE 审批（默认） |
| `all` | 所有会话都向 LINE 发送审批请求 |
### 启动带有审批的 LINE 会话
```bash
LINE_APPROVE=1 claude --resume --dangerously-load-development-channels server:line
```
只有此会话会向 LINE 发送审批请求。其他会话运行钩子但立即自动批准（无需 API 调用）。
### 审批内容
| 操作 | 审批 |
|-----------|----------|
| 只读 Bash（`git status`，`ls`，`cat`，`pwd`） | 自动批准 |
| 破坏性 Bash（`git push`，`rm`，`npm publish`） | 需要 LINE 审批 |
| 编辑 `.env`，`.key`，`.pem` 文件 | 需要 LINE 审批 |
| 所有其他工具（Read，Glob，Grep 等） | 自动批准 |
### 注意事项
- 每次审批都使用一次 LINE 推送 API 调用（免费计划：200/月）
- `webhook-service.ts` 必须运行以接收后退按钮响应
- 需要新的 Claude Code 会话以加载设置.json 中的钩子更改
---
## 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `LINE_CHANNEL_ACCESS_TOKEN` | LINE 频道访问令牌 | **必填** |
| `LINE_CHANNEL_SECRET` | LINE 频道密钥 | **必填** |
| `LINE_WEBHOOK_PORT` | Webhook 服务器端口 | `8789` |
| `GDRIVE_FOLDER_ID` | 用于图片备份的 Google Drive 文件夹 ID（在 `webhook-service.ts` 中设置） | — |
---
## 故障排除
**验证显示 502 Bad Gateway**
Webhook 服务器未运行。两个选项：
- **快速修复**：使用 `claude --dangerously-load-development-channels server:line` 启动 Claude Code — 它还将启动 Webhook 服务器。
- **永久修复**：设置 [始终在线的 Webhook 服务](#始终在线的-webhook-服务自动启动)，使 Webhook 独立于 Claude Code 运行。
**机器人不响应消息**
- 检查 ngrok 是否仍在运行
- 检查 LINE Webhook URL 是否正确且 **使用 webhook** 已启用
- 检查 `access.json` 是否具有正确的策略和用户 ID 在允许列表中
**ngrok URL 每次重启都更改**
免费的 ngrok 计划每次重启都分配一个新的 URL。您需要每次都更新 LINE 开发者控制台中的 Webhook URL。升级到付费计划以获取固定 URL。
**特殊字符的令牌在 Windows 上失败**
用引号包裹令牌：
```powershell
$env:LINE_CHANNEL_ACCESS_TOKEN="您的令牌+特殊字符"
```
**MCP 服务器无法启动 — 端口已被占用**
如果您运行了始终在线的 Webhook 服务，`server.ts` 会自动检测端口冲突并切换到队列模式 — 无需操作。
要使用不同的端口：
```bash
claude mcp remove line
claude mcp add line bun "/path/to/server.ts" -e LINE_WEBHOOK_PORT=8790
ngrok http 8790
```
---
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器