amber-voice-assistant

Original source / Raw SKILL.md

---
name: amber-voice-assistant
title: "Amber — Phone-Capable Voice Agent"
description: "The most complete voice and phone calling skill for OpenClaw. Handles inbound and outbound phone calls over Twilio with OpenAI Realtime speech. Inbound outbound calling, calendar management, CRM, multilingual phone assistant with transcripts. Includes setup wizard, live dashboard, and brain-in-the-loop escalation. Now also ships as a Claude Desktop plugin (MCP) — make calls, check CRM, and query your calendar directly from Claude Desktop."
homepage: https://github.com/batthis/amber-openclaw-voice-agent
metadata: {"openclaw":{"emoji":"☎️","requires":{"env":["TWILIO_ACCOUNT_SID","TWILIO_AUTH_TOKEN","TWILIO_CALLER_ID","OPENAI_API_KEY","OPENAI_PROJECT_ID","OPENAI_WEBHOOK_SECRET","PUBLIC_BASE_URL"],"optionalEnv":["OPENCLAW_GATEWAY_URL","OPENCLAW_GATEWAY_TOKEN","BRIDGE_API_TOKEN","TWILIO_WEBHOOK_STRICT","VOICE_PROVIDER","VOICE_WEBHOOK_SECRET","ASSISTANT_NAME","OPERATOR_NAME","AMBER_CRM_DB_PATH","AGENT_MD_PATH","DEFAULT_CALENDAR"],"anyBins":["node","ical-query","bash"]},"primaryEnv":"OPENAI_API_KEY","install":[{"id":"runtime","kind":"node","cwd":"runtime","label":"Install Amber runtime (cd runtime && npm install && npm run build)"}]}}
---

# Amber — Phone-Capable Voice Agent

## Overview

Amber gives any OpenClaw deployment a phone-capable AI voice assistant. It ships with a **production-ready Twilio + OpenAI Realtime bridge** (`runtime/`) that handles inbound call screening, outbound calls, appointment booking, and live OpenClaw knowledge lookups — all via natural voice conversation.

**✨ New in v5.4.0:** Amber now ships as a **Claude Desktop MCP plugin** with 9 tools — make outbound calls by name, check call history, query CRM contacts, manage calendar, and control call screening, all from Claude Desktop or Claude Cowork. Includes Apple Contacts integration and a 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!

## See it in action

![Setup Wizard Demo](demo/demo.gif)

**[▶️ Watch the interactive demo on asciinema.org](https://asciinema.org/a/l1nOHktunybwAheQ)** (copyable text, adjustable speed)

*The interactive wizard validates credentials, detects ngrok, and generates a complete `.env` file in minutes.*

### What's included

- **Runtime bridge** (`runtime/`) — a complete Node.js server that connects Twilio phone calls 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 greets callers by name and references personal context naturally on every call
- **Call log dashboard** (`dashboard/`) — browse call history, transcripts, and captured messages; includes **manual Sync button** to pull new calls on demand
- **Setup & validation scripts** — preflight checks, env templates, quickstart runner
- **Architecture docs & troubleshooting** — call flow diagrams, common failure runbooks
- **Safety guardrails** — approval patterns for outbound calls, payment escalation, consent boundaries

## 🔌 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 remembers every caller across calls and uses that memory to personalize every conversation.

- **Runtime-managed** — lookup and logging happen automatically; Amber never has to "remember" to call CRM
- **Personalized greeting** — known callers are greeted by name; personal context (pets, recent events, preferences) is referenced warmly on the first sentence
- **Two-pass enrichment** — auto-log captures the call immediately; a post-call LLM extraction pass reads the full transcript to extract name, email, and `context_notes`
- **Symmetric** — works identically for inbound and outbound calls
- **Local SQLite** — stored at `~/.config/amber/crm.sqlite`; no cloud, no data leaves your machine
- **Native dependency** — requires `better-sqlite3` (native build). macOS: `sudo xcodebuild -license accept` before `npm 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** — book appointments directly into the operator's calendar from a phone conversation
- **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](https://clawhub.com)

See [`amber-skills/`](amber-skills/) for examples and the full specification to get started.

> **Note:** Each skill's `handler.js` is 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

```bash
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.
- 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`
- Full inbound screening: greeting, message-taking, appointment booking with calendar integration
- Outbound calls with structured call plans (reservations, inquiries, follow-ups)
- **`ask_openclaw` tool (least-privilege)** — voice agent consults your OpenClaw gateway only for call-critical needs (calendar checks, booking, required factual lookups), not for unrelated tasks
- VAD tuning + verbal fillers to keep conversations natural (no dead air 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) ✨

The easiest way to get started:

1. `cd runtime`
2. `npm run setup`
3. Follow the interactive prompts — the wizard will:
   - Validate your Twilio and OpenAI credentials in real-time
   - Auto-detect and configure ngrok if available
   - Generate a working `.env` file
   - Optionally install dependencies and build the project
4. Configure your Twilio webhook (wizard shows you the exact URL)
5. Start the server: `npm start`
6. Call your Twilio number — your voice assistant answers!

**Benefits:**
- Real-time credential validation (catch errors before you start)
- No manual `.env` editing
- Automatic ngrok detection and setup
- Step-by-step guidance with helpful links

### Option B: Manual setup

1. `cd runtime && npm install`
2. Copy `../references/env.example` to `runtime/.env` and fill in your values.
3. `npm run build && npm start`
4. Point your Twilio voice webhook to `https://<your-domain>/twilio/inbound`
5. Call your Twilio number — your voice assistant answers!

### Option C: Validation-only (existing setup)

1. Copy `references/env.example` to your own `.env` and replace placeholders.
2. Export required variables (`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_CALLER_ID`, `OPENAI_API_KEY`, `OPENAI_PROJECT_ID`, `OPENAI_WEBHOOK_SECRET`, `PUBLIC_BASE_URL`).
3. Run quick setup:
   `scripts/setup_quickstart.sh`
4. If preflight passes, run one inbound and one outbound smoke test.
5. 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_TOKEN` if you need brain-in-the-loop lookups; keep token scope minimal.
- **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

- Require explicit approval before outbound calls. **Note on confirmation enforcement:** For MCP-initiated outbound calls (`make_call`), confirmation is enforced at the MCP server layer in code (the tool returns a preview and requires `confirmed=true` on a second call before dialing) — this is not LLM-only instruction. The LLM instruction layer provides an additional reminder, but the code gate is the primary enforcement mechanism.
- If payment/deposit is requested, stop and escalate to the human operator.
- Keep greeting short and clear.
- Use timeout + graceful fallback when `ask_openclaw` is slow/unavailable.

## Workflow

1. **Confirm scope for V1**
   - Include only stable behavior: call flow, bridge behavior, fallback behavior, and setup steps.
   - Exclude machine-specific secrets and private paths.

2. **Document architecture + limits**
   - Read `references/architecture.md`.
   - Keep claims realistic (latency varies; memory lookups are best-effort).

3. **Run release checklist**
   - Read `references/release-checklist.md`.
   - Validate config placeholders, safety guardrails, and failure handling.

4. **Smoke-check runtime assumptions**
   - Run `scripts/validate_voice_env.sh` on the target host.
   - Fix missing env/config before publishing.

5. **Publish**
   - Publish to ClawHub (example):  
     `clawhub publish <skill-folder> --slug amber-voice-assistant --name "Amber Voice Assistant" --version 1.0.0 --tags latest --changelog "Initial public release"`
   - Optional: run your local skill validator/packager before publishing.

6. **Ship updates**
   - Publish new semver versions (`1.0.1`, `1.1.0`, `2.0.0`) with changelogs.
   - Keep `latest` on the recommended version.

## Troubleshooting (common)

- **"Missing env vars"** → re-check `.env` values and re-run `scripts/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.
- **"Webhook unreachable"** → verify tunnel/domain and Twilio webhook target.

## Guardrails for public release

- Never publish secrets, tokens, phone numbers, webhook URLs with credentials, or personal data.
- Include explicit safety rules for outbound calls, payments, and escalation.
- Mark V1 as beta if conversational quality/latency tuning is ongoing.

## Install safety notes

- Amber does **not** execute arbitrary install-time scripts from this repository.
- Runtime install uses standard Node dependency installation in `runtime/`.
- CRM uses `better-sqlite3` (native module), which compiles locally on your machine.
- Review `runtime/package.json` dependencies before deployment in regulated environments.

## Resources

- **Runtime bridge:** `runtime/` (full source + README)
- Architecture and behavior notes: `references/architecture.md`
- Release gate: `references/release-checklist.md`
- Env template: `references/env.example`
- Quick setup runner: `scripts/setup_quickstart.sh`
- Env/config validator: `scripts/validate_voice_env.sh`


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/setup_quickstart.sh

```bash
#!/usr/bin/env bash
set -euo pipefail

echo "[amber-voice-assistant] Quickstart setup"
echo "1) Copy references/env.example to your own .env and replace placeholders."

env_example_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/references"
if [[ -f "$env_example_dir/env.example" ]]; then
  echo "   Example file: $env_example_dir/env.example"
fi

echo "2) Export required vars (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_CALLER_ID, OPENAI_API_KEY, OPENAI_PROJECT_ID, OPENAI_WEBHOOK_SECRET, PUBLIC_BASE_URL)."
echo "3) Run preflight validator..."
"$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/validate_voice_env.sh"

echo "4) Personalize voice assistant values (name/greeting/safety policy)."
echo "5) Run one inbound/outbound smoke call before production use."

echo "[amber-voice-assistant] Quickstart complete."

```

### references/architecture.md

```markdown
# Architecture (Amber Voice Assistant)

## Goal
Provide a phone-call voice assistant that can consult OpenClaw during the call for facts, context, or task specific lookup.

## Core components

1. **Telephony edge (Twilio)**
   - Handles PSTN call leg (inbound/outbound).
2. **Realtime voice runtime**
   - Manages STT/LLM/TTS loop.
3. **Bridge service**
   - Intercepts tool/function calls from realtime model.
   - For `ask_openclaw` requests, forwards question to OpenClaw session/gateway.
4. **OpenClaw brain**
   - Returns concise result for voice playback.

## Typical call flow

1. Call connects.
2. Assistant greets caller.
3. Caller asks question.
4. Voice runtime triggers `ask_openclaw` when needed.
5. Bridge queries OpenClaw (timeout + fallback enforced).
6. Assistant replies with synthesized answer.

## Required behavior

- **Timeouts:** protect call UX from long pauses.
- **Graceful degradation:** if OpenClaw lookup is unavailable, assistant says it cannot verify right now and offers callback/escalation.
- **Safety checks:** outbound call intent, payment/deposit handoff, and consent boundaries.
- **Auditability:** log call IDs, timestamps, and major tool events.

## Known limitations

- “Open tracking” style certainty does not apply here either: call-side model/tool failures can appear as latency or partial answers.
- Latency depends on network, provider load, model selection, and tunnel quality.
- Availability and quality can vary by host machine and plugin/runtime versions.

```

### references/release-checklist.md

```markdown
# V1 Release Checklist (Public)

## 1) Safety + policy
- [ ] Outbound call policy is explicit (requires human approval unless user config says otherwise).
- [ ] Payment/deposit rule is explicit (stop + handoff).
- [ ] Privacy statement included (no secret leakage, no unauthorized data sharing).

## 2) Secret hygiene
- [ ] No API keys/tokens in files.
- [ ] No private phone numbers unless intended as placeholders.
- [ ] Replace local absolute paths with variables or examples.

## 3) Runtime behavior
- [ ] Greeting works.
- [ ] ask_openclaw call path works.
- [ ] Timeout/fallback message is human-friendly.
- [ ] Logging is enough to debug failed calls.

## 4) Installability
- [ ] SKILL.md has clear trigger description.
- [ ] Setup steps are reproducible on a fresh machine.
- [ ] Optional dependencies are marked optional.

## 5) Packaging + publish
- [ ] `package_skill.py` validation passes.
- [ ] Publish with semver `1.0.0` and changelog.
- [ ] Add `latest` tag.

## 6) Post-publish
- [ ] Verify listing page renders correctly on ClawHub.
- [ ] Test install from CLI on a clean workspace.
- [ ] Open a tracking issue list for V1->V2 fixes.

```

### scripts/validate_voice_env.sh

```bash
#!/usr/bin/env bash
set -euo pipefail

# Lightweight preflight for Amber Voice Assistant deployments.
# Safe: prints missing values only (never prints secret contents).

required=(
  TWILIO_ACCOUNT_SID
  TWILIO_AUTH_TOKEN
  TWILIO_CALLER_ID
  OPENAI_API_KEY
  OPENAI_PROJECT_ID
  OPENAI_WEBHOOK_SECRET
  PUBLIC_BASE_URL
)

optional=(
  OPENCLAW_GATEWAY_URL
  OPENCLAW_GATEWAY_TOKEN
  REALTIME_MODEL
  TTS_MODEL
)

missing=0

echo "[amber-voice-assistant] Checking required env vars..."
for key in "${required[@]}"; do
  if [[ -z "${!key:-}" ]]; then
    echo "  ✗ missing: $key"
    missing=1
  else
    echo "  ✓ $key"
  fi
done

echo "[amber-voice-assistant] Checking optional env vars..."
for key in "${optional[@]}"; do
  if [[ -z "${!key:-}" ]]; then
    echo "  - not set: $key"
  else
    echo "  ✓ $key"
  fi
done

echo "[amber-voice-assistant] Tool checks..."
if command -v node >/dev/null 2>&1; then
  echo "  ✓ node $(node -v)"
else
  echo "  ✗ node missing"
  missing=1
fi

if command -v openclaw >/dev/null 2>&1; then
  echo "  ✓ openclaw $(openclaw --version | head -n1)"
else
  echo "  - openclaw CLI not found in PATH"
fi

if [[ "$missing" -eq 1 ]]; then
  echo "[amber-voice-assistant] Preflight failed. Set missing required env vars."
  exit 1
fi

echo "[amber-voice-assistant] Preflight passed."

```

### runtime/package.json

```json
{
  "name": "amber-voice-bridge",
  "version": "5.5.0",
  "description": "Twilio + OpenAI Realtime SIP bridge for Amber Voice Assistant (OpenClaw skill)",
  "private": true,
  "type": "module",
  "scripts": {
    "setup": "node setup-wizard.js",
    "dev": "tsx watch src/index.ts",
    "build": "tsc -p .",
    "start": "node dist/index.js",
    "mcp": "node dist/mcp-server.js",
    "sync-contacts": "node scripts/sync-contacts.js",
    "validate": "node ../scripts/validate_voice_env.sh"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.27.1",
    "better-sqlite3": "^11.7.0",
    "body-parser": "^1.20.3",
    "dotenv": "^16.4.7",
    "express": "^4.19.2",
    "openai": "^4.82.0",
    "twilio": "^5.3.7",
    "ws": "^8.18.0"
  },
  "devDependencies": {
    "@types/better-sqlite3": "^7.6.13",
    "@types/body-parser": "^1.19.5",
    "@types/express": "^4.17.21",
    "@types/node": "^22.10.2",
    "@types/ws": "^8.5.12",
    "tsx": "^4.19.2",
    "typescript": "^5.7.3"
  },
  "engines": {
    "node": ">=20.0.0"
  }
}

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# ☎️ Amber — Phone-Capable Voice Agent

**A voice sub-agent for [OpenClaw](https://openclaw.ai)** — gives your OpenClaw deployment phone capabilities via a provider-swappable telephony bridge + OpenAI Realtime. Twilio is the default and recommended provider.

[![ClawHub](https://img.shields.io/badge/ClawHub-amber--voice--assistant-blue)](https://clawhub.ai/skills/amber-voice-assistant)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## What is Amber?

Amber is not a standalone voice agent — it operates as an extension of your OpenClaw instance, delegating complex decisions (calendar lookups, contact resolution, approval workflows) back to OpenClaw mid-call via the `ask_openclaw` tool.

### Features

- 🔉 **Inbound call screening** — greeting, message-taking, appointment booking
- 📞 **Outbound calls** — reservations, inquiries, follow-ups with structured call plans
- 🧠 **Brain-in-the-loop** — consults your OpenClaw gateway mid-call for calendar, contacts, preferences
- 👤 **Built-in CRM** — remembers every caller across calls; greets by name, references personal context naturally
- 📊 **Call log dashboard** — browse history, transcripts, captured messages, follow-up tracking
- ⚡ **Launch in minutes** — `npm install`, configure `.env`, `npm start`
- 🔒 **Safety guardrails** — operator approval for outbound calls, payment escalation, consent boundaries
- 🎛️ **Fully configurable** — assistant name, operator info, org name, voice, screening style
- 📝 **AGENT.md** — customize all prompts, greetings, booking flow, and personality in a single editable markdown file (no code changes needed)

## 🆕 What's New

### v5.3.1 — Security Scope Hardening (Feb 2026)

Addressed scanner feedback around instruction scope and credential handling:

- Tightened `ask_openclaw` usage rules to **call-critical, least-privilege actions only**
- Clarified credential hygiene guidance (dedicated Twilio/OpenAI credentials, minimal gateway token scope)
- Added setup-wizard preflight warnings for native build requirements (`better-sqlite3`) to reduce insecure/failed installs

### v5.3.0 — CRM Skill (Feb 2026)

Amber now has memory. Every call — inbound or outbound — is automatically logged to a local SQLite contact database. Callers are greeted by name. Personal context (pet names, recent events, preferences) is captured post-call by an LLM extraction pass and used to personalize future conversations. No configuration required — it works out of the box.

See [CRM skill docs](#-crm--contact-memory) below for details.

---

## Quick Start

```bash
cd runtime && npm install
cp ../references/env.example .env  # fill in your values
npm run build && npm start
```

Point your Twilio voice webhook to `https://<your-domain>/twilio/inbound` — done!

> **Switching providers?** Set `VOICE_PROVIDER=telnyx` (or another supported provider) in your `.env` — no code changes needed. See [SKILL.md](SKILL.md) for details.

## ♻️ Runtime Management — Staying Current After Recompilation

**Important:** Amber's runtime is a long-running Node.js process. It loads `dist/` once at startup. If you recompile (e.g. after a `git pull` and `npm run build`), **the running process will not pick up the changes automatically** — you must restart it.

```bash
# macOS LaunchAgent (recommended)
launchctl kickstart -k gui/$(id -u)/com.jarvis.twilio-bridge

# or manual restart
kill $(pgrep -f 'dist/index.js') && sleep 2 && node dist/index.js
```

### Automatic Restart (Recommended for Persistent Deployments)

Amber includes a `dist-watcher` script that runs in the background and automatically restarts the runtime whenever `dist/` files are newer than the running process. This prevents the "stale runtime" problem entirely.

To enable it, register the provided LaunchAgent:

```bash
cp runtime/scripts/com.jarvis.amber-dist-watcher.plist.example ~/Library/LaunchAgents/com.jarvis.amber-dist-watcher.plist
# Edit the plist to match your username/paths
launchctl load ~/Library/LaunchAgents/com.jarvis.amber-dist-watcher.plist
```

The watcher checks every 60 seconds and logs to `/tmp/amber-dist-watcher.log`.

> **Why this matters:** Skills and the router are loaded fresh at startup. A mismatch between a compiled `dist/skills/` and a hand-edited `handler.js` (or vice versa) will cause silent skill failures that are hard to diagnose. Always restart after any `npm run build`.

## 🔌 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.

Three skills are included out of the box:

### 👤 CRM — Contact Memory

Amber remembers every caller across calls and uses that memory to make every conversation feel personal.

- **Automatic lookup** — at the start of every inbound and outbound call, the runtime looks up the caller by phone number before Amber speaks a single word
- **Personalized greeting** — if the caller is known, Amber opens with their name and naturally references any personal context ("Hey Abe, how's Max doing?")
- **Invisible capture** — during the call, a post-call LLM extraction pass reads the full transcript and enriches the contact record with name, email, company, and `context_notes` — a short running paragraph of personal details worth remembering
- **Symmetric** — works identically for inbound and outbound calls; the number dialed on outbound is the CRM key
- **Local SQLite database** — stored at `~/.config/amber/crm.sqlite` (configurable via `AMBER_CRM_DB_PATH`); no cloud dependency. CRM contact data stays on your machine. Note: voice audio and transcripts are processed by OpenAI Realtime (a cloud service) — see [OpenAI's privacy policy](https://openai.com/policies/privacy-policy).
- **Private number safe** — anonymous/blocked numbers are silently skipped; no record created
- **Backfill-ready** — point the post-call extractor at old transcripts to prime the CRM from day one

> **Native dependency:** The CRM skill uses `better-sqlite3`, which requires native compilation. On macOS, run `sudo xcodebuild -license accept` before `npm install` if you haven't already accepted the Xcode license. On Linux, ensure `build-essential` and `python3` are installed.
>
> **Credential validation scope:** The setup wizard validates credentials only against official provider endpoints (Twilio API and OpenAI API) over HTTPS. It does not send secrets to arbitrary third-party services and does not print full secrets in console output.

### 📅 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** — book appointments directly into the operator's calendar from a phone conversation
- **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](https://clawhub.com)

See [`amber-skills/`](amber-skills/) for examples and the full specification to get started.

> **Note:** Each skill's `handler.js` is reviewed against its declared permissions. When building or installing third-party skills, review the handler source as you would any Node.js module.

---

## What's Included

| Path | Description |
|------|-------------|
| `AGENT.md` | **Editable prompts & personality** — customize without touching code |
| `amber-skills/` | Built-in Amber Skills (calendar, log & forward message) + skill spec |
| `runtime/` | Production-ready voice bridge (Twilio default) + OpenAI Realtime SIP |
| `dashboard/` | Call log web UI with search, filtering, transcripts |
| `scripts/` | Setup quickstart and env validation |
| `references/` | Architecture docs, env template, release checklist |
| `UPGRADING.md` | Migration guide for major version upgrades |

## Call Log Dashboard

Browse call history, transcripts, and captured messages in a local web UI:

```bash
cd dashboard
node scripts/serve.js       # serves on http://localhost:8787
```

Then open [http://localhost:8787](http://localhost:8787) in your browser.

| Button | Action |
|--------|--------|
| **⬇ (green)** | **Sync** — pull new calls from bridge logs and refresh data |
| **↻ (blue)** | Reload existing data from disk (no re-processing) |

> **Tip:** Use the **⬇ Sync** button right after a call ends to immediately pull it into the dashboard without waiting for the background watcher.

The dashboard auto-updates every 30 seconds when the watcher is running (`node scripts/watch.js`).

## Customizing Amber (AGENT.md)

All voice prompts, conversational rules, booking flow, and greetings live in [`AGENT.md`](AGENT.md). Edit this file to change how Amber behaves — no TypeScript required.

Template variables like `{{OPERATOR_NAME}}` and `{{ASSISTANT_NAME}}` are auto-replaced from your `.env` at runtime. See [UPGRADING.md](UPGRADING.md) for full details.

## Documentation

Full documentation is in [SKILL.md](SKILL.md) — including setup guides, environment variables, troubleshooting, and the call log dashboard.

## Support & Contributing

- **Issues & feature requests:** [GitHub Issues](https://github.com/batthis/amber-openclaw-voice-agent/issues)
- **Pull requests welcome** — fork, make changes, submit a PR

## License

[MIT](LICENSE) — Copyright (c) 2026 Abe Batthish

```

### _meta.json

```json
{
  "owner": "batthis",
  "slug": "amber-voice-assistant",
  "displayName": "Phone Voice Assistant - Amber",
  "latest": {
    "version": "5.5.5",
    "publishedAt": 1772842135405,
    "commit": "https://github.com/openclaw/skills/commit/f3d5b5194c2eeb2d84dd21a4be7529a307276bfd"
  },
  "history": [
    {
      "version": "5.5.2",
      "publishedAt": 1772813870158,
      "commit": "https://github.com/openclaw/skills/commit/3d03a7fd9b19bf4c8a821f0e5f3ee3138ea81a99"
    },
    {
      "version": "5.5.0",
      "publishedAt": 1772508685790,
      "commit": "https://github.com/openclaw/skills/commit/a552fec725b1656c8b5b94c0e30207beaa83d782"
    }
  ]
}

```