Amber — Phone-Capable Voice Agent
Inbound calls, confirmed outbound calls, transcripts, calendar booking, optional CRM, and opt-in Apple Contacts lookup through MCP.
Amber — Give Your Agent Real Phone Capabilities
Overview
Screen incoming calls, call a business, book an appointment, or take a message—all through your agent. Amber connects a real phone number to your agent with a Twilio + OpenAI Realtime bridge (runtime/), confirmed outbound calling, transcripts, and MCP tools.
Use it when you want an agent to do the plain-English phone job: call this business, ask this question, book the slot, leave the message, screen this caller, or show me what happened. Amber is built for operators who want the phone capability layer under their own Twilio or compatible voice account, with local logs, a local dashboard, and confirmation gates before outbound calls or calendar writes.
Capability and data scope
Beyond phone calls, configured MCP clients can query availability and create calendar events through ical-query, and independently use optional CRM contact creation, updates, history, and interaction logging. Calendar writes require explicit confirmation. Contact lookup uses an operator-generated local Apple Contacts cache; the sync helper exports contact names/numbers, with optional extended notes, relationships, and addresses only when AMBER_CONTACTS_EXTENDED=true. CRM and transcript enrichment remain separately opt-in. Review local cache, database and transcript retention before use.
The live-call CRM router in runtime/src/skills/router.ts permits only record actions for the number attached to the call by the bridge. A caller-supplied number cannot override it, and live calls cannot search the CRM. Broader CRM search and edits are available through the local MCP server over standard input and output, under the account that runs it. Grant that client access only to trusted operators.
Twilio carries the call and routing details. OpenAI Realtime processes call audio and receives call context, including CRM greeting hints when enabled. Separately opted-in CRM enrichment sends up to 6,000 characters of the transcript to the OpenAI API and writes extracted fields to the local CRM. If configured, the OpenClaw gateway receives consultation requests with relevant call context and forwards caller messages to the operator’s chosen channel. Apple Contacts export runs locally. Custom mid-call skills execute code the operator installs on the host.
Automatic inbound CRM attribution and personalized greetings require the call reference Amber creates from a signed Twilio webhook. Live-call CRM actions use the number tied to the call. Operator MCP tools can search and manage other contacts. An inbound call without a matching reference still goes through screening under the default greeting.
The authenticated MCP screening controls pause or resume new inbound calls. While paused, Amber returns a busy response on its Twilio number. Calls already connected and confirmed outbound calls can continue. The preference is saved under the bridge’s working directory and persists across restarts. Configure forwarding separately in Twilio if you need a human fallback.
Maintainer documentation includes optional ClawHub publishing and demo-recording upload commands. Those commands are manual release/demo workflows, not actions performed at runtime or during installation.
Security upgrade notes
- OpenAI webhooks now require valid
webhook-id,webhook-timestamp, andwebhook-signatureheaders, signingid.timestamp.rawBodywith the configured webhook secret. Missing/invalid signatures and timestamps outside five minutes are rejected; the old unsigned-development override is no longer supported. - Every outbound bridge request now requires a preview from
/call/preview, followed by the exact same number, objective, model and optional call plan withconfirmed=trueand its single-useapprovalTokenwithin five minutes. The MCPmake_calltool and dashboard use this flow. Direct integrations must migrate. A token proves a matching preview occurred; it cannot prove human consent. Clients must obtain explicit operator approval and must not autonomously approve previews. - The dashboard accepts state-changing requests only as JSON from its exact same origin. Open it on its own configured loopback URL, not another site's embedded view. The bridge rejects direct browser-origin requests; use the dashboard proxy or authenticated non-browser integration.
- Caller-derived CRM names/context are passed only as bounded, untrusted user-message data, never inserted into higher-priority greeting instructions or treated as verified identity.
Try asking your agent
- “Screen my incoming calls and take a message with a callback number.”
- “Prepare a call to the restaurant to ask about a table for four at 7 p.m.; show me the details before dialing.”
- “Check my availability for Friday afternoon and help the caller confirm an appointment.”
What you need
- A phone number and voice-provider account — Twilio is the default and recommended provider.
- OpenAI API access — the voice runtime uses OpenAI Realtime.
- A running host with Node.js and a reachable webhook endpoint — plus OpenClaw or a configured MCP client for your chosen workflows. Local calendar integration uses
ical-query. - Usage budget — voice-provider number/call charges and OpenAI API usage are separate; installing the skill does not include those services. The dashboard shows estimated call costs.
Amber is a sensitive communications system. It can process call audio/transcripts through configured voice and AI providers, store local call logs, maintain a local CRM, read/write the operator calendar, expose local MCP tools, and optionally use an Apple Contacts export for name-to-number resolution. Operators should configure caller notice/consent, retention/deletion practices, and least-privilege provider credentials before production use.
Twilio handles phone connections and OpenAI Realtime processes live audio and transcripts. When the OpenClaw gateway integration is configured, it receives call context needed for the requested task. Restrict access to local transcripts and structured summaries and set a retention policy appropriate for your calls.
Privacy defaults: local CRM lookup/logging is disabled unless AMBER_CRM_ENABLED=true, and post-call transcript enrichment is disabled unless AMBER_CRM_TRANSCRIPT_ENRICHMENT=true. Enable those only after setting caller notice/consent and retention/deletion practices.
You stay in control: prepare calls before dialing, review call history afterward, and enable optional caller memory only when you want it.
✨ v5.4.0: Amber ships as an MCP plugin with 9 tools — prepare confirmed calls by name, check call history, query CRM contacts, manage calendar, and control call screening. It works with Claude Desktop/Cowork and other MCP-capable clients or agent harnesses once configured. Includes Apple Contacts integration and a code-enforced call confirmation safeguard to prevent wrong-number dials.
✨ Also: Interactive setup wizard (npm run setup) validates credentials in real-time and generates a working .env file — no manual configuration needed. Once setup is complete, Amber is prompt-based: ask your OpenClaw agent to prepare confirmed calls, answer/screen callers, schedule confirmed appointments, or handle phone workflows in natural language.
See a phone task from prompt to result
Run node demo/first-call-demo.js from the skill folder to see a simulated OpenClaw phone task with recipient and objective approval, a call excerpt, and a result. Demo instructions
The setup wizard recording shows the configuration prompts.
What's included
- Phone number + runtime bridge (
runtime/) — a complete Node.js server that connects a Twilio phone number to OpenAI Realtime with OpenClaw brain-in-the-loop - Amber Skills (
amber-skills/) — modular mid-call capabilities (CRM, calendar, log & forward message) with a spec for building your own - Built-in CRM — local SQLite contact database; Amber can greet callers by name and use operator-approved context naturally on calls, with operator review/correction responsibility
- Call log dashboard (
dashboard/) — browse call history, transcripts, captured messages, estimated costs, and one-touch localhost test calls with regular/mini Realtime model selection - Setup & validation scripts — preflight checks, env templates, quickstart runner
- Architecture docs & troubleshooting — call flow diagrams, common failure runbooks
- Safety guardrails — outbound calls require code-enforced confirmation; payment escalation, consent boundaries, and explicit confirmation for calendar writes are documented
🔌 Amber Skills — Extensible by Design
Amber ships with a growing library of Amber Skills — modular capabilities that plug directly into live voice conversations. Each skill exposes a structured function that Amber can call mid-call, letting you compose powerful voice workflows without touching the bridge code.
👤 CRM — Contact Memory (v5.3.0)
Amber can maintain operator-reviewed caller memory across calls, limited to relevant follow-up context under the operator's notice, consent, and retention policy.
- Opt-in runtime management — set
AMBER_CRM_ENABLED=trueto enable automatic known-caller lookup and interaction logging - Personalized greeting — known callers can be greeted by name; optional notes are used only when relevant to the call objective
- Optional enrichment — set
AMBER_CRM_TRANSCRIPT_ENRICHMENT=trueto allow post-call extraction to propose caller details and notes for the local CRM - Operator review expected — review, correct, or delete CRM records periodically so bad transcript extraction, misleading caller input, or overly sensitive details do not persist indefinitely
- Symmetric — works identically for inbound and outbound calls
- Local SQLite CRM — contact memory is stored at
~/.config/amber/crm.sqlite; CRM records are not cloud-hosted. Live call audio/transcripts still pass through Twilio/OpenAI as part of the phone bridge. Tell callers when calls are handled by an AI assistant and may be logged/used for follow-up, according to your local consent requirements. - Native dependency — requires
better-sqlite3(native build). macOS:sudo xcodebuild -license acceptbeforenpm install. Linux:build-essential+python3.
📅 Calendar
Query the operator's calendar for availability or schedule a new event — all during a live call.
- Availability lookups — free/busy slots for today, tomorrow, this week, or any specific date
- Event creation — create calendar events from a phone conversation only after the required details are collected and the caller explicitly confirms the slot
- Privacy by default — callers are only told whether the operator is free or busy; event titles, names, and locations are never disclosed
- Powered by
ical-query— local-only, zero network latency
📬 Log & Forward Message
Let callers leave a message that is automatically saved and forwarded to the operator.
- Captures the caller's message, name, and optional callback number
- Always saves to the call log first (audit trail), then delivers via the operator's configured messaging channel
- Confirmation-gated — Amber confirms with the caller before sending
- Delivery destination is operator-configured — callers cannot redirect messages
Build Your Own Skills
Amber's skill system is designed to grow. Each skill is a self-contained directory with a SKILL.md (metadata + function schema) and a handler.js. You can:
- Customize the included skills to fit your own setup
- Build new skills for your use case — CRM lookups, inventory checks, custom notifications, anything callable mid-call
- Share skills with the OpenClaw community via ClawHub
See amber-skills/ for examples and the full specification to get started.
Contacts privacy: Apple Contacts sync is opt-in. By default it reads and exports only names, phone numbers, and phone labels needed for call-by-name. Set AMBER_CONTACTS_EXTENDED=true only if you explicitly want extra local-only fields such as email, organization, relationships, addresses, and notes in runtime/contacts-cache.json.
Note: Each skill's
handler.jsis reviewed against its declared permissions. When building or installing third-party skills, review the handler source as you would any Node.js module.
Call log dashboard
cd dashboard && node scripts/serve.js # → http://localhost:8787
- ⬇ Sync button (green) — immediately pulls new calls from
runtime/logs/and refreshes the dashboard. Use this right after a call ends rather than waiting for the background watcher. - ↻ Refresh button (blue) — reloads existing data from disk without re-processing logs.
- One-touch test calls — when opened through
node scripts/serve.js, the dashboard can call a test number through the local Amber bridge and choosegpt-realtime-2.1orgpt-realtime-2.1-miniper call. - Cost visibility — estimates telephony and Realtime token cost from call duration and saved usage metadata; rates are editable in the dashboard.
- Background watcher (
node scripts/watch.js) auto-syncs every 30 seconds when running.
Why Amber
- Ship a voice assistant in minutes —
npm install, configure.env,npm start - Give an agent a real phone number — callers can reach it, and it can place confirmed outbound calls for concrete phone tasks
- Full inbound screening: greeting, message-taking, appointment booking with calendar integration
- Outbound calls with structured call plans (reservations, inquiries, follow-ups), with confirmation gates and a runtime disable switch
- OpenClaw gateway lookup (least-privilege) — voice agent consults your OpenClaw gateway only for call-critical needs (availability checks, confirmed scheduling, required factual lookups), not for unrelated tasks
- Configurable speech detection and waiting acknowledgments to help reduce awkward pauses during lookups
- Fully configurable: assistant name, operator info, org name, calendar, screening style — all via env vars
- Operator safety guardrails for approvals/escalation/payment handling
Personalization requirements
Before deploying, users must personalize:
- assistant name/voice and greeting text,
- own Twilio number and account credentials,
- own OpenAI project + webhook secret,
- own OpenClaw gateway/session endpoint,
- own call safety policy (approval, escalation, payment handling).
Do not reuse example values from another operator.
5-minute quickstart
Option A: Interactive Setup Wizard (recommended) ✨
- Run
cd runtimeandnpm run setup. - Follow the prompts to validate credentials, choose a tunnel URL, and save your configuration.
- Follow the wizard’s instructions to build and start the bridge in another terminal and configure the Twilio and OpenAI webhooks.
- Return to the wizard and press Enter to check readiness. After the checks pass, call your Twilio number to test Amber.
To retry the check without re-entering credentials, run npm run setup -- --check.
Option B: Manual setup
- From the Amber skill folder:
cd runtime && npm ci cd ../amber-skills/crm && npm ciif you plan to enable CRM caller memory.cd ../..and copyreferences/env.exampletoruntime/.env, then fill in your values.- Set
AMBER_CRM_ENABLED=trueonly if you want local caller memory/known-caller greetings. cd runtime && npm run build && npm start- Point your Twilio voice webhook to
https://<your-domain>/twilio/inbound - Call your Twilio number — your voice assistant answers!
Option C: Validation-only (existing setup)
- Copy
references/env.exampleto your own.envand replace placeholders. - Export required variables (
TWILIO_ACCOUNT_SID,TWILIO_AUTH_TOKEN,TWILIO_CALLER_ID,OPENAI_API_KEY,OPENAI_PROJECT_ID,OPENAI_WEBHOOK_SECRET,PUBLIC_BASE_URL). - Run quick setup:
scripts/setup_quickstart.sh - If preflight passes, run one inbound and one outbound smoke test.
- Only then move to production usage.
Credential scope (recommended hardening)
Use least-privilege credentials for every provider:
- Twilio: use a dedicated subaccount for Amber and rotate auth tokens regularly.
- OpenAI: use a dedicated project API key for this runtime only; avoid reusing keys from unrelated apps.
- OpenClaw Gateway token: only set
OPENCLAW_GATEWAY_TOKENif you need brain-in-the-loop lookups; keep token scope minimal. - Dependency integrity: runtime dependencies are pinned by
runtime/package-lock.json; review dependency changes before publishing updates. - Secrets in logs: never print full credentials in scripts, setup output, or call transcripts.
- Setup wizard validation scope: credential checks call only official Twilio/OpenAI API endpoints over HTTPS for auth verification; no arbitrary exfiltration endpoints are used.
These controls reduce blast radius if a host or config file is exposed.
Safe defaults
- Outbound calling is enabled by default for the full phone-agent experience. Set
AMBER_ENABLE_OUTBOUND_CALLS=falseto disable the outbound call endpoint. - Require explicit approval before outbound calls. Note on confirmation enforcement: The bridge enforces a matching, expiring, single-use preview token plus
confirmed=truebefore dialing, including MCP and dashboard calls. This enforces the two-step protocol, not proof of human consent; the MCP client must still obtain explicit operator approval. - If payment/deposit is requested, stop and escalate to the human operator.
- Keep greeting short and clear.
- Use timeout + graceful fallback when
ask_openclawis slow/unavailable.
Setup and verification
Read references/architecture.md, run scripts/validate_voice_env.sh on the target host, and use the setup wizard's first-call check. Use an authorized test number for inbound and outbound smoke tests.
Troubleshooting (common)
- "Missing env vars" → re-check
.envvalues and re-runscripts/validate_voice_env.sh. - "Call connects but assistant is silent" → verify TTS model setting and provider auth.
- "ask_openclaw timeout" → verify gateway URL/token and increase timeout conservatively.
- "CRM lookup fails after a Node upgrade" → run
cd amber-skills/crm && npm rebuild better-sqlite3, then restart the Amber runtime. - "Webhook unreachable" → verify tunnel/domain and Twilio webhook target.
Install safety notes
- Amber does not execute arbitrary install-time scripts from this repository.
- Runtime install uses standard Node dependency installation in
runtime/, with dependencies pinned inruntime/package-lock.json. - CRM uses
better-sqlite3(native module), which compiles locally on your machine. - Review
runtime/package.jsondependencies before deployment in regulated environments.
Resources
- Runtime bridge:
runtime/(full source + README) - Architecture and behavior notes:
references/architecture.md - Env template:
references/env.example - Quick setup runner:
scripts/setup_quickstart.sh - Env/config validator:
scripts/validate_voice_env.sh
Authenticated local clients and caller-data boundaries
Sensitive bridge HTTP endpoints always require bearer authentication, even on loopback: a public tunnel can forward a remote request from a local peer. Existing BRIDGE_API_TOKEN settings continue to work. When absent, Amber generates a random installation credential in runtime/data/bridge-api-token (owner-only mode 0600). Bundled MCP and the dashboard's configured local bridge automatically share this file, including a token set in this installation's runtime/.env; the browser never receives the generated secret. Set AMBER_BRIDGE_TOKEN_FILE to an owner-only shared file for clients in another installation; relative paths resolve from runtime/. Custom HTTP clients must supply Authorization: Bearer <token>; remote clients need the operator to configure the same credential. Generated credentials must never be published or exposed by a tunnel. Back up/rotate them as secrets. On a read-only installation, provision a writable owner-only token path or set the existing environment token.
Dashboard automatic credentials are sent only to AMBER_BRIDGE_URL (default http://127.0.0.1:8000), not arbitrary loopback targets. If you use a different local bridge port, set that URL or provide its token in the existing dashboard field. Do not expose the unauthenticated local dashboard itself through a public tunnel; its same-origin checks are browser-CSRF defenses, not remote-user authentication.
Gateway consultations and skill requests use call-scoped session identifiers. Repeated lookups within a call retain their session, but one caller does not inherit another call's conversation. Persistent opt-in CRM behavior is unchanged. Caller transcripts, objectives, names and callback values are user-role JSON data, never higher-priority instructions or verified identity. All message fields stay inside that boundary while the operator still receives the readable call message. This reduces instruction-confusion risk; JSON and prompts do not guarantee model injection immunity or replace the gateway's own least-privilege permissions and approval policies. GPT-4o brain fallback is retained. Calendar audit logs record outcomes and generic error reasons. Call routing records retain numbers and call identifiers for the dashboard. Caller messages and transcripts remain sensitive local records.
Optional local authority and persistence
Calendar lookup/create uses the operator-installed ical-query helper. Contact sync is an explicit local Apple Contacts export; it can invoke local macOS helpers. CRM reads/writes its opt-in local database. The optional runtime/scripts/dist-watcher.cjs maintenance watcher reads the named bridge service from launchctl, checks its process start time with ps, and restarts that service after build changes. An operator must install and enable the watcher separately. These local binaries, environment settings, credential files, contact cache, logs and database are real authority/data accesses, not capabilities constrained by the skill metadata alone. Review source and host permissions before enabling integrations.
- Downloads
- 5.8kAll time
- Security audit
- Review
- Last updated
- 6h ago
- Current version
- v5.5.62
- License
- MIT-0
