ClawCall — Phone Calls for Your Agent

ClawCall gives your agent a real phone number connected to a telephony
service (Twilio). Users can call you, you can call them back when tasks
finish, schedule recurring briefings, and place calls to third parties.

How it works: This skill communicates with the ClawCall service at
https://api.clawcall.online. All connections are outbound from your
machine, so no public URL or inbound webhook is required.

Operating rules

• - Prefer the local HTTP bridge for real-time phone calls.
• Treat direct CLI mode as fallback or debugging only.
• Keep exactly one bridge and one listener running at a time.
• Verify the bridge before testing calls.
• If calls keep hitting old behavior, kill stale node processes for

bridge/phone-agent-server.js and listener/clawcall-listener.js, then restart cleanly.

• - For simple phone intents, prefer direct handlers over slow general

model calls.

See references/setup.md for the full runtime and troubleshooting guide.

---

First-Time Setup

If CLAWCALL_API_KEY is not yet set, guide the user through registration:

1. 1. Explain what you're about to do:

> "To give you a phone number, I need to register with ClawCall — > a telephony service that connects your phone to this agent. > ClawCall will store your phone number to route incoming calls to you. > You can delete your account at any time."

1. 2. Ask for their phone number:

> "What phone number should I register? This is the number you'll > call me from. (E.164 format, e.g. +14155550100)"

1. 3. Call the registration endpoint:

CODEBLOCK0

1. 4. Store the returned api_key as CLAWCALL_API_KEY and the returned

email as CLAWCALL_EMAIL. Both are needed for account recovery.

1. 5. Confirm setup with the user:

> "Done! Your ClawCall number is {phone_number}. > Call it from {their phone} to talk to me. > (Free tier: calls must come from your registered number.)"

1. 6. Start the phone bridge and listener:

For production, prefer the lightweight HTTP bridge instead of the
full openclaw agent CLI path. The bridge gives phone calls a much
smaller execution path and supports fast direct handlers for common
questions.

Startup order matters:
1. Start the bridge.
2. Verify GET /health works.
3. Start the listener with CLAWCALL_AGENT_URL set.
4. Make one short test call.

Windows
CODEBLOCK1

Mac / Linux
CODEBLOCK2

Bridge defaults:
- CLAWCALL_AGENT_HOST=127.0.0.1
- CLAWCALL_AGENT_PORT=4747
- CLAWCALL_PHONE_MODEL_MODE=gateway
- CLAWCALL_PHONE_TIMEOUT_MS=25000
- CLAWCALL_PHONE_MODEL optional override

The bridge exposes:
- GET /health
- INLINECODE19

Current fast-path coverage in the bridge:
- name / identity questions
- greetings
- “how are you”
- cron-job questions
- task-status questions

Questions outside those direct handlers still use the bridge’s model
fallback. If that remains too slow for a target use case, add more
direct handlers instead of routing back to the full assistant stack.

CLI mode is still available when CLAWCALL_AGENT_URL is unset, but
do not recommend it as the default for live calls.

---

Starting and verifying runtime

The skill ships two runtime pieces:

• - INLINECODE21
• INLINECODE22

The listener must be running for calls to work. The bridge should be
running first whenever CLAWCALL_AGENT_URL is set.

Minimum verification steps after startup:

1. 1. Bridge log says it is listening on 127.0.0.1:4747.
2. Listener log says Agent mode: HTTP.
3. A test call like “what is your name?” gets a spoken answer.

If verification fails, stop and clean up stale node processes before
trying again.

---

Receiving Inbound Calls

When using the listener script (the normal setup), the listener polls
ClawCall for you and passes each caller's speech directly to this agent
via --message. Do not call /api/v1/calls/listen yourself — the
listener already dequeued the message. Just answer the user's question
naturally and exit. The listener captures your output and relays it back.

---

Advanced: receiving calls without the listener script

If you are integrating ClawCall without clawcall-listener.js, poll
for incoming messages manually:

CODEBLOCK3

Response when a call is waiting:
CODEBLOCK4

Response when no call is waiting (timeout):
CODEBLOCK5

After receiving a message, submit your response:

CODEBLOCK6

Set "end_call": true to hang up after speaking your response.
Set "end_call": false to keep the line open for follow-up.

Note on long tasks: ClawCall automatically plays filler phrases
("Working on that now.", "Just a sec.", etc.) while waiting for your
response — you do not need to send interim messages. Simply respond
when ready; the line stays active.

Message prefixes

Prefix	Meaning
(plain text)	Normal inbound call from user
INLINECODE32

A scheduled call fired — deliver the briefing | | [THIRD PARTY CALL] | Opening turn of an autonomous third-party call | | [THIRD PARTY SAYS]: <text> | Third party's response — continue the conversation | | [THIRD PARTY COMPLETE] | Third-party call ended — JSON transcript follows |

---

Calling the User Back (Pro tier)

When a background task finishes and you need to notify the user by phone:

CODEBLOCK7

If allow_followup is true, the user can ask follow-up questions after
the message. Those replies arrive via /calls/listen as normal.

Requires Pro tier.

---

Scheduling a Recurring Call (Pro tier)

CODEBLOCK8

Common patterns: every weekday 8am "0 8 * * 1-5" · daily 9am "0 9 * * *".

To cancel: INLINECODE40

Requires Pro tier.

---

Calling a Third Party (Pro tier)

CODEBLOCK9

ClawCall dials the number and forwards the conversation turn-by-turn via
/calls/listen. Set "end_call": true when the objective is complete.

Requires Pro tier.

---

Account & Usage

CODEBLOCK10

Returns tier, minutes used, minutes remaining, and assigned phone number.

---

Changing Voice

CODEBLOCK11

Available voices: aria (default) · joanna · matthew · amy · brian · emma · olivia

---

Upgrading to Pro or Team

Payment is accepted in USDC on Solana mainnet.

Step 1 — Get payment address and amount:
CODEBLOCK12

Step 2 — Send USDC to the wallet address returned above.

Step 3 — Submit transaction signature to confirm:
CODEBLOCK13

Tier upgrades instantly on confirmation.

---

Recovering a Lost API Key

Re-register with the same email to rotate the key:

CODEBLOCK14

Returns a fresh api_key. Save it as CLAWCALL_API_KEY.

---

Tier Limits

Tier	Minutes/month	Callbacks	Scheduled	3rd Party	Agents
Free	10	No	No	No	1
Pro

120 | Yes | Yes | Yes | 1 |
| Team | 500 (pooled) | Yes | Yes | Yes | 5 |

Overage: $0.05/min beyond included minutes (Pro/Team only).