LINE

ZeroClaw 通过 Messaging API 支持 LINE，使用内嵌的 webhook 服务器接收消息，并通过 Reply API 进行回复（当回复令牌过期时回退到 Push API）。

谁可以与代理通信

入站发送方会根据为绑定代理解析出的对等集合进行限制，该集合来自代理所属的 peer_groups 配置。匹配时会去除开头的 @，并对通道的原生发送方标识符执行不区分大小写的比对。空集合会拒绝所有人；包含 "*" 的集合会接受所有人；否则仅接受列出的外部对等方（以及对等代理）。这与网关配对（gateway.require_pairing）不同，后者验证的是 HTTP/WebSocket 客户端，而非聊天通道的发送方。

用于 line 的对等组将 channel 设置为 line，在 external_peers 中列出允许的发送者（对于 line，即 LINE 用户 ID；["*"] 接受任何人），可选地命名用于跨代理调度的对等 agents、ignore 屏蔽列表，以及 output_modality（mirror、voice 或 text）。字段参考请参阅 Peer Groups。

在何处设置：

网关仪表板

在 Web 仪表板中打开 /config/peer_groups。

zerocode

在 Config 窗格中的 Peer groups 下。

LINE 在对等节点集合之上叠加了 dm_policy 和 group_policy，详见下文的访问策略。当某个策略设置为 allowlist 时，对等节点集合即为允许列表。

前置条件

一个 LINE Developers Console 账户。
可从 LINE 服务器访问的公共 HTTPS 端点（或用于本地开发的 ngrok）。
ZeroClaw 已启用 LINE 频道支持（zeroclaw-channels crate 上的 channel-line 功能）。

1. 创建 LINE Bot

登录 LINE Developers Console。
创建一个 Provider（或使用现有的 Provider）。
在该提供商下创建一个新的 Messaging API 通道。
从频道设置中，收集两个值：
- Channel Access Token：Messaging API 标签页 → Issue（签发）一个长期有效的令牌。
- Channel Secret：基本设置选项卡。

2. 配置 ZeroClaw

channel_access_token 🔑 secret · default ""

长期有效的频道访问令牌（来自 LINE Developers Console）。同时用于 Reply API 和 Push API 回退。如果为空，则回退到 LINE_CHANNEL_ACCESS_TOKEN 环境变量。

将它放置在任何表面上：

网关仪表板

打开 /config/channels/line 并设置 channels.line.<alias>.channel_access_token 字段。

zerocode

在 Config 窗格中，设置 channels.line.<alias>.channel_access_token 字段。

zeroclaw config

zeroclaw config set channels.line.<alias>.channel_access_token    # 掩码输入，加密存储

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_channels__line__<alias>__channel_access_token=

channel_secret 🔑 secret · default ""

Channel secret（来自 LINE Developers Console）。用于验证传入 webhook 上的 X-Line-Signature 标头。如果为空，则回退到 LINE_CHANNEL_SECRET 环境变量。

将它放置在任何表面上：

网关仪表板

打开 /config/channels/line 并设置 channels.line.<alias>.channel_secret 字段。

zerocode

在 Config 窗格中，设置 channels.line.<alias>.channel_secret 字段。

zeroclaw config

zeroclaw config set channels.line.<alias>.channel_secret    # 掩码输入，加密存储

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_channels__line__<alias>__channel_secret=

dm_policy LineDmPolicy · default "pairing"

DM（一对一聊天）访问策略。默认值：pairing。- open：对所有人响应 - pairing：首次联系时需要一次性的 /bind <code> 握手 - allowlist：仅对 allowed_users 中列出的用户 ID 响应

将它放置在任何表面上：

zeroclaw config set channels.line.<alias>.dm_policy <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_channels__line__<alias>__dm_policy=

excluded_tools string[] · default []

从此通道的工具规范中排除的工具。设置后，通过此通道响应时不会向模型公开这些工具。

将它放置在任何表面上：

zeroclaw config set channels.line.<alias>.excluded_tools <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_channels__line__<alias>__excluded_tools=

group_policy LineGroupPolicy · default "mention"

群组/多人聊天策略。默认值：mention。- open：响应每条消息 - mention：仅在被 @提及时响应 - disabled：忽略所有群组消息

将它放置在任何表面上：

zeroclaw config set channels.line.<alias>.group_policy <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_channels__line__<alias>__group_policy=

proxy_url string? · default null

每个通道的代理 URL（http、https、socks5、socks5h）。仅为此通道覆盖全局 [proxy] 设置。

将它放置在任何表面上：

zeroclaw config set channels.line.<alias>.proxy_url <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_channels__line__<alias>__proxy_url=

sender_name string? · default null

在 LINE 聊天气泡中显示为发送者的显示名称。未设置或为空时默认为 "AI"。

将它放置在任何表面上：

zeroclaw config set channels.line.<alias>.sender_name <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_channels__line__<alias>__sender_name=

webhook_port integer · default 8443

嵌入式 webhook 服务器监听的 TCP 端口。默认值：8443。

将它放置在任何表面上：

zeroclaw config set channels.line.<alias>.webhook_port <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_channels__line__<alias>__webhook_port=

在 [channels.line.<alias>] 下配置 LINE 频道，至少需提供 channel_access_token 和 channel_secret。关于 dm_policy / group_policy 面向用户的语义，详见下文 §6。

使用环境变量代替配置文件

如果您不希望将凭据存储在配置文件中，可以省略 token 字段，并将其作为环境变量导出：

sh

export LINE_CHANNEL_ACCESS_TOKEN="your-channel-access-token"
export LINE_CHANNEL_SECRET="your-channel-secret"

环境变量优先于空的配置字段。

3. 暴露 Webhook 端点

LINE 通过向您的 Webhook URL 发送消息来传递消息。嵌入式服务器在配置的 webhook_port 上监听。

用于本地开发（ngrok）：

sh

ngrok http 8443

复制 ngrok 提供的 https:// URL（例如 https://abc123.ngrok.io）。

用于生产环境： 在 HTTPS 反向代理（如 nginx、Caddy 等）后面暴露端口 8443（或你配置的端口），或者直接部署在带有 TLS 证书的服务器上。

4. 在 LINE Developers 控制台中注册 Webhook

前往您的频道 → Messaging API 选项卡 → Webhook 设置。
将 Webhook URL 设置为 https://your-domain.com/line/webhook。
启用 使用 Webhook 选项。
点击 Verify，LINE 将发送一个测试请求。ZeroClaw 必须处于运行状态，验证才能成功。

5. 启动 ZeroClaw

sh

zeroclaw daemon

启动日志信号：

LINE: webhook 服务器正在监听 http://0.0.0.0:8443/line/webhook—

6. 访问策略

私信（1:1 聊天）：`dm_policy`

值	行为
`pairing`（默认）	该机器人会忽略所有私信，直到用户发送 `/bind <code>`。配对码会在 ZeroClaw 启动时的日志中显示。
`open`	该机器人会立即回复每条私信。
`allowlist`	此机器人仅响应代理对等集合（peer set）中的 LINE 用户 ID（参见谁可以与代理对话）。

配对流程：

ZeroClaw 在启动时会在日志中打印一个配对码。
用户向机器人发送 LINE 私信并输入 /bind <code>。
ZeroClaw 确认配对；后续 DM 将被接受。

群组/多人聊天：`group_policy`

值	行为
`mention`（默认）	该机器人仅在被明确 @提及时才会响应。
`open`	该机器人会响应群组中的每条消息。
`disabled`	该机器人完全忽略所有群聊消息。

7. 音频/语音消息转录（可选）

启用转录功能后（通过全局 [transcription] 配置，参见配置参考），LINE 的 audio 消息事件会自动从 LINE Content API 下载并转录，然后再传递给模型。

最大接受的音频文件大小为 25 MB。较大的文件将被静默跳过，并记录警告日志。

8. 故障排除

症状	可能的原因	操作
LINE Verify 验证失败	ZeroClaw 未运行，或端口不可达	确认进程已启动，且端口可从互联网访问
机器人不回复私信	`dm_policy = pairing` 且用户尚未运行 `/bind`	用户必须先发送 `/bind <code>`，或者切换到 `dm_policy = open`。
机器人不在群组中回复	`group_policy = mention` 且消息中没有 @提及	@提及机器人，或切换至 `group_policy = open`
回复以推送消息的形式到达	回复令牌已过期（约 30 秒窗口）	预期的回退行为，无需采取任何操作
音频消息已忽略	未配置 `[transcription]`	添加 `[transcription]` 块，其中 `enabled = true`

日志关键词

条件	日志消息
启动健康	`LINE: webhook 服务器正在监听 http://0.0.0.0:<port>/line/webhook`
签名被拒绝	`LINE: 无效的 X-Line-Signature`
未授权的 DM	`LINE: 来自 <userId> 的 DM 被策略拒绝`
需要配对	`LINE: 未配对的用戶 <userId>；忽略直到 /bind`
音频被忽略（无转录）	`LINE: 音频消息已忽略（未配置转录）`
音频转录失败	`LINE: 转录失败，消息ID为 <messageId>：`

另见

配置参考：完整的配置字段索引
LINE 开发者文档

Keyboard shortcuts

ZeroClaw Docs