line

claude-channel-line

把 LINE Messaging API 串到 Claude Code 做雙向訊息互動的 channel plugin。

• Claude 可主動透過 LINE 發訊息給你
• 你在 LINE 傳的訊息會被推進 Claude session，由 Claude 看到並回覆
• 內建白名單（pair / allowlist / disabled 三種 policy）
• 使用者身份：每個白名單 user 可標 暱稱 / 稱謂 / 角色，Claude 會用你給的名字稱呼、依角色調整信任度
• 搭配你自管的常駐 tunnel（建議 Cloudflare Named Tunnel），webhook URL 永久固定。channel 本身只 listen 本機 port，不再代管 cloudflared 子進程

架構

LINE 用戶 ──► LINE Platform
                  │ HTTPS webhook
                  ▼
        Cloudflare Tunnel (HTTPS)
                  │
                  ▼
   localhost:8788 (Bun + Hono)
                  │ 簽章驗證 → access policy
                  ▼
           MCP notification ──► Claude Code session
                                       │
                                       ▼
                              line_reply / line_push tool
                                       │
                  LINE Platform ◄──────┘

Channel 是一個 MCP server 子進程（透過 claude --dangerously-load-development-channels 啟動），同時在本機跑 webhook server 接收 LINE 推送，並暴露 MCP tools 讓 Claude 對 LINE 發訊息。

Prerequisites

裝這幾個工具：

• Bun 1.x — 建議 npm install -g bun（或 brew install oven-sh/bun/bun）
• Claude Code 2.1.123+
• cloudflared — brew install cloudflared
• 一組 LINE Messaging API channel 的 access token 與 channel secret
• 一個指向 Cloudflare 的網域（例如 casper.tw），用來建立永久固定的 webhook URL

Concepts

LINE 帳號層級對照：

層級	說明
Business ID	你的 LINE 商業帳號
Provider	在 Business ID 之下的「服務提供者」（一旦選定不能改）
Messaging API channel	對應一個官方帳號（Official Account），這就是 bot 本身。token / secret 在這裡取得

兩種容易混淆的設定：

• Channel access token（長期）→ 用來呼叫 LINE API 發訊息
• Channel secret → 用來驗證 LINE webhook 的簽章

Quick Start

你先把一條常駐的 Cloudflare Named Tunnel 跑起來（與 Claude 解耦、開機自動啟動），channel 只透過 LINE_PUBLIC_URL 指向它——URL 永久固定，LINE Console webhook URL 設一次就好。

v0.3.0 起：channel 不再自動 spawn cloudflared。 過去由 channel 代管的 cloudflared 子進程，連線穩定度與 Claude session lifecycle 綁在一起，session 重啟時容易斷線。現在 tunnel 改由你自管成常駐服務，channel 只 listen localhost:8788。舊 .env 裡的 LINE_TUNNEL_MODE / LINE_TUNNEL_NAME 會被忽略，不需要移除。

1. 申請 LINE Messaging API channel

1. LINE Business ID 登入或註冊
2. LINE Official Account Manager 建立官方帳號
3. 帳號頁右上角 Settings → Messaging API → Enable（會自動建一個 Provider 與 channel）
4. Settings → Response settings：
   • 「Chat (聊天)」→ Off（很多人卡這——詳見 Troubleshooting）
   • 「Webhook」→ On
   • 「Auto-response messages」→ Off
   • 「Greeting messages」→ Off
5. 進入 LINE Developers Console → 點選剛建立的 channel：
   • Basic settings 分頁底部複製 Channel secret
   • Messaging API 分頁底部 Issue + 複製 Channel access token (long-lived)

2. 設 Cloudflare Named Tunnel（做完一次永久不用再動）

需要：Cloudflare 帳號 + 一個指向 Cloudflare DNS 的網域。

# 一、登入（瀏覽器跳出選網域、Authorize）
cloudflared tunnel login

# 二、建 tunnel（記下回傳的 tunnel ID）
cloudflared tunnel create line-bot-channel

# 三、把子網域路由到 tunnel
cloudflared tunnel route dns line-bot-channel line-bot.example.com

# 四、寫 ~/.cloudflared/config.yml：
cat > ~/.cloudflared/config.yml <<EOF
tunnel: <剛建的 tunnel id>
credentials-file: $HOME/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: line-bot.example.com
    service: http://localhost:8788
  - service: http_status:404
EOF

驗證 tunnel 設定 OK（先手動跑一次測試）：

# 啟動 tunnel
cloudflared tunnel run line-bot-channel &

# 另外一個終端起一個假 server
( printf 'HTTP/1.1 200 OK\r\nContent-Length: 11\r\n\r\ntunnel ok!\n' | nc -l 8788 ) &
sleep 1
curl -s https://line-bot.example.com/

# 看到 "tunnel ok!" 即通了
pkill -f "cloudflared tunnel run"

2-1. 把 tunnel 變成「永久性連線」（常駐服務）

⚠️ 重點：channel 不會幫你跑 cloudflared。你必須自己讓 tunnel 常駐——開機自動啟動、crash 自動重連、跟 Claude session 完全解耦。這樣 session 重啟也不會斷線。

推薦：裝成系統服務（macOS launchd / Linux systemd）

# cloudflared 會讀 ~/.cloudflared/config.yml，註冊成開機自動啟動、crash 自動重連的背景服務
sudo cloudflared service install

# 啟動服務
sudo launchctl start com.cloudflare.cloudflared   # macOS
# sudo systemctl enable --now cloudflared          # Linux

# 確認在跑（看到 connection registered / 4 條連線即 OK）
cloudflared tunnel info line-bot-channel

之後 cloudflared 就一直在背景跑、開機自動起，你完全不用再管它。要停掉：

sudo cloudflared service uninstall   # 移除服務

替代方案：自管 LaunchAgent（不用 sudo、跟著登入的使用者跑）

在 ~/Library/LaunchAgents/com.line-bot.cloudflared.plist 放：