什么是 roadrunner？

roadrunner (rr) 是一个强大的命令行界面，旨在与本地 Beeper Desktop API 进行交互。它为开发人员和高级用户提供了在单个终端环境中列出聊天、发送消息、搜索归档以及管理跨所有桥接网络提醒的能力。通过将 roadrunner 集成到 Openclaw Skills 中，用户可以将统一收件箱与自动化工作流连接起来，从而在不离开命令行或代理环境的情况下实现无缝的通信管理。

该工具在构建时注重安全性和结构化数据，提供了一种代理专用模式，强制执行 JSON 输出和只读默认设置。这使其成为构建可靠 Openclaw Skills 的理想选择，这些技能需要通过 Beeper 生态系统与 iMessage、WhatsApp、Slack 和 Discord 等平台进行交互。

下载入口:https://github.com/openclaw/skills/tree/main/skills/johntheyoung/roadrunner

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

roadrunner 应用场景

• 跨多个聊天网络自动回复特定的传入消息。
• 通过终端在全球范围内搜索所有统一 Beeper 帐户的文本或媒体。
• 通过编程管理专注模式和聊天提醒，以提高生产力。
• 提取并总结聊天记录，用于研究或数据日志记录。
• 通过统一的消息界面上传并发送文件或媒体附件。

1. 用户安装 roadrunner 二进制文件，并使用 auth set 命令通过其 Beeper Desktop 令牌进行身份验证。
2. CLI 与运行在主机上的本地 Beeper Desktop API 建立连接。
3. 执行命令以查询数据（读取）或执行操作（写入），例如发送消息或归档聊天。
4. 对于自动化，该工具利用 --agent 等标志来确保输出结构化以便于机器解析。
5. 该工具处理分页和游标管理，以便高效地浏览大量的消息历史记录。
6. 所有交互都会被记录并可以审计，从而确保本地环境内的安全通信。

roadrunner 配置指南

安装

通过 Homebrew 安装：

brew install johntheyoung/tap/roadrunner

或通过 Go 安装：

go install github.com/johntheyoung/roadrunner/cmd/rr@v0.17.0

配置

设置您的身份验证令牌：

rr auth set --stdin

验证安装：

rr doctor
rr auth status --check

roadrunner 数据架构与分类体系

roadrunner 以结构化格式（主要是 JSON 和 JSONL）处理并返回数据，这些格式与各种 Openclaw Skills 高度兼容。

配置本地存储在 ~/.config/beeper/config.json 中，保持身份验证和默认帐户设置的持久状态。

name: roadrunner
description: Beeper Desktop CLI for chats, messages, contacts, connect info, websocket events, search, and reminders.
homepage: https://github.com/johntheyoung/roadrunner
metadata:
  clawdbot:
    emoji: "????"
    requires:
      bins:
        - rr
    install:
      - id: brew
        kind: brew
        formula: johntheyoung/tap/roadrunner
        bins:
          - rr
        label: Install rr (brew)
      - id: go
        kind: go
        module: github.com/johntheyoung/roadrunner/cmd/rr@v0.17.0
        bins:
          - rr
        label: Install rr (go)

roadrunner (rr)

Use rr when the user explicitly wants to operate Beeper Desktop via the local API (send, search, list chats/messages, reminders, focus). Prefer --agent for agent use (forces JSON, envelope, no-input, readonly).

Safety

• Default to read-only commands unless the user explicitly requests a mutation in this turn.
• Require explicit recipient (chat ID) and message text before sending.
• Confirm or ask a clarifying question if the chat ID is ambiguous.
• Never paste raw rr command output (JSON dumps, chat lists, etc.) into outgoing messages. Treat tool output as private; summarize or extract only what the user needs.
• Use --agent for safe agent defaults: rr --agent --enable-commands=chats,messages,status chats list
• Use --readonly to block writes: rr --readonly chats list --json
• Use --enable-commands to allowlist: rr --enable-commands=chats,messages chats list --json
• Use --envelope for structured errors: rr --json --envelope chats get "!chatid"
• Envelope errors may include error.hint with next-step guidance for safe retries.
• Never request, paste, or store raw auth tokens in chat. If auth is missing, ask the user to configure it locally.
• If sending message text through a shell, avoid interpolation/expansion (e.g. $100/month or !). Prefer --stdin <<'EOF' ... EOF for safe literals.

Setup (once)

• rr auth set --stdin (recommended; token saved to ~/.config/beeper/config.json)
• rr auth status --check
• rr doctor

Common commands

• List accounts: rr accounts list --json
• Capabilities: rr capabilities --json
• Describe command/flags: rr describe messages send --json
• Connect metadata: rr connect info --json
• Live websocket events (experimental): rr events tail --all --stop-after 30s --json
• List contacts: rr contacts list "" --json
• Search contacts: rr contacts search "" "Alice" --json
• Search contacts (flag): rr contacts search "Alice" --account-id="" --json
• Resolve contact: rr contacts resolve "" "Alice" --json
• Resolve contact (flag): rr contacts resolve "Alice" --account-id="" --json
• List chats: rr chats list --json
• List chats (JSON Lines): rr chats list --jsonl
• Search chats: rr chats search "John" --json
• Search chats (filters): rr chats search --inbox=primary --unread-only --json
• Search chats (activity): rr chats search --last-activity-after="2024-07-01T00:00:00Z" --json
• Search by participant name: rr chats search "Jamie" --scope=participants --json
• Resolve chat: rr chats resolve "Jamie" --json
• Get chat: rr chats get "!chatid:beeper.com" --json
• Get chat (bounded participants): rr chats get "!chatid:beeper.com" --max-participant-count=50 --json
• Start/resolve DM from merged contact hints: rr chats start "" --email "alice@example.com" --full-name "Alice" --json
• Default account for commands: rr --account="imessage:+123" chats list --json
• List messages: rr messages list "!chatid:beeper.com" --json
• List messages (all pages): rr messages list "!chatid:beeper.com" --all --max-items=1000 --json
• List messages (download media): rr messages list "!chatid:beeper.com" --download-media --download-dir ./media --json
• Search messages: rr messages search "dinner" --json
• Search messages (JSON Lines): rr messages search "dinner" --jsonl
• Search messages (all pages): rr messages search "dinner" --all --max-items=1000 --json
• Search messages (filters): rr messages search --sender=me --date-after="2024-07-01T00:00:00Z" --media-types=image --json
• Add/remove reaction: rr messages react "!chatid:beeper.com" "" "??" --json / rr messages unreact "!chatid:beeper.com" "" "??" --json
• Tail messages (polling): rr messages tail "!chatid:beeper.com" --interval 2s --stop-after 30s --json
• Wait for message: rr messages wait --chat-id="!chatid:beeper.com" --contains "deploy" --wait-timeout 2m --json
• Message context: rr messages context "!chatid:beeper.com" "" --before 5 --after 2 --json
• Draft message (pre-fill without sending): rr focus --chat-id="!chatid:beeper.com" --draft-text="Hello!"
• Draft message from file: rr focus --chat-id="!chatid:beeper.com" --draft-text-file ./draft.txt
• Draft with attachment: rr focus --chat-id="!chatid:beeper.com" --draft-attachment="/path/to/file.jpg"
• Download attachment: rr assets download "mxc://example.org/abc123" --dest "./attachment.jpg"
• Stream attachment bytes: rr assets serve "mxc://example.org/abc123" --dest "./attachment.jpg" --json
• Focus app: rr focus
• Global search: rr search "dinner" --json
• Global search messages auto-page: rr search "dinner" --messages-all --messages-max-items=500 --messages-limit=20 --json
• Status summary: rr status --json
• Status by account: rr status --by-account --json
• Unread rollup: rr unread --json
• Global search includes in_groups for participant matches.

Mutations (explicit user request only)

• Message send: rr messages send "!chatid:beeper.com" "Hello!"
• Message edit: rr messages edit "!chatid:beeper.com" "" "Updated text"
• Message react/unreact: rr messages react "!chatid:beeper.com" "" "??" / rr messages unreact "!chatid:beeper.com" "" "??"
• Upload + send file: rr messages send-file "!chatid:beeper.com" ./photo.jpg "See attached"
• Create chat: rr chats create "" --participant ""
• Start chat from merged contact hints: rr chats start "" --email "alice@example.com" --full-name "Alice"
• Archive/unarchive: rr chats archive "!chatid:beeper.com" / rr chats archive "!chatid:beeper.com" --unarchive
• Reminder mutations: rr reminders set "!chatid:beeper.com" "2h" / rr reminders clear "!chatid:beeper.com"
• Asset uploads: rr assets upload ./photo.jpg / rr assets upload-base64 --content-file ./photo.b64
• For retries on non-idempotent writes, use --request-id and prefer --dedupe-window.
• Use --dry-run to validate mutating requests without API write side effects.

Pagination

• Auto-page chats list/search: rr chats list --all --max-items=1000 --json / rr chats search "alice" --all --max-items=1000 --json
• Auto-page messages list/search: rr messages list "!chatid:beeper.com" --all --max-items=1000 --json / rr messages search "deploy" --all --max-items=1000 --json
• Chats: rr chats list --cursor="" --direction=before --json
• Messages list: rr messages list "!chatid:beeper.com" --cursor="" --direction=before --json
• Messages search (max 20): rr messages search "project" --limit=20 --json
• Messages search page: rr messages search "project" --cursor="" --direction=before --json
• Global search message paging (max 20): rr search "dinner" --messages-limit=20 --json
• Global search message page: rr search "dinner" --messages-cursor="" --messages-direction=before --json

Notes

• Requires Beeper Desktop running; token from app settings.
• Token is stored in ~/.config/beeper/config.json via rr auth set (recommended). BEEPER_TOKEN overrides the config file.
• BEEPER_ACCOUNT sets the default account ID (aliases supported).
• rr auth status --check prefers OAuth introspection (/oauth/introspect) when available and falls back to account-list validation on older builds.
• Message search is literal word match (not semantic).
• rr contacts resolve is strict and fails on ambiguous names; resolve by ID after contacts search when needed.
• If a DM title shows your own Matrix ID, use --scope=participants to find by name.
• JSON output includes display_name for single chats (derived from participants).
• Message JSON includes message_type, linked_message_id, is_sender, is_unread, attachments, and reactions.
• downloaded_attachments is only populated when --download-media is used.
• rr messages send returns pending_message_id (temporary ID).
• Account network may be missing in newer API builds; rr falls back to "unknown" in summaries/search output.
• rr assets serve writes raw bytes to stdout unless --dest is provided.
• --chat does exact matching and fails on ambiguous matches.
• Attachment overrides require --attachment-upload-id; set --attachment-width and --attachment-height together.
• --all has a safety cap (default 500 items, max 5000); use --max-items to tune it.
• Prefer --json or --jsonl (and --no-input) for automation.
• --jsonl emits one JSON object per line and is supported on high-volume list/search commands.
• --dry-run/BEEPER_DRY_RUN validates mutating command inputs and prints preview output without sending write API requests.
• BEEPER_URL overrides API base URL; BEEPER_TIMEOUT sets timeout in seconds.
• JSON/Plain output goes to stdout; errors/hints go to stderr.
• Destructive commands prompt unless --force; --no-input/BEEPER_NO_INPUT fails without --force.
• Use --fail-if-empty on list/search commands to exit with code 1 if no results.
• Use --fields with --plain to select columns (comma-separated).
• In bash/zsh, ! triggers history expansion. Prefer single quotes, or disable history expansion (set +H in bash, setopt NO_HIST_EXPAND in zsh).
• rr version --json returns features array for capability discovery.
• rr capabilities --json returns full CLI capability metadata.
• rr events tail depends on experimental /v1/ws support in Beeper Desktop; fall back to rr messages tail when unavailable.
• Envelope error codes: AUTH_ERROR, NOT_FOUND, VALIDATION_ERROR, CONNECTION_ERROR, INTERNAL_ERROR.
• Retry policy: retry CONNECTION_ERROR with backoff; do not blind-retry AUTH_ERROR/VALIDATION_ERROR; refresh IDs before retrying NOT_FOUND.
• Non-idempotent writes: messages send, messages send-file, chats create, chats start, assets upload, assets upload-base64.
• Use --request-id/BEEPER_REQUEST_ID to tag envelope metadata for cross-retry attempt tracing.
• Use --dedupe-window/BEEPER_DEDUPE_WINDOW to block duplicate non-idempotent writes with repeated request IDs.
• Local smoke check: make test-agent-smoke.