---
name: openclaw-create-agent
description: Create a new OpenClaw agent with Discord integration -- directory setup, bootstrap files, config update, and verification on the homelab server.
---

# Create OpenClaw Agent

## When to Use

- User asks to create/add a new OpenClaw agent
- User wants to connect a new AI bot to Discord via OpenClaw
- User says "create agent", "add agent", "new bot" in the context of OpenClaw

Do NOT use for modifying existing agents -- use the `openclaw` skill instead.

---

## Environment

- Server: `yiukai@192.168.68.108`
- Config: `/home/yiukai/.openclaw/openclaw.json` (JSON, hot-reloads on save)
- Home: `/home/yiukai/.openclaw/`
- Owner Discord ID: `964122056163721286`
- Default model: `kimi-coding/k2p5`
- All commands run via `ssh yiukai@192.168.68.108 '<command>'`

---

## Required Input

Gather ALL before starting. Ask the user for any missing items:

| Item | Required | Default | Example |
|------|----------|---------|---------|
| Agent ID | Yes | -- | `xhs-creator` (lowercase, hyphenated) |
| Display Name | Yes | -- | `小红薯` |
| Discord Bot Token | Yes | -- | `MTQ4NTMw...` |
| Guild ID | Yes | -- | `1485305839379021871` |
| Channel ID | Yes | -- | `1485305839828074620` |
| Purpose | Yes | -- | `小红书内容创作、话题分析` |
| Require Mention | No | `false` | `true` for shared channels |
| Model | No | `kimi-coding/k2p5` | `google-antigravity/claude-opus-4-6-thinking` |

Remind user of Discord bot prerequisites if they don't have a token yet:
1. https://discord.com/developers/applications > New Application
2. Bot page > Reset Token > copy
3. Enable **Message Content Intent** (Privileged Gateway Intents)
4. OAuth2 > URL Generator > scope `bot` > permissions: Send Messages, Read Message History, Add Reactions
5. Invite bot to the target server using the generated URL

---

## Procedure

### Step 1: Pre-flight Checks

Decode the bot user ID from the token's first segment (before first `.`):

```bash
echo "FIRST_SEGMENT" | base64 -d
```

Then verify the agent doesn't already exist:

```bash
ssh yiukai@192.168.68.108 'node -e "
const cfg = JSON.parse(require(\"fs\").readFileSync(\"/home/yiukai/.openclaw/openclaw.json\", \"utf8\"));
const exists = cfg.agents.list.some(a => a.id === \"AGENT_ID\");
console.log(exists ? \"CONFLICT: agent already exists\" : \"OK: agent ID available\");
"'
```

If CONFLICT, stop and ask user to choose a different ID or confirm they want to update the existing agent.

### Step 2: Create Directories

```bash
ssh yiukai@192.168.68.108 "mkdir -p ~/.openclaw/workspace-AGENT_ID ~/.openclaw/agents/AGENT_ID/agent"
```

### Step 3: Write AGENTS.md

Write to `/home/yiukai/.openclaw/workspace-AGENT_ID/AGENTS.md` via SSH heredoc.
IMPORTANT: All .md bootstrap files go in the WORKSPACE directory, NOT agentDir. agentDir only stores JSON config files (auto-managed by OpenClaw).

Tailor content to the agent's purpose. Every AGENTS.md must include:

1. **Identity statement** -- one sentence: who the agent is and what it specializes in
2. **Core capabilities** -- 3-5 numbered sections with concrete descriptions
3. **Workflow or output templates** -- structured format the agent should follow when producing output
4. **Constraints** -- what the agent must NOT do

Use the user's stated purpose to generate domain-specific content. Do NOT use generic placeholder text.

### Step 4: Write SOUL.md

Write to `/home/yiukai/.openclaw/workspace-AGENT_ID/SOUL.md` via SSH heredoc.

Keep it short (20-30 lines). Must include:

1. **Identity** -- one-line character description
2. **Tone** -- 3-4 bullet points on communication style
3. **Language** -- specify primary language (usually Chinese)
4. **Boundaries** -- 3-4 things the agent refuses to do

### Step 5: Update Config

Use a single Node.js script via SSH to atomically update all three config sections. The script must:

1. Read the current config
2. Add agent entry to `agents.list`
3. Add Discord account to `channels.discord.accounts`
4. Add binding to `bindings`
5. Write back

```bash
ssh yiukai@192.168.68.108 'node -e "
const fs = require(\"fs\");
const path = \"/home/yiukai/.openclaw/openclaw.json\";
const cfg = JSON.parse(fs.readFileSync(path, \"utf8\"));

// --- Agent ---
cfg.agents.list.push({
  id: \"AGENT_ID\",
  name: \"AGENT_ID\",
  workspace: \"/home/yiukai/.openclaw/workspace-AGENT_ID\",
  agentDir: \"/home/yiukai/.openclaw/agents/AGENT_ID/agent\",
  model: \"MODEL\",
  identity: { name: \"DISPLAY_NAME\" },
  groupChat: {
    mentionPatterns: [
      \"<@!?BOT_USER_ID>\",
      \"DISPLAY_NAME\",
      \"SHORT_ALIAS\",
      \"BOT_USER_ID\"
    ]
  }
});

// --- Discord Account ---
cfg.channels.discord.accounts[\"AGENT_ID\"] = {
  name: \"DISPLAY_NAME\",
  enabled: true,
  token: \"FULL_BOT_TOKEN\",
  groupPolicy: \"open\",
  streaming: \"off\",
  guilds: {
    \"GUILD_ID\": {
      requireMention: REQUIRE_MENTION_BOOL,
      users: [\"964122056163721286\", \"BOT_USER_ID\"],
      channels: { \"CHANNEL_ID\": { allow: true } }
    }
  }
};

// --- Binding ---
cfg.bindings.push({
  agentId: \"AGENT_ID\",
  match: { channel: \"discord\", accountId: \"AGENT_ID\" }
});

fs.writeFileSync(path, JSON.stringify(cfg, null, 2));
console.log(\"OK: config updated\");
"'
```

Substitute ALL placeholders before executing. Never leave template variables in the actual command.

### Step 6: Verify

Wait 5 seconds for hot-reload, then check logs:

```bash
ssh yiukai@192.168.68.108 'journalctl --user -u openclaw-gateway --since "30 sec ago" --no-pager 2>&1 | grep -iE "AGENT_ID|error|reload"'
```

**Success indicators** (all three must appear):
- `[reload] config change detected` -- hot-reload triggered
- `[discord] [AGENT_ID] starting provider` -- bot connected to Discord
- `channels resolved: GUILD_ID/CHANNEL_ID` -- channel mapped successfully

**If hot-reload fails**, restart manually:

```bash
ssh yiukai@192.168.68.108 'systemctl --user restart openclaw-gateway'
```

Then recheck logs.

**If bot fails to connect**, common causes:
- Bot not invited to server -- remind user to use OAuth2 invite link
- Message Content Intent not enabled -- user must enable in Developer Portal
- Invalid token -- ask user to regenerate

### Step 7: Report to User

Summarize:
- Agent ID and display name
- Discord server and channel (by name if visible in logs)
- Mention requirement
- Model
- Next step: send a test message in the Discord channel

---

## Optional: Add Cron Job

If the user wants scheduled tasks:

```bash
ssh yiukai@192.168.68.108 'node -e "
const fs = require(\"fs\");
const path = \"/home/yiukai/.openclaw/openclaw.json\";
const cfg = JSON.parse(fs.readFileSync(path, \"utf8\"));
if (!cfg.cron) cfg.cron = { enabled: true, entries: [] };
if (!cfg.cron.entries) cfg.cron.entries = [];
cfg.cron.entries.push({
  name: \"JOB_NAME\",
  schedule: \"CRON_EXPRESSION\",
  timezone: \"Europe/Stockholm\",
  agentId: \"AGENT_ID\",
  message: \"TASK_PROMPT\",
  deliver: { channel: \"discord\", target: \"channel:CHANNEL_ID\" }
});
fs.writeFileSync(path, JSON.stringify(cfg, null, 2));
console.log(\"OK: cron job added\");
"'
```

## Optional: Enable Agent-to-Agent Communication

1. Add agent ID to `tools.agentToAgent.allow` array
2. Set `subagents.allowAgents` on the calling agent
3. Set `requireMention: true` on all collaborating agents in the shared guild