beeper-api-cli

面向大语言模型（LLM）优化的 Beeper CLI 封装工具，支持跨所有已连接聊天网络读取与发送消息。

⚠️ 重要警告：消息发送策略

🚨 未经用户明确授权，绝对禁止发送任何消息 🚨

所有消息操作必须严格遵守以下强制协议：

1. 必须首先完整展示待发消息草稿 —— 显示全部内容
2. 必须等待用户明确的口头确认 —— 如“发送它”、“看起来没问题”、“可以发了”等
3. 绝不可默认获得发送权限 —— 即使用户仅说“帮我起草一条消息”，也不代表授权发送
4. 适用于全部平台：WhatsApp、Telegram、Signal、Instagram、Twitter、Facebook、LinkedIn 等
5. 绝不例外 —— 此规则适用于新消息、回复及转发等所有类型的消息操作

该规则为不可协商、不可绕过，且适用于所有 beeper send 命令。

快速开始

步骤 1：从 Beeper Desktop 获取 Token

1. 启动 Beeper Desktop
2. 设置 → 高级 → API
3. 启用 API 访问
4. 复制 Bearer token

步骤 2：设置环境变量

# 必需：设置您的 token
export BEEPER_TOKEN="paste-your-token-here"

# 可选：覆盖默认 localhost 地址
export BEEPER_API_URL="http://[::1]:23373"  # 默认值

步骤 3：使用 CLI

# 推荐使用技能封装脚本（skill wrapper）
~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json

# 或直接调用二进制文件
/Users/ashrafali/clawd/beeper-api-cli/beeper chats list --output json

⚠️ 重要提示：若未设置 BEEPER_TOKEN，所有命令均将返回 “Unauthorized” 错误。

前提条件

1. Beeper Desktop 必须处于运行状态

CLI 通过本地 API 服务与 Beeper Desktop 连接。

2. 在 Beeper Desktop 中启用 API 访问

⚠️ 必需：您必须先在 Beeper Desktop 中完成 API Token 配置！

1. 启动 Beeper Desktop
2. 进入 设置 → 高级 → API
3. 启用 API 访问
4. 生成并复制 Bearer token
5. （可选）配置允许访问的 IP 地址
   • 默认仅允许 localhost（即 127.0.0.1 / ::1）
   • 若 CLI 运行于远程机器，请在 Beeper 设置中添加该机器的 IP 地址

3. 设置环境变量

必须提前设置 token，CLI 才能正常工作：

# 必需：使用 Beeper Desktop 中获取的 token
export BEEPER_TOKEN="your-token-from-beeper-settings"

# 可选：覆盖 API URL（默认为 http://[::1]:23373）
export BEEPER_API_URL="http://[::1]:23373"

如何获取 token：

• Beeper Desktop → 设置 → 高级 → API → 复制 Bearer Token

重要提示：

• ❌ 若未设置 BEEPER_TOKEN，CLI 将无法工作
• ⚠️ 默认 API URL 为 localhost（http://[::1]:23373）
• 🔒 若从其他机器访问，您必须：
  1. 在 Beeper Desktop 的 API 设置中添加该机器的 IP 地址
  2. 更新 BEEPER_API_URL，使其指向正确的主机 IP

命令列表

列出全部聊天会话

# JSON 输出（面向 LLM 优化）
~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json

# 人类可读文本格式
~/clawd/skills/beeper-api-cli/beeper.sh chats list --output text

# Markdown 格式
~/clawd/skills/beeper-api-cli/beeper.sh chats list --output markdown

JSON 输出示例：

[
  {
    "id": "!wcn4YMCOtKUEtxYXYAq1:beeper.local",
    "title": "beeper-api-cli - Lion Bot",
    "type": "group",
    "network": "Telegram",
    "unreadCount": 15
  }
]

获取指定聊天会话详情

~/clawd/skills/beeper-api-cli/beeper.sh chats get  --output json

列出某聊天会话中的消息

# 获取最近 50 条消息（默认数量）
~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id 

# 指定获取消息数量
~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id  --limit 20 --output json

JSON 输出示例：

[
  {
    "id": "42113",
    "chatID": "!wcn4YMCOtKUEtxYXYAq1:beeper.local",
    "senderName": "ClawdBot",
    "text": "Hello world!",
    "timestamp": "2026-01-19T22:17:38.000Z",
    "isSender": true
  }
]

发送消息

# ⚠️ 必须事先获得用户授权 —— 详见上方「消息发送策略」
~/clawd/skills/beeper-api-cli/beeper.sh send --chat-id  --message "Your message here"

输出示例：

{
  "success": true,
  "message_id": "msg_123",
  "chat_id": "!wcn4YMCOtKUEtxYXYAq1:beeper.local"
}

搜索消息

# 在全部聊天会话中全局搜索
~/clawd/skills/beeper-api-cli/beeper.sh search --query "keyword" --limit 10 --output json

自动发现 API URL

~/clawd/skills/beeper-api-cli/beeper.sh discover

LLM 工作流示例

查找聊天会话并发送消息

# 1. 列出所有会话以定位目标
CHATS=$(~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json)

# 2. 提取 chat ID（使用 jq）
CHAT_ID=$(echo "$CHATS" | jq -r '.[] | select(.title | contains("Project")) | .id')

# 3. 发送消息
~/clawd/skills/beeper-api-cli/beeper.sh send --chat-id "$CHAT_ID" --message "Update ready!"

获取对话上下文

# 获取最近若干条消息用于上下文构建
~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id  --limit 20 --output json | jq

监控未读消息

# 获取所有含未读消息的会话
~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json | jq '.[] | select(.unreadCount > 0) | {title, network, unread: .unreadCount}'

输出格式

JSON（默认格式 —— 面向 LLM 优化）

• 结构化数据，便于程序解析
• 专为自动化流程设计
• 可直接通过管道传入 jq 进行过滤与处理

Text（人类可读格式）

ID: !wcn4YMCOtKUEtxYXYAq1:beeper.local
Title: beeper-api-cli - Lion Bot
Type: group
Network: Telegram
Unread: 15

Markdown（文档友好格式）

## beeper-api-cli - Lion Bot

- **ID**: !wcn4YMCOtKUEtxYXYAq1:beeper.local
- **Type**: group
- **Network**: Telegram
- **Unread**: 15

Chat ID 格式说明

不同网络采用不同的 ID 格式：

• Telegram: !wcn4YMCOtKUEtxYXYAq1:beeper.local
• WhatsApp: 电话号码格式（例如 15551234567@s.whatsapp.net）
• Signal: 电话号码（例如 +15551234567）
• Instagram/Twitter: 平台专属 ID

请使用 chats list 命令查询您当前会话所使用的精确 ID 格式。

环境变量

必需配置项

使用 CLI 前，您必须设置以下环境变量：

BEEPER_TOKEN（必需）

export BEEPER_TOKEN="your-bearer-token-from-beeper-desktop"

如何获取您的 token：

1. 启动 Beeper Desktop
2. 设置 → 高级 → API
3. 启用 API 访问
4. 复制设置页面中显示的 Bearer token
5. 将其设为环境变量

缺少此 token，CLI 将一律返回 “Unauthorized” 错误。

BEEPER_API_URL（可选）

export BEEPER_API_URL="http://[::1]:23373"  # 默认值

默认行为：

• 使用 http://[::1]:23373（IPv6 下的 localhost）
• 当 CLI 与 Beeper Desktop 运行在同一台机器上时有效

何时需要修改：

• CLI 运行于 远程机器 上
• Beeper Desktop 运行于另一台主机
• 使用了自定义端口

远程访问场景下操作步骤：

1. 查出运行 Beeper Desktop 的机器 IP 地址
2. 在 Beeper Desktop → 设置 → 高级 → API → 将远程机器 IP 添加至“允许访问的 IP 列表”
3. 将 BEEPER_API_URL 设为：http://:23373

远程访问示例：

export BEEPER_API_URL="http://192.168.1.100:23373"
export BEEPER_TOKEN="your-token-here"

技能封装脚本（Skill Wrapper）行为说明

技能封装脚本（beeper.sh）具备以下行为：

• ✅ 自动读取环境变量 $BEEPER_TOKEN（您必须自行设置！）
• ✅ 若未设置 $BEEPER_API_URL，则默认使用 http://[::1]:23373
• ❌ 若 BEEPER_TOKEN 未设置，则报错退出

故障排查

“Connection refused”（连接被拒绝）

# 检查 Beeper Desktop 是否正在运行
ps aux | grep -i beeper

# 启动 Beeper Desktop（macOS 示例）
open -a "Beeper Desktop"

“Unauthorized” 或 “Invalid or missing token”（未授权 / Token 无效或缺失）

这表示您尚未设置 BEEPER_TOKEN，或其值不正确。

修复方法：

# 1. 检查 token 是否已设置
echo $BEEPER_TOKEN

# 若为空或错误，请从 Beeper Desktop 重新获取：
# - 启动 Beeper Desktop
# - 设置 → 高级 → API
# - 若尚未启用 API，请先启用
# - 复制设置中显示的 Bearer token
# - 在环境中设置：

export BEEPER_TOKEN="paste-the-token-here"

# 测试是否生效：
~/clawd/skills/beeper-api-cli/beeper.sh chats list

重要说明：

• Token 在 Beeper Desktop 设置中生成，而非本 CLI 中生成
• 您必须完全准确地复制设置 → 高级 → API 页面中的 token
• 无有效 token 时，所有命令均无法执行
• Token 不会自动过期，除非您在 Beeper 设置中主动重新生成

“Chat not found”（未找到聊天会话）

# 列出全部会话以查找正确 ID
~/clawd/skills/beeper-api-cli/beeper.sh chats list --output text | grep -i "search-term"

远程访问（CLI 与 Beeper Desktop 运行于不同机器）

若您希望在另一台计算机上运行 CLI：

1. 配置 Beeper Desktop 允许远程访问：

- 启动 Beeper Desktop（运行 Beeper 的机器）
- 设置 → 高级 → API
- 找到“允许访问的 IP 地址”区域
- 添加运行 CLI 的机器 IP 地址
- 示例：192.168.1.50

2. 设置 BEEPER_API_URL 指向远程机器：

# 在运行 CLI 的机器上执行：
export BEEPER_API_URL="http://:23373"
export BEEPER_TOKEN="your-token"

# 示例：
export BEEPER_API_URL="http://192.168.1.100:23373"

默认行为（仅限 localhost）：

• 默认 URL：http://[::1]:23373（IPv6 localhost）
• 仅当 CLI 与 Beeper Desktop 运行于同一台机器时可用
• 不支持远程访问，除非您在 Beeper 设置中显式配置允许的 IP 列表

使用示例

示例 1：检查未读消息

#!/bin/bash
BEEPER="$HOME/clawd/skills/beeper-api-cli/beeper.sh"

# 获取含未读消息的会话
$BEEPER chats list --output json | 
  jq -r '.[] | select(.unreadCount > 0) | "(.title) ((.network)): (.unreadCount) unread"'

示例 2：读取近期消息

#!/bin/bash
BEEPER="$HOME/clawd/skills/beeper-api-cli/beeper.sh"
CHAT_ID="!wcn4YMCOtKUEtxYXYAq1:beeper.local"

# 以可读格式获取最后 10 条消息
$BEEPER messages list --chat-id "$CHAT_ID" --limit 10 --output text

示例 3：搜索并响应

#!/bin/bash
BEEPER="$HOME/clawd/skills/beeper-api-cli/beeper.sh"

# 搜索提及内容
RESULTS=$($BEEPER search --query "@clawdbot" --limit 5 --output json)

# 处理结果并响应（LLM 集成接入点）
echo "$RESULTS" | jq

与 Clawdbot 集成

当通过 Clawdbot 工具调用时，环境变量已预先配置完毕：

# 直接通过 exec 工具调用
~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json

技能封装脚本具备以下能力：

• ✅ 自动配置 BEEPER_API_URL 和 BEEPER_TOKEN
• ✅ 对必需环境变量进行完整性校验
• ✅ 清晰透传全部 CLI 参数

二进制文件位置

• 技能封装脚本: ~/clawd/skills/beeper-api-cli/beeper.sh
• Beeper CLI 二进制文件: /Users/ashrafali/clawd/beeper-api-cli/beeper
• 源代码: https://github.com/nerveband/beeper-api-cli

功能特性

✅ 支持只读与写入操作（区别于其他同类工具）
✅ 面向 LLM 优化的 JSON 输出
✅ 支持人类可读的文本与 Markdown 格式
✅ 自动发现 Beeper Desktop API 地址
✅ 跨平台二进制（macOS、Linux、Windows）
✅ 基于环境变量的灵活配置
✅ 完整详尽的错误提示
✅ 兼容 Unix 管道操作

注意事项

• 该技能依赖 Beeper Desktop 处于运行状态
• 必须在 Beeper Desktop 设置中启用 API 访问
• Token 已预存于 Clawdbot 配置中（已自动配置）
• 所有已接入 Beeper 的网络（WhatsApp、Telegram、Signal 等）均可访问
• LLM 处理推荐使用 JSON 输出；人工阅读推荐使用 text 格式

版本信息

最新版（基于源码构建的开发版）