Voice Agent: Setup & Settings

The four places settings live

Your voice agent reads from four sources, in this order. Each one wins over the next.

The first install (3 minutes)

1. Generate an install token in the voice portal. Pick the version (default is Stable; pin to a test build only if you're testing a release candidate).
2. Run the install command on a Linux host (Ubuntu, Debian, or any modern distro). Same host as your OpenClaw agent:

   curl -sSL https://api.talktomyagent.io/install.sh | \
     bash -s -- --token <YOUR_TOKEN> --accept-license

3. Wait ~30 seconds. The installer downloads the gateway binary, sets up a Cloudflare tunnel, writes config.json with your defaults, seeds the voice playbook, and starts the service. Output shows a check mark for each step.
4. Place a test call from your owner phone. The agent should greet you in private mode immediately.

What you have on disk afterward

~/ninja-talk/                         ← install dir
  config.json                         ← operator settings (this guide)
  .env                                ← secrets + identity (don't edit)
  ninja-talk                          ← the gateway binary
  start.sh                            ← what systemd runs
  sync-config.sh                      ← pull cloud-managed settings
  integrations/                       ← optional direct-API configs
  install-meta.json                   ← installer-recorded metadata

config.json - the main operator surface

Open ~/ninja-talk/config.json with nano on the server and you see something like this:

{
  "schemaVersion": 1,

  "callMode": "private",
  "ownerPhone": "+16478359044",
  "greetingPrompt": "Hi {name}, what can I do for you?",
  "voice": "Callirrhoe",
  "language": "auto",
  "sharePrivateVoiceWithMainDm": true,
  "mainDmSourceKey": null,
  "recordingEnabled": true,
  "maxCalls": 2,
  "callTimeoutMinutes": 60,
  "idleTimeoutSeconds": 120,

  "audio":    { /* outbound pipeline tuning, VAD, watchdogs */ },
  "context":  { /* which workspace files load into the prompt */ },
  "features": { /* gateway-side capability toggles */ }
}

Three groups of fields, three different rules:

• Top-level flat fields (callMode, voice, greetingPrompt, …)
  Cloud-managed. Edit them in the voice portal - running ~/ninja-talk/sync-config.sh overwrites these from the dashboard. Hand edits on the box survive a single restart but get overwritten on the next sync.
• The three nested sections (audio, context, features)
  Local only. The sync script never touches them; cloud changes never overwrite them. Edit them directly on the server and they survive everything except a hand rm config.json.
• schemaVersion
  Don't change. The installer bumps this when the schema evolves so old configs migrate cleanly.

audio - outbound pipeline tuning

Eleven knobs that control how the gateway prepares the model's voice for the phone-line codec. Defaults are tuned for a typical realtime voice model + carrier + a typical PSTN path - change them per-deployment if a particular voice or carrier line needs adjustment.

The knobs you'll actually touch

Advanced (rarely changed)

The fade chain, large-step adaptive smoother, and audio mode are stable defaults from field-tuning across many calls. Touch only if audio analysis shows a specific defect:

Out-of-range or non-numeric values fall back to the default - bad values can't kill calls.

context - which workspace files load into every call

The voice agent inherits the same identity and memory as your OpenClaw agent by reading four files from ~/.openclaw/workspace/ at the start of every call:

• SOUL.md - voice and personality
• IDENTITY.md - name, role, who the agent is
• USER.md - the owner's profile (private mode only)
• MEMORY.md - long-term memory (contacts, preferences, learned facts)

By default all four load when present. The context.files field lets you include or exclude any of them per-deployment - useful for measuring prompt-size impact on first-token latency, or for trimming a giant MEMORY.md out of the prompt on a low-context test bot.

Default (everything loads)

"context": {
  "files": ["SOUL.md", "IDENTITY.md", "USER.md", "MEMORY.md"]
}

Drop MEMORY.md to trim the prompt

"context": {
  "files": ["SOUL.md", "IDENTITY.md", "USER.md"]
}

On a typical bot this drops 8-10 KB from the system instruction (roughly 2,000-2,500 tokens), which usually saves 100-300 ms on first-token latency.

features - gateway capability toggles

On/off flags that control which capabilities the gateway offers per-call. All default to a safe, fully-functional baseline.

Apply changes - edit, then restart

config.json is read at service start. To apply an edit, restart the service:

# 1. SSH to your server, then edit:
sudo -u <openclaw-user> nano ~/ninja-talk/config.json

# 2. Restart (user-scope service - most common):
sudo -u <openclaw-user> systemctl --user restart ninja-talk

# 3. Verify the new value reached the gateway:
sudo journalctl --user -u ninja-talk -n 20 --no-pager | grep -E "GAIN_TRIM|VAD_SILENCE|context"

If your service runs at the system level, replace step 2 with:

sudo systemctl restart ninja-talk

Sanity-check after a change

The gateway logs the effective values on startup and the assembled system instruction at the start of every call. After a restart, the next call will print:

[ninja-talk:context] System instruction built {
  mode: "private",
  totalBytes: 22628,           ← drops if you removed MEMORY.md from context.files
  agentName: "Donna",
  hasMemory: true,             ← false when MEMORY.md is excluded
  hasPlaybook: true,
  truncated: false,
  stubMode: false
}

Cloud sync - what comes from the portal

Running ~/ninja-talk/sync-config.sh (or ninja-talk sync from the CLI) pulls the latest cloud-managed fields from the voice portal and merges them into your config.json. The sync explicitly preserves your local audio, context, and features sections - they are never touched.

Fields the sync overwrites

• callMode, ownerPhone, greetingPrompt, voice, language
• recordingEnabled, maxCalls, callTimeoutMinutes, idleTimeoutSeconds
• sharePrivateVoiceWithMainDm, mainDmSourceKey

Fields the sync leaves alone

• audio.* - every audio knob
• context.files
• features.* - every feature toggle
• schemaVersion

.env - secrets and identity (don't edit)

~/ninja-talk/.env holds the things you should never edit by hand: deployment credentials, the API base URL, the Cloudflare tunnel token reference, and your installer-bound machine fingerprint. The installer regenerates this file on every re-install; nothing operator-tunable lives here.

If you suspect a credential is wrong, the fix is always “re-run install.sh with a fresh token” - never hand-edit .env.

Quick reference: where to change what

Troubleshooting

Companion guides

• Private & Public Mode - how the agent decides who's allowed to do what on a call.
• Tools & Skills - what the agent can do (email, calendar, direct API integrations) and how to add capabilities.