Execution context

You are running on a Linux host with BlueZ + ofono installed and a phone paired over Bluetooth. The skill ships:

• Low-level primitives at skill/bin/bt-*.py — BlueZ/ofono/ADB direct interfaces
• High-level wrappers at skill/wrappers/paired-*.py — JSON-clean interfaces designed for agents to call
• Systemd unit files at skill/systemd/*.service.txt — for persistent listeners (SMS push, call watch, command hook). The .txt suffix is a packaging convention; rename to .service when copying into ~/.config/systemd/user/ (see Installation below).

Installation

After clawhub install paired:

# 1. Symlink (or copy) the bin/ and wrappers/ scripts into ~/bin/, dropping .py from filenames
#    so the user/agent can invoke `paired-sms-send` rather than `paired-sms-send.py`.
mkdir -p ~/bin
for f in ~/.openclaw/workspace/skills/paired/bin/*.py; do
  ln -sf "$f" ~/bin/"$(basename "$f" .py)"
done
for f in ~/.openclaw/workspace/skills/paired/wrappers/*.py; do
  ln -sf "$f" ~/bin/"$(basename "$f" .py)"
done
for f in ~/.openclaw/workspace/skills/paired/wrappers/*.sh; do
  ln -sf "$f" ~/bin/"$(basename "$f" .sh)"
done
chmod +x ~/.openclaw/workspace/skills/paired/bin/*.py \
         ~/.openclaw/workspace/skills/paired/wrappers/*.py \
         ~/.openclaw/workspace/skills/paired/wrappers/*.sh

# 2. Optional: enable systemd user services. Strip the .txt suffix on copy.
mkdir -p ~/.config/systemd/user
for f in ~/.openclaw/workspace/skills/paired/systemd/*.service.txt; do
  cp "$f" ~/.config/systemd/user/"$(basename "$f" .txt)"
done
systemctl --user daemon-reload

# 3. One-time inbox HMAC key generation (required for paired-inbox-hook)
paired-inbox-hook --keygen

# 4. Optional: enable the inbox hook (HMAC-signed command dispatcher)
systemctl --user enable --now paired-inbox-hook.service

The .py, .sh, and .service.txt extensions exist to satisfy the ClawHub packaging text-file allowlist; on disk in your ~/bin/ and ~/.config/systemd/user/ they should be the unsuffixed names referenced throughout this document.

When reasoning about a phone task, prefer the high-level paired-* wrappers — they handle trust checks, error formatting, and JSON output. Drop to bt-* only for diagnostic or low-level work. The low-level bt-call and bt-sms primitives now also enforce the trusted-numbers allowlist (since v1.0.4) and refuse to dial/SMS unlisted numbers unless --confirm is passed.

Acting on the world vs. answering questions: for status queries ("is my phone connected?", "any new SMS?"), running the tool and reporting the result is the right call. For high-impact actions (sending SMS, dialling calls, pairing new devices, unlocking the phone), confirm with the user first unless the request is unambiguous and the destination is on the trusted-numbers allowlist.

Phone identity comes from ~/.config/paired/paired.conf, key phone_bt_mac. If a command needs the phone's MAC, read it from the config rather than asking the user. If the config is missing, tell the user to copy paired.conf.example and fill in the MAC.

Most-used commands

Stack health and discovery

~/bin/bt-test                              # 10-check stack health (one-shot diagnostic)
~/bin/bt-adapters                          # list HCI adapters
~/bin/bt-list --paired                     # paired devices with CONN/PAIR/TRUST status
~/bin/bt-list --connected                  # only currently-connected
~/bin/bt-list --scan 10                    # 10-second scan for nearby
~/bin/bt-info <MAC>                        # full device detail (UUIDs, RSSI, profiles)
~/bin/bt-recover                           # USB-reset adapter if hung

Pairing and connection

~/bin/bt-pair <MAC>                        # initiate pairing (passkey via bt-agent)
~/bin/bt-pair <MAC> --connect              # pair + trust + connect in one step
~/bin/bt-connect <MAC>                     # connect to an already-paired device
~/bin/bt-disconnect <MAC>
~/bin/bt-trust <MAC> | ~/bin/bt-untrust <MAC>
~/bin/bt-forget <MAC>                      # remove pairing entirely

Phone — SMS

Receive (read-only via Bluetooth, fully working on most phones):

~/bin/paired-sms-watch --status            # is the MNS push daemon running?
~/bin/paired-sms-watch --last 10           # last 10 SMS the daemon caught
~/bin/bt-sms-list --map <MAC> --max 10     # explicit MAP read of recent
~/bin/bt-adb-sms-list --limit 10           # ADB read of inbox (works while phone is locked)
~/bin/bt-adb-sms-list --sent --limit 10    # sent folder

Send (via ADB-over-USB autosend — Bluetooth MAP send is blocked on most Samsung firmware):

~/bin/paired-sms-send <NUMBER> "<text>" --json
# Pass --auto-unlock to dismiss the lock screen using the PIN at
# ~/.config/paired/pin (mode 0600 enforced). Pass --relock to re-lock after.
# Without --auto-unlock, the tool returns error=keyguard_locked when phone is locked.

Telegram command shortcut: when the user types /sms NUMBER text in Telegram, run ~/bin/paired-sms-send NUMBER "text" --json and report the JSON result. Quote the entire body as one argument.

Phone — calls (HFP via ofono)

~/bin/paired-call status --json            # active calls in structured form
~/bin/paired-call dial <NUMBER>            # initiate outbound
~/bin/paired-call answer                   # accept incoming
~/bin/paired-call hangup                   # end all calls
~/bin/paired-call-and-speak <NUMBER> "<msg>" # dial + speak via Tasker TTS (see limits)
~/bin/bt-modems --full                     # ofono modem state, network registration
~/bin/paired-call-watch --last 10          # last 10 incoming calls caught by daemon
~/bin/paired-call-watch --status           # is the call watcher daemon running?

Real-time incoming-call alerts run as a systemd user service (paired-call-watch.service) — caught calls go to the user's Telegram via paired-call-watch-tg-hook with sender + trust-status info.

Phone — Telegram command vocabulary (deterministic, bypasses LLM)

paired-sms-command-hook.service reads commands from a dedicated, append-only inbox at ~/.openclaw/paired/inbox/ (NOT from raw agent session logs — see Security model below) and dispatches recognised commands without invoking the LLM:

Trusted list at ~/.config/paired/trusted-numbers.conf — managed via ~/bin/paired-trusted add | remove | list. UK number normalization: +44, 0044, 44, and 07 formats all match the same entry. An empty trusted-numbers file blocks all outgoing SMS and calls except for explicit --confirm invocations. This is the safe default — fill the file in deliberately.

SMS fallback for /phone <num> <msg>: TTS during calls is blocked on some phone firmware (notably Samsung — see "Known phone-side limits" below). When TTS-during-call fails, the wrapper can also send an SMS with the same body so the recipient still gets the message. This is opt-in per invocation — pass --with-sms-fallback to enable it. Without that flag, a TTS failure returns an error and the wrapper does not send any SMS. The Telegram reply notes the chosen behaviour explicitly: "📞 TTS only" or "📞 TTS + 📨 SMS fallback (best-effort)".

Security model (read this before enabling persistent services)

This skill runs persistent systemd services that can dispatch phone actions automatically:

• paired-sms-watch.service — listens for incoming SMS (via Bluetooth MAP-MNS), forwards alerts to Telegram. Read-only with respect to the phone.
• paired-call-watch.service — listens for incoming calls (via ofono D-Bus), forwards alerts to Telegram. Read-only.
• paired-sms-command-hook.service — reads command messages from ~/.openclaw/paired/inbox/, dispatches recognised commands. This is the surface that can act. It accepts commands ONLY from a directory the user controls, with a per-message HMAC signature using a secret in ~/.config/paired/inbox.key (mode 0600). Commands from any other source — raw session logs, the agent's chat memory, an SMS body, etc. — are NOT dispatched.

Why the inbox model: earlier versions of this skill parsed the agent's session JSONL log directly. That made the session log a control surface — anything that landed in it (including unfiltered text from incoming SMS/calls) was a potential command source. The inbox model isolates the dispatch surface to messages the user (or a trusted bot relay) explicitly drops into the inbox dir, signed with the inbox key.

To stop all persistent services in one go:

systemctl --user stop paired-sms-watch paired-call-watch paired-sms-command-hook
systemctl --user disable paired-sms-watch paired-call-watch paired-sms-command-hook

Phone — contacts (PBAP)

~/bin/bt-contacts <MAC> --max 10           # list 10 contacts
~/bin/bt-contacts <MAC> --pull             # pull entire phonebook to ~/Downloads/bluetooth/<mac>.vcf
~/bin/bt-contacts <MAC> --search "name"    # search by name

Phone — media (AVRCP via BT, fallback to ADB)

~/bin/paired-media status --json           # current track + status (auto BT/ADB transport)
~/bin/paired-media play | pause | next | prev | stop
~/bin/paired-media volume 50               # set BT volume 0-100
~/bin/paired-media current                 # what's playing right now

Auto-detects connected phone, picks BT/AVRCP first then falls back to ADB media controller.

File transfer (OBEX)

~/bin/bt-send <FILE> <MAC>                 # push file to phone
~/bin/bt-receive                           # listen for incoming pushes (saves to ~/Downloads/bluetooth/)
~/bin/bt-browse <MAC>                      # OBEX-FTP browse (vendor-dependent)

Network (PAN)

~/bin/bt-pan up <MAC>                      # connect as NAP client (phone-side BT-tethering must be ON)
~/bin/bt-pan down                          # disconnect
~/bin/bt-pan status                        # show bnep0 state

GATT / BLE

~/bin/bt-gatt-tree <MAC>                   # enumerate services + characteristics
~/bin/bt-gatt-read <MAC> <UUID>            # read a characteristic
~/bin/bt-gatt-write <MAC> <UUID> <HEX>     # write a characteristic

Audio

~/bin/bt-audio <MAC> --info                # available profiles
~/bin/bt-volume <MAC>                      # current volume
~/bin/bt-play <FILE> <MAC>                 # play file through BT speaker

LLM-drafted SMS reply (showcase feature, opt-in)

When an SMS arrives whose body starts with the phrase set in paired.conf[llm_trigger] (default: "Hi Agent,") and the sender is on the paired.conf[llm_trigger_whitelist], paired-respond will:

1. Strip the trigger prefix
2. Call the configured LLM (Gemini / OpenAI / local) with a tight system prompt
3. Post a richer Telegram alert containing sender, original question, drafted reply, and a tap-to-copy /sms command

The user decides whether to send the draft by tapping the /sms line. No automatic SMS reply. Empty whitelist disables the feature. Logs at ~/.paired/sms-respond.log.

Common phrasings → tool mapping

• "Stack health?" → ~/bin/bt-test
• "What's paired?" / "What devices?" → ~/bin/bt-list --paired
• "Is my phone connected?" → ~/bin/bt-list --connected | grep -i <phone-label>
• "Pair with X" → ~/bin/bt-pair X --connect
• "Network signal?" → ~/bin/bt-modems --full
• "Any new SMS?" / "Watch SMS" → ~/bin/paired-sms-watch --last 5
• "Is SMS watcher running?" → ~/bin/paired-sms-watch --status
• /sms NUMBER text → ~/bin/paired-sms-send NUMBER "text" --json
• "Reply to that SMS with X" → user provides text; you call paired-sms-send LAST_SENDER "X" --json. Get LAST_SENDER from the most recent ~/.paired/sms-events.jsonl entry.
• "Call NUMBER" → ~/bin/paired-call dial NUMBER --json
• "Hang up" → ~/bin/paired-call hangup --json
• "Pause music" / "play music" / "next song" → ~/bin/paired-media pause/play/next
• "What's playing?" → ~/bin/paired-media current

Known phone-side limits (clean errors, not bugs)

These are phone-firmware constraints, not skill bugs. The tools return clean errors and the docs explain workarounds.

Samsung firmware (Note 8/9/10/20, S-series tested through OneUI 12)

• SMS-send via Bluetooth (HFP / MAP) is blocked. Samsung firmware does not implement MAP UpdateInbox and ofono SMS-send returns access-denied. Workaround: use paired-sms-send (ADB-over-USB autosend) — fully working.
• In-call TTS is blocked at the audio policy level. Samsung Telecom holds AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE | AUDIOFOCUS_FLAG_LOCK for the entire ring+call lifecycle. No third-party app (Tasker included) can inject audio into the call audio path. The paired-call-and-speak tool runs but the recipient hears silence — SMS fail-soft compensates (the message body is also sent as SMS, recipient guaranteed to receive). On non-Samsung devices (Pixel/AOSP, LineageOS, rooted) this is expected to work normally.
• OBEX-FTP browse not advertised. Use bt-send to push files instead.

ofono + PipeWire (Debian 13, Ubuntu 24.04)

• Two-way SCO audio in calls is blocked. ofono 2.16 + PipeWire 1.4.x + libspa-bluetooth 1.4.x do not cooperate for HFP audio routing on current Debian. Outgoing calls work — the audio just routes through the phone earpiece, not the host's speaker/mic. Tested on both BCM43142 BT 4.0 and RTL8761B BT 5.1 adapters. paired-sco-agent is shipped as experimental — see docs/ARCHITECTURE.md.
• A2DP source profile (phone music → host speaker) is blocked by the same conflict. Receive (host as sink) works; source does not.

General

• The "Hi Agent," LLM trigger is opt-in via paired.conf and bound to a whitelist. Default config has the whitelist empty, which keeps the feature off until the user explicitly trusts a number.
• Auto-unlock is opt-in only. Storing a phone PIN on the host is a security trade — see paired.conf.example for the warning.

Architecture notes

• ofono owns HFP. PipeWire bluez monitor loaded but A2DP-source profile blocked by ofono/PipeWire HFP backend conflict — known trade-off, documented in docs/ARCHITECTURE.md.
• bt-agent.service runs as a system service to handle pairing PIN/passkey requests.
• The paired-* wrappers are the agent-facing interface; the underlying bt-* tools are CLI primitives that wrap BlueZ D-Bus and ofono D-Bus directly. Wrappers add JSON output, trust gating, fail-soft behaviour, and Telegram integration.

Hardware compatibility

See docs/HARDWARE-COMPATIBILITY.md for the full matrix. Tested combinations:

Setup checklist (for first-time users)

1. Pair your phone:

   ~/bin/bt-list --scan 10                # find your phone in the scan output
   ~/bin/bt-pair <MAC> --connect          # pair, trust, connect
   

2. Write your config:

   cp config-templates/paired.conf.example ~/.config/paired/paired.conf
   $EDITOR ~/.config/paired/paired.conf   # set phone_bt_mac, adapter, etc.
   

3. Set up the trusted-numbers list (optional, recommended):

   cp config-templates/trusted-numbers.conf.example ~/.config/paired/trusted-numbers.conf
   ~/bin/paired-trusted add 07911123456 "main mobile"
   ~/bin/paired-trusted list
   

4. Enable the systemd user services you want:

   systemctl --user enable --now paired-sms-watch.service       # real-time SMS push
   systemctl --user enable --now paired-call-watch.service      # incoming call alerts
   systemctl --user enable --now paired-sms-command-hook.service # /sms /phone Telegram commands
   

5. Verify:

   ~/bin/bt-test                          # 10-check stack health
   

If everything's green, the agent is ready to use the skill.