How to Invoke a Mira Custom Agent (Step-by-Step)

OpenClaw supports multiple named agents — each with its own persona, tools, and model. Invoking a Mira custom agent is a two-part process: define the agent in config, then trigger it via CLI, cron, or API. This guide covers both paths.

Step 1: Verify your OpenClaw installation

Open a terminal and run:

openclaw --version

You should see a version like v2025.x.x. If the command isn't found, install OpenClaw first:

npm install -g openclaw@latest

Step 2: Define your custom agent in openclaw.json

Open ~/.openclaw/openclaw.json (or wherever your config lives). Add a named agent entry under the agents array:

{
  "agents": [
    {
      "id": "mira",
      "name": "Mira",
      "model": "anthropic/claude-sonnet-4-5",
      "systemPrompt": "You are Mira, a proactive AI partner running on OpenClaw..."
    }
  ]
}

Key fields: id (used in CLI and cron), systemPrompt (the agent's persona and instructions), and optionally model to override the default.

Step 3: Start the OpenClaw Gateway

The Gateway is the runtime that handles agent sessions. Make sure it's running:

openclaw gateway status

If it's not running, start it:

openclaw gateway start

For always-on deployments (Mac mini, server), install it as a launchd daemon so it starts automatically on boot.

Step 4: Invoke the agent via CLI

The fastest way to invoke a Mira custom agent is a direct CLI call:

openclaw session send --agent mira --message "Summarize my email inbox"

Replace mira with your agent's id and the message with your prompt. The response streams to stdout.

For a one-shot background run (no wait for output):

openclaw session send --agent mira --message "Run daily digest" --background

Step 5: Invoke the agent via cron (unattended)

For scheduled or recurring invocations, use OpenClaw's built-in cron system. Create a job with these fields:

{
  "name": "Daily Mira digest",
  "schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "America/Los_Angeles" },
  "payload": {
    "kind": "agentTurn",
    "message": "Run my morning digest",
    "agentId": "mira"
  },
  "sessionTarget": "isolated"
}

sessionTarget options:

• isolated — fresh ephemeral session per run (recommended for most automation tasks)
• session:<id> — persistent named session with memory continuity across runs
• current — binds to the session that created the job (useful for interactive flows)

Step 6: Verify the invocation succeeded

Check run history in the OpenClaw UI:

openclaw tasks

Or via the cron API — call GET /api/cron/runs?jobId=<id>. A status: completed entry with non-empty output confirms the agent ran successfully.

Common issues

Summary

To invoke a Mira custom agent:

1. Define the agent in openclaw.json with a unique id and systemPrompt
2. Start the Gateway
3. Use openclaw session send --agent <id> for one-off invocations
4. Create a cron job with payload.kind=agentTurn for scheduled runs
5. Check run history to confirm success