OpenClaw — Specialist Agent Setup Guide

Complete walkthrough for creating a dedicated specialist agent. Uses kLinked (LinkedIn Intelligence) as the reference implementation.

---

Architecture Overview

Discord Server: KLinked HQ
      ↓
Discord Bot: kLinked (separate bot token)
      ↓
OpenClaw Binding (accountId: klinked)
      ↓
Agent: klinked
      ↓
Workspace: ~/.openclaw/workspace-klinked

Each agent has its own agentId, workspace, Discord bot token, and accountId. Completely isolated unless you explicitly enable agent-to-agent communication.

---

Part 1: Agent Creation

Step 1 — Create the Agent

openclaw agents add klinked

When prompted:

• Copy auth profiles? → Yes (reuses existing API key)

• Configure model/auth? → No (inherits from main)

• Configure chat channels? → No (configure manually)

Step 2 — Verify

openclaw agents list

You should see both main and klinked listed.

---

Part 2: Workspace Structure

Step 3 — Official Structure

Per docs.openclaw.ai/concepts/agent-workspace:

~/.openclaw/workspace-klinked/
├── SOUL.md          ← agent identity
├── AGENTS.md        ← workspace guide
├── USER.md          ← human context
├── TOOLS.md         ← env specifics (optional)
├── HEARTBEAT.md     ← periodic tasks
├── memory/          ← daily logs + MEMORY.md
└── skills/          ← workspace-specific skills

⚠️ No official data/ or templates/ folders. Custom data and templates go inside skills/ as skill modules.

Step 4 — Create Directory Structure

mkdir -p ~/.openclaw/workspace-klinked/{memory,skills}

---

Step 5 — SOUL.md (Agent Identity)

nano ~/.openclaw/workspace-klinked/SOUL.md

Template:

# SOUL.md

You are [AgentName].

## Specialisation
[One sentence on what this agent does]

## Tone
[How the agent communicates — e.g. direct, strategic, no filler]

## Core Capabilities
- [Capability 1]
- [Capability 2]

## Hard Rules
- Never [X] without explicit confirmation
- Always [Y]

✅ Keep it lean and specific. Avoid generic assistant language.

---

Step 6 — AGENTS.md (Workspace Guide)

# AGENTS.md

## Session Startup
1. Read SOUL.md
2. Read USER.md
3. Read memory/YYYY-MM-DD.md (today's log)

## Memory Rules
Write things down. Mental notes don't survive restarts.

## Platform Formatting
Discord: no tables, use bullets, wrap links in <>

## Safety
Never post to [platform] without explicit confirmation.

---

Step 7 — USER.md (Human Context)

For a career/LinkedIn agent, populate with:

• Full name and location

• Current role and company

• Years of experience

• Core skills and technologies

• Certifications

• Education

• Personal projects

• Job search status and target role

• Posting tone preferences

✅ The richer USER.md is, the more personalised every response. This is the most important file for a specialist agent.

---

Step 8 — HEARTBEAT.md (Periodic Tasks)

# HEARTBEAT.md

## Daily
- Check skills/ for newly installed skills
- Review USER.md — any fields still blank?
- Check memory/ — unresolved follow-ups?

## Weekly
- Refresh trending skills data
- Suggest 3 content ideas based on recent work

## Proactive Alerts
Reach out if:
- A significant new trend emerges worth posting about
- It's been more than 5 days since last content was drafted

## Stay Quiet When
- Nothing has changed
- Late night (23:00 - 08:00 local time)

If nothing needs attention, reply HEARTBEAT_OK.

---

Part 3: Discord Setup

Step 9 — Create a New Discord Server

Create a dedicated server for the specialist agent. Keeps it isolated and avoids routing conflicts.

Suggested channels for a LinkedIn/career agent:

• Core: #profile-review, #networking, #posting, #job-finder, #content-ideas

• Ops: #strategy, #automation, #logs

Note down the Guild ID. Enable Developer Mode in Discord settings → right-click server → Copy Server ID.

---

Step 10 — Create a Second Discord Bot

Go to discord.com/developers/applications:

1. Create New Application → name it (e.g. kLinked)

2. Bot tab → Reset Token → copy the token

3. Enable: Message Content Intent, Server Members Intent

4. Permissions: Send Messages, Read Message History, Attach Files, Embed Links

5. OAuth2 → URL Generator → select bot + permissions → copy invite URL

6. Open invite URL → add bot to your new server

⚠️ Keep both bot tokens safe. You need them in openclaw.json.

---

Part 4: openclaw.json Configuration

Step 11 — Multi-Bot Config Structure

OpenClaw validates config strictly — unknown keys cause the gateway to refuse to start.

{
  "agents": {
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace"
      },
      {
        "id": "klinked",
        "workspace": "~/.openclaw/workspace-klinked",
        "tools": {
          "allow": [
            "browser", "web_fetch", "web_search",
            "read", "write", "exec",
            "sessions_send", "sessions_list", "sessions_history"
          ]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "main",
      "match": { "channel": "discord", "accountId": "default" }
    },
    {
      "agentId": "klinked",
      "match": { "channel": "discord", "accountId": "klinked" }
    }
  ],
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["main", "klinked"]
    }
  },
  "browser": {
    "enabled": true
  },
  "channels": {
    "discord": {
      "accounts": {
        "default": {
          "token": "MAIN_BOT_TOKEN",
          "guilds": {
            "YOUR_MAIN_GUILD_ID": { "requireMention": false }
          }
        },
        "klinked": {
          "token": "KLINKED_BOT_TOKEN",
          "guilds": {
            "YOUR_KLINKED_GUILD_ID": { "requireMention": false }
          }
        }
      }
    }
  }
}

⚠️ Critical rules:

• browser is a top-level key, NOT nested under tools

• sessions is NOT a valid key under tools — remove it

• tools.allow at the agent level controls what that agent can call

---

Step 12 — Restart and Verify

openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

Expected: both agents listed, both Discord accounts connected.

---

Part 5: Skills Setup

Step 13 — Installing from ClawHub

⚠️ Security warning: In February 2026, 341 malicious skills were found on ClawHub ("ClawHavoc" incident). Always check a skill's VirusTotal report on its clawhub.ai page before installing.

Navigate to the workspace first:

cd ~/.openclaw/workspace-klinked

Search for skills:

npx clawhub@latest search "linkedin automation"

Inspect before installing:

npx clawhub@latest inspect [skill-slug]

Install:

npx clawhub@latest install [skill-slug]

✅ If clawhub returns "Skill not found", the slug from GitHub repos may differ from the registry. Use search to find the correct slug.

---

Step 14 — Custom Skill Module

For domain-specific knowledge and templates, create a custom skill module:

mkdir -p ~/.openclaw/workspace-klinked/skills/linkedin-intelligence

Inside, place:

• SKILL.md — description and usage instructions

• headline.md — headline templates

• tagline.md — About section template

• networking.md — DM and connection message templates

• trending_skills.json — skills gap data (refresh every 14 days)

✅ Workspace skills take precedence over global skills. The agent auto-loads all skills from skills/ at session start.

---

Part 6: Agent-to-Agent Communication

Step 15 — How One Agent Talks to Another

There is no /delegate command. Communication works via the sessions_send tool.

Method 1 — Natural language from klaw's Discord:

use sessions_send to message klinked: "write 3 LinkedIn posts about Terraform"

Method 2 — CLI:

openclaw agent --agent klinked --message "write 3 LinkedIn posts" --deliver

sessions_send must be in the sending agent's tools.allow list, and agentToAgent.enabled: true must be set.

---

Part 7: Browser Tool for Automation

Step 16 — Enable Browser Tool

browser is a top-level key:

{
  "browser": {
    "enabled": true
  }
}

Add to agent tool allowlist under agents.list[].tools.allow.

Step 17 — Log Into LinkedIn

openclaw browser open https://www.linkedin.com

Log in manually. Session is saved and reused for automation.

Test from Discord:

open linkedin.com in the browser and tell me what you see

---

Common Mistakes & Fixes

Mistake	Fix
sessions key under tools	Not a valid key. Remove it entirely
browser nested under tools	browser is a top-level key
Identity file named IDENTITY.md	Correct filename is SOUL.md
Using /delegate in Discord	No such command. Use sessions_send or openclaw agent CLI
data/ and templates/ folders	Not official. Put custom content inside skills/
clawhub install returns "Skill not found"	Use search to find the correct registry slug
Gateway refuses to start after config edit	Unknown key in config. Check tail ~/.openclaw/logs/gateway.log

---

Quick Reference

Essential Commands

openclaw agents add [agentId]           # create new agent
openclaw agents list --bindings         # verify routing
openclaw channels status --probe        # verify connections
openclaw gateway restart                # apply config changes
openclaw config get tools               # inspect tool config
openclaw security audit                 # check for issues
npx clawhub@latest search "[query]"     # search skills
npx clawhub@latest install [slug]       # install skill
npx clawhub@latest inspect [slug]       # check if slug exists
openclaw agent --agent [id] --message   # send message to agent

Documentation References

• Multi-agent routing: docs.openclaw.ai/concepts/multi-agent

• Agent workspace: docs.openclaw.ai/concepts/agent-workspace

• Discord channel config: docs.openclaw.ai/channels/discord

• Tools reference: docs.openclaw.ai/tools

• Browser tool: docs.openclaw.ai/tools/browser

• Session tools: docs.openclaw.ai/concepts/session-tool

• Config reference: docs.openclaw.ai/gateway/configuration-reference

• ClawHub security guide: clawhub.ai