Customizing the Voice Playbook

The playbook is a single Markdown file that the voice gateway reads at the start of every call. It tells the AI how to greet callers, what to do while looking things up, how to handle outbound calls, and any patterns it has learned from past conversations.

The default location is:

~/.openclaw/workspace/protocols/dojo-voice-agent-playbook.md

This file is created automatically when you install the Voice Agent skill. The installer sets overwrite: false, which means future skill updates and redeployments will never erase your edits. Once the file exists, it is yours to customize.

The gateway recognizes several ## heading sections. Each one controls a different aspect of call behavior. Sections not relevant to the current call mode are automatically filtered out -- for example, a private call only sees the ## Private Mode section, not ## Public Mode or ## Outbound Mode.

There are two ways to edit the playbook:

ssh your-server
nano ~/.openclaw/workspace/protocols/dojo-voice-agent-playbook.md

The ## Outbound Mode section supports named script profiles under a ### Script profiles subsection. Each profile is a #### heading followed by instructions for that specific type of call.

When an outbound call is triggered, the system can specify a script parameter. The gateway looks for a matching #### profile-name heading in the playbook. If found, the bot follows that profile. If not found, it falls back to the general outbound guidance -- the call still goes through.

Two profiles are included by default:

#### appointment-confirmation
Brief + direct. Identify yourself, state the appointment specifics,
ask "is this still good for you?", log the answer, thank them,
end_call. 30-60s for a confirm; ~2 min for a reschedule.

#### sales-discovery
Initial discovery for the owner's offering. Understand what brought
the prospect, identify the pain, match one feature, close on a
follow-up or end gracefully. Lead with questions.

Add your own profiles by creating new #### headings under the Script profiles subsection. Profile names must be lowercase alphanumeric with hyphens or underscores (for example, debt-collection or survey_followup).

By default, the gateway reads the playbook from the standard path. If you need to use a different file -- for example, a seasonal variant or an A/B test -- you can override the path in your config.json:

{
  "context": {
    "voicePlaybook": "protocols/holiday-playbook.md"
  }
}

The path is relative to the workspace directory (~/.openclaw/workspace/). The file must end in .md and must stay inside the workspace -- paths that escape with .. are rejected.

Set voicePlaybook to null (or remove the key entirely) to revert to the default path.

Customizing the greeting. Open the playbook and find the ## Greeting section. Replace or modify the example lines:

## Greeting

The call just connected. You speak first.

- **OWNER_AUTH block is present**: "Hey boss, what do you need?"
- **CRM block has caller info**: greet them by name and mention
  their company if you know it.
- **Neither**: "Thank you for calling Acme Corp, this is Alex.
  How can I help you today?"

Adding a debt collection script. Add a new #### profile under ### Script profiles in the Outbound Mode section:

#### payment-reminder
Polite but firm. Identify yourself, reference the invoice number
and amount from the Facts block, ask if they can confirm a payment
date. If they dispute: note it, do not argue, tell them the owner
will follow up. Keep under 2 minutes.

Adding learned patterns manually. While the bot maintains this section automatically, you can seed it with patterns you already know:

## Learned Patterns

- Callers asking about "the Monday special" are referring to our
  weekly 20% discount on consulting hours.
- When someone says "transfer me to billing," they usually need
  an invoice resent. Check email history first.
- Spanish-speaking callers prefer a slower pace. Pause after each
  sentence.

• Your edits are safe. The playbook is installed with overwrite: false. Skill updates and redeployments create the file only if it does not exist. Once you have edited it, those edits persist through updates.
• Changes are instant. The gateway reads the playbook fresh at the start of each call. Save the file and the next call uses it. No service restart needed.
• Security rules still apply. The gateway appends its own security and operational rules after the playbook. You cannot override those rules from the playbook -- they are non-negotiable platform-level protections (impersonation blocking, prompt injection defense, data isolation between callers).
• Budget limit. The entire system instruction (identity files + playbook + security rules) must fit within 32 KB. If the playbook pushes the total over budget, the gateway trims the Learned Patterns section first, then truncates the playbook tail. Keep each section focused.
• Persona lives in SOUL.md, not the playbook. The playbook controls call-handling behavior. Your agent's personality, name, and tone come from SOUL.md and IDENTITY.md (or the dashboard personality field). Edit those to change who the agent is. Edit the playbook to change what the agent does on calls.