agent-takeover
How to perform a live agent takeover of the Clawfinger voice gateway — dial, inject greetings, handle turns, release, and observe handback. Covers timing, endpoints, the WebSocket protocol, and includes a human-guided test case.
Install / Use
npx skills add LeoYeAI/openclaw-master-skills --skill agent-takeoverInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OtherSupported Platforms
Our assessment of agent-takeover
agent-takeover scores 90/100 on our quality scale, 96th of 330 Other skills we index (top 30%).
Its SKILL.md is 21 KB long, well organised into 26 sections with 13 code examples: a thorough specification that gives an agent plenty to work with.
With 2,149 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-10-30 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 98/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-30. Automated pattern scan on 2026-09-30. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
agent-takeover compared with similar skills
All 4 of these similar skills score higher than agent-takeover; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| agent-takeover (this skill)by LeoYeAI | 90 | 2.1k | 4mo ago | SKILL.md |
| LocalAIby mudler | 100 | 50.4k | today | MCP Server |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
Frequently asked questions
- How do I install agent-takeover?
- Run
npx skills add LeoYeAI/openclaw-master-skills --skill agent-takeover. The install tabs above show the steps for each supported agent. - Which AI agents does agent-takeover work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is agent-takeover safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 98/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is agent-takeover still maintained?
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: agent-takeover description: How to perform a live agent takeover of the Clawfinger voice gateway — dial, inject greetings, handle turns, release, and observe handback. Covers timing, endpoints, the WebSocket protocol, and includes a human-guided test case. metadata: openclaw: emoji: "\U0001F3AF" skillKey: agent-takeover requires: - plugin:clawfinger
Agent Takeover — Full Lifecycle Guide
How an external agent (OpenClaw plugin, custom script, or any WebSocket client) takes control of a live phone call, handles conversation turns directly, and hands back to the local LLM.
Architecture Overview
Caller <--> Phone App <--> Gateway /api/turn <--> Local LLM
|
+-- (takeover) --> Agent WS
Normal flow: phone sends audio to /api/turn, gateway runs ASR → LLM → TTS, returns audio.
Takeover flow: after takeover, gateway sends turn.request to the agent WebSocket instead of calling the local LLM. The agent replies with text, gateway runs TTS, returns audio to phone.
Endpoints Used
WebSocket (primary — full bidirectional control)
WS /api/agent/ws — No authentication required on the WebSocket itself. Connects, receives all bus events, and sends commands.
| Send (agent → gateway) | Fields | Description |
|-------------------------|--------|-------------|
| dial | number | Dial outbound call via ADB |
| inject | text, session_id | Queue TTS message for next turn poll |
| takeover | session_id | Take over LLM for this session |
| release | session_id | Hand back to local LLM |
| hangup | session_id (optional) | Force hang up call + end session |
| get_call_state | session_id | Query conversation history and state |
| end_session | session_id | Mark session ended without phone hangup |
| inject_context | session_id, context | Push knowledge into LLM context |
| clear_context | session_id | Remove injected knowledge |
| ping | — | Heartbeat |
| Receive (gateway → agent) | Fields | Description |
|----------------------------|--------|-------------|
| dial.ack | ok, detail | Dial result |
| takeover.ack | ok, session_id | Takeover confirmed |
| release.ack | ok, session_id | Release confirmed |
| hangup.ack | ok, detail, session_id | Hangup result |
| turn.request | session_id, transcript, request_id | Takeover only — caller spoke, agent must reply |
| turn.started | session_id | Turn processing began |
| turn.transcript | transcript | ASR result |
| turn.reply | reply | LLM/agent reply text |
| turn.complete | metrics, transcript, reply, model | Turn finished |
| session.ended | session_id | Session ended (stale sweep, hangup, or explicit end) |
REST (alternative — no persistent connection needed)
| Method | Path | Purpose |
|--------|------|---------|
| POST | /api/call/dial | {"number": "+49..."} — dial via ADB |
| POST | /api/call/hangup | {"session_id": "..."} — force hangup |
| POST | /api/call/inject | {"text": "...", "session_id": "..."} — inject TTS |
| GET | /api/agent/sessions | List active session IDs |
| GET | /api/agent/call/{sid} | Full call state (history, instructions, takeover) |
| POST | /api/agent/context/{sid} | {"context": "..."} — inject knowledge |
REST cannot do takeover. Takeover requires the WebSocket for real-time turn.request / reply exchange. REST is fine for dial, inject, hangup, and observation.
Takeover Turn Protocol
During takeover, the gateway replaces the local LLM with the agent for response generation:
Phone → /api/turn (audio) → Gateway ASR → transcript
↓
Gateway sends to Agent WS:
{"type": "turn.request",
"session_id": "abc123",
"transcript": "what caller said",
"request_id": "unique-id"}
↓
Agent replies on same WS:
{"reply": "agent's response",
"request_id": "unique-id"}
↓
Gateway TTS → audio → Phone
Critical: request_id correlation
The agent must echo back the request_id from the turn.request. Without it, the gateway cannot match the reply to the pending turn and the request times out.
// Gateway sends:
{"type": "turn.request", "session_id": "abc", "transcript": "hello", "request_id": "a1b2c3"}
// Agent must reply:
{"reply": "Hi there!", "request_id": "a1b2c3"}
No type field needed in the reply — just reply + request_id.
Timeout and fallback
If the agent doesn't reply within the timeout (default 60s, configurable via agent_takeover_timeout in config), the gateway falls back to the local LLM for that single turn. The takeover remains active — the next turn will try the agent again.
Timing Model
Understanding timing is critical for a smooth takeover experience.
Phone polling cadence
The phone app polls /api/turn in a tight loop:
- Record audio chunk (~2-5s of speech)
- POST to
/api/turn - Wait for response (ASR + LLM/agent + TTS)
- Play response audio
- Go to step 1
The phone does NOT poll on a fixed interval — it sends the next turn as soon as playback finishes and new audio is captured. Typical turn cycle: 3-8 seconds.
Inject timing
inject queues a pre-synthesized TTS message. It's delivered on the next /api/turn poll, before ASR/LLM processing:
Agent injects "Hello!" at T=0
↓
Phone polls /api/turn at T=3 (next natural poll)
↓
Gateway sees pending inject → returns inject audio immediately (skips ASR/LLM)
↓
Phone plays "Hello!" → polls again
Key implications:
- Inject is NOT instant — there's a delay of up to one poll cycle (3-8s)
- During takeover, the phone is usually waiting for the agent's reply, so the next poll happens quickly after the agent responds
- Multiple injects queue up — each delivered on successive polls
- Inject skips ASR entirely — the phone's recorded audio is ignored for that poll
Takeover timing
T=0 Agent sends {"type": "takeover", "session_id": "..."}
T=0 Gateway immediately routes future turns to agent
T=0 Agent gets {"type": "takeover.ack", "ok": true}
T=3-8 Phone polls /api/turn → gateway ASR → turn.request sent to agent
T=3-8 Agent replies → gateway TTS → phone plays agent's response
Takeover takes effect instantly on the gateway side. The first turn.request arrives on the next phone poll.
Release timing
T=0 Agent sends {"type": "release", "session_id": "..."}
T=0 Gateway removes takeover → local LLM handles future turns
T=0 Agent gets {"type": "release.ack", "ok": true}
T=3-8 Phone polls /api/turn → local LLM responds (no more turn.requests to agent)
Release is also instant. The agent continues receiving bus events (turn.complete, etc.) but no longer gets turn.request messages.
Inject + Takeover ordering
When you inject a greeting AND takeover in quick succession:
T=0.0 Agent injects greeting text
T=0.5 Agent sends takeover
T=3 Phone polls → gets inject (greeting plays) — takeover is active but no turn.request yet
T=8 Phone polls again → NOW it's a takeover turn → turn.request sent to agent
The inject is consumed first (it takes priority in the turn endpoint), then takeover kicks in on the subsequent poll. This is the correct order for "inject greeting then take over."
Dial-to-first-turn latency
T=0 Agent sends dial command
T=0 ADB broadcast sent to phone
T=1-3 Phone initiates outbound call
T=5-30 Callee picks up (depends on the person)
T=+1 Phone detects call connected, sends first /api/turn (greeting)
T=+2 Gateway processes greeting (forced_reply → TTS only, no ASR/LLM)
T=+5 Greeting plays, phone captures first real audio
T=+8 First real turn arrives at gateway
Total dial-to-first-real-turn: 10-40 seconds depending on pickup time.
Session Lifecycle
Sessions have a TTL of 60 seconds of inactivity (configurable via session_ttl). The phone polls every 3-8s during a call, so active calls never hit the TTL. But if:
- The phone crashes or loses USB connection
- The caller hangs up and the phone doesn't send
/api/session/end
...the session auto-ends after 60s of no polls.
Session detection after dial: After dialing, the agent needs the session ID. Options:
- Watch bus events — a
turn.startedevent withsession_idarrives when the call connects - Poll
GET /api/agent/sessions— check for new session IDs - Send
get_call_state— if you know the session ID
Option 1 (events) is most reliable and fastest.
Complete Takeover Lifecycle
1. CONNECT ws://gateway:8996/api/agent/ws
2. DIAL {"type": "dial", "number": "+49..."}
WAIT for dial.ack (ok: true)
3. DISCOVER watch events for session_id (turn.started or session.started)
4. INJECT {"type": "inject", "session_id": "...", "text": "Custom greeting"}
5. TAKEOVER {"type": "takeover", "session_id": "..."}
WAIT for takeover.ack (ok: true)
6. HANDLE receive turn.request → reply with {reply, request_id}
REPEAT for N turns
7. RELEASE {"type": "release", "session_id": "..."}
WAIT for release.ack (ok: true)
8. OBSERVE watch turn.complete events → model != "agent" confirms local LLM resumed
9. HANGUP {"type": "hangup", "session_id": "..."} (optional — end call)
Error Handling
| Scenario | What happens |
|----------|-------------|
| Agent WS disconnects during takeover | All takeovers auto-released, local LLM resumes |
| Agent doesn't reply within 60s | That turn falls back to local LLM; takeover stays active for next turn |
| Session ends during takeover | session.ended event; further turn.requests stop |
| Multiple agents take over same session | Last takeover wins (overwrites previous) |
| Takeover of non-existent session | takeover.ack with ok: false |
| Release without takeover | release.ack with ok: false |
OpenClaw Plugin (Clawfinger)
If using the Clawfinger OpenClaw plugin, you don't need raw WebSocket code. The plugin tools map directly:
| Lifecycle step | Plugin tool |
|----------------|-------------|
| Dial | clawfinger_dial |
| Check sessions | clawfinger_sessions |
| Inspect state | clawfinger_call_state |
| Inject greeting | clawfinger_inject |
| Take over | clawfinger_takeover |
| Wait for caller | clawfinger_turn_wait — blocks until caller speaks, returns transcript + request_id |
| Reply to caller | clawfinger_turn_reply — send response text with the request_id |
| Release | clawfinger_release |
| Hang up | clawfinger_hangup |
Takeover tool workflow:
clawfinger_takeover(session_id) → "Takeover active."
clawfinger_turn_wait() → {transcript: "...", request_id: "abc123"}
clawfinger_turn_reply(request_id, reply) → "Reply sent."
clawfinger_turn_wait() → next turn...
clawfinger_turn_reply(...) → ...
clawfinger_release(session_id) → "Released."
Slash commands: /clawfinger dial +49..., /clawfinger takeover <sid>, /clawfinger release <sid>, /clawfinger hangup.
Test Case: Human-Guided Takeover (3 turns)
A complete test walkthrough. Requires: gateway running, phone connected via ADB, a real phone number to call.
Prerequisites
- Gateway running on
127.0.0.1:8996 - Phone connected via ADB (
adb devicesshows device) - ADB reverse active (
adb reverse tcp:8996 tcp:8996) websocketsPython package installed (pip install websockets)
Test Script
Save as test_takeover.py in the gateway directory:
#!/usr/bin/en
Truncated for display — read the full file on GitHub.
Related Skills
LocalAI
50.4kLocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
