Configuration

goClaw uses YAML configuration files for all agent settings. Changes to config files are hot-reloaded in development mode. In production, restart the agent process after changes.

Agent Configuration (config/agent.yaml)

This is the primary agent configuration file. It defines who your agent is and what it's trying to do.

agent:
  name: "Aria"
  persona: |
    You are Aria, an outbound sales development representative for Acme Corp.
    You are direct, professional, and focused on qualifying leads efficiently.
    You never pretend to be human — you are an AI SDR.

  goals:
    - Identify qualified prospects for the Acme platform
    - Schedule discovery calls with qualified leads
    - Maintain accurate CRM records for every interaction
    - Follow up on stalled conversations within 3 business days

  behaviors:
    follow_up_delay_days: 3
    max_follow_ups: 3
    research_before_outreach: true
    personalization_depth: "company_and_role"  # minimal | company_and_role | deep

  llm:
    primary: "claude-sonnet-4-6"       # primary reasoning
    fast: "claude-haiku-4-5"           # classification, CRM ops, short tasks
    research: "gpt-4o-mini"            # web search queries
    batch_eligible: true               # enable 50% batch discount for async tasks

Persona guidelines

The persona field is injected into every agent prompt. Keep it:

• Specific about role and company context
• Clear about AI disclosure (required)
• Focused on behaviors, not capabilities

Goals

Goals are injected alongside the persona. Write them as actionable objectives, not abstract principles. The agent references these when deciding whether to take action.

Channel Configuration (config/channels.yaml)

channels:
  email:
    enabled: true
    provider: resend
    from_name: "Aria from Acme"
    from_address: "aria@acme.com"
    signature: |
      Aria
      AI Sales Development Representative, Acme Corp
      aria@acme.com

    imap:
      host: "imap.gmail.com"
      port: 993
      user: "${IMAP_USER}"
      password: "${IMAP_PASSWORD}"
      check_interval_minutes: 5

  sms:
    enabled: true
    provider: twilio
    from_number: "${TWILIO_PHONE_NUMBER}"
    opt_out_keywords: ["STOP", "UNSUBSCRIBE"]

  whatsapp:
    enabled: false

  telegram:
    enabled: false

Environment variables (prefixed with ${}) are resolved at startup. Never commit credentials directly to channels.yaml.

Adding a custom channel

goClaw's channel interface is pluggable. To add a custom channel:

1. Implement the Channel interface from @clawrm/channels:

   interface Channel {
     send(to: string, message: string, context: MessageContext): Promise<SendResult>;
     listen(handler: MessageHandler): Promise<void>;
     normalize(raw: RawMessage): NormalizedMessage;
   }
   

2. Register it in your channel registry

3. Add a config block under channels: in channels.yaml

Permissions (config/permissions.yaml)

groups:
  default:
    description: "Standard agent group"
    knowledge_mounts:
      - ./knowledge/public
      - ./knowledge/products
    tool_allowlist:
      - crm_search
      - crm_get_contact
      - crm_create_contact
      - crm_add_note
      - web_search
      - send_email
      - send_sms
    sandbox:
      filesystem: read_only
      network: allow
      container: false

  admin:
    description: "Admin access group — humans only"
    knowledge_mounts:
      - ./knowledge
    tool_allowlist: "*"
    sandbox:
      filesystem: read_write
      network: allow
      container: false

See Permission System for full documentation on group isolation and container mode.

Knowledge Base initialization

The knowledge base lives in ./knowledge/. Files are plain Markdown with optional YAML frontmatter.

knowledge/
├── company.md          # Company overview, values, key facts
├── products/
│   ├── platform.md     # Product descriptions
│   └── pricing.md      # Pricing information
├── objections.md       # How to handle common objections
└── icp.md             # Ideal customer profile

On startup, the agent indexes all knowledge files into SQLite FTS5 for fast retrieval. The agent accesses knowledge through the knowledge_search MCP tool.

Seeding knowledge

Use @clawrm/cli to seed knowledge from common sources:

# Import from a URL
npx @clawrm/cli knowledge import --url https://your-docs.com

# Import from a directory of Markdown files
npx @clawrm/cli knowledge import --dir ./docs

# Import from a Notion database (requires Notion API key)
npx @clawrm/cli knowledge import --notion --database-id <id>

Environment variables reference

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	Claude API key for agent reasoning
RESEND_API_KEY	If email	Resend transactional email API key
IMAP_HOST	If email	IMAP server for reading inbound email
IMAP_USER	If email	IMAP login username
IMAP_PASSWORD	If email	IMAP login password
TWILIO_ACCOUNT_SID	If SMS/WA	Twilio account SID
TWILIO_AUTH_TOKEN	If SMS/WA	Twilio auth token
TWILIO_PHONE_NUMBER	If SMS	Twilio phone number (E.164 format)
TELEGRAM_BOT_TOKEN	If Telegram	Bot token from @BotFather
OPENAI_API_KEY	Optional	GPT-4o-mini for web search synthesis
PORT	Optional	Admin dashboard port (default: 3000)
NODE_ENV	Optional	development or production