name: winclaw-agents description: Create, configure, and manage AI agents in WinClaw/WinClaw. Use when the user asks to add a new agent, change agent model, set agent workspace, configure agent identity/personality, manage agent bindings to channels, set thinking level, timeout, concurrency, context management, heartbeat schedule, or any agent-related settings. metadata: { "winclaw": { "emoji": "🤖" } }

WinClaw Agent Management

Create, configure, and manage AI agents and their settings.

List agents

curl -s http://127.0.0.1:18789/__winclaw__/api \
  -d '{"method":"agents.list","params":{}}'

Create an agent

curl -s http://127.0.0.1:18789/__winclaw__/api \
  -d '{
    "method": "agents.create",
    "params": {
      "name": "Research Assistant",
      "workspace": "~/.winclaw/agents/research"
    }
  }'

Creates agent directory with IDENTITY.md and adds to config. Returns agentId.

Update an agent

curl -s http://127.0.0.1:18789/__winclaw__/api \
  -d '{
    "method": "agents.update",
    "params": {
      "agentId": "research_assistant",
      "model": "anthropic/claude-sonnet-4-5"
    }
  }'

Delete an agent

curl -s http://127.0.0.1:18789/__winclaw__/api \
  -d '{
    "method": "agents.delete",
    "params": {
      "agentId": "research_assistant",
      "deleteFiles": false
    }
  }'

Cannot delete the "default" agent.

Manage agent files

# List files
curl -s http://127.0.0.1:18789/__winclaw__/api \
  -d '{"method":"agents.files.list","params":{"agentId":"default"}}'

# Read a file (AGENTS.md, TOOLS.md, MEMORY.md, IDENTITY.md)
curl -s http://127.0.0.1:18789/__winclaw__/api \
  -d '{"method":"agents.files.get","params":{"agentId":"default","filename":"IDENTITY.md"}}'

# Write a file
curl -s http://127.0.0.1:18789/__winclaw__/api \
  -d '{"method":"agents.files.set","params":{"agentId":"default","filename":"IDENTITY.md","content":"# My Agent\nYou are a helpful assistant."}}'

Agent defaults (config)

These live at agents.defaults and apply to all agents unless overridden per-agent.

Model settings

Reasoning & behavior

Heartbeat

Context management

Typing indicator

Options: never, instant, thinking, message.

Agent bindings

Bind agents to specific channels or accounts via config:

{
  "agents": {
    "bindings": [
      {
        "agentId": "support_bot",
        "channel": "discord",
        "guildId": "123456"
      },
      {
        "agentId": "sales_agent",
        "channel": "slack",
        "teamId": "T012345"
      }
    ]
  }
}

Per-agent overrides

In agents.list[], each agent can override defaults:

{
  "agents": {
    "list": [
      {
        "id": "research",
        "name": "Research Agent",
        "workspace": "~/.winclaw/agents/research",
        "model": "anthropic/claude-sonnet-4-5",
        "default": false
      }
    ]
  }
}

Workflow

1. Ask what the user wants (new agent, modify existing, change defaults).
2. For new agents: ask for name, purpose, and optionally a model preference.
3. Call agents.create with name and workspace.
4. Optionally write IDENTITY.md with custom personality/instructions.
5. If binding to a channel, patch agents.bindings in config.
6. Confirm creation and explain how to use the agent.

Examples

"Create a coding agent that uses Sonnet"

1. agents.create name="Coding Agent", workspace auto-assigned.
2. agents.update model="anthropic/claude-sonnet-4-5".
3. Write IDENTITY.md with coding-focused instructions.

"Make my bot think more before answering" → Patch: {"agents":{"defaults":{"thinkingDefault":"high"}}}

"Set heartbeat to every hour during business hours" → Patch:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "1h",
        "activeHours": { "start": "09:00", "end": "18:00", "tz": "Asia/Tokyo" }
      }
    }
  }
}