Create & Configure Agents

OpenTrader uses 3 active AI agents running inside OpenClaw: coo, finance, scout. The retired ops workspace is kept only for compatibility and responds ANNOUNCE_SKIP if invoked.

Step 1 — Create a Telegram bot

Agent coo communicates with boss via Telegram. You need to create a bot before starting the system.

1.1 Create bot with BotFather

1. Open Telegram, search for @BotFather
2. Send the command /newbot
3. Set a display name (e.g. OpenTrader COO)
4. Set a username (must end in bot, e.g. opentrader_coo_bot)
5. BotFather returns a token like 123456789:AAxxxxxx... — this is your TELEGRAM_BOT_TOKEN

1.2 Get your Chat ID

The Chat ID is your Telegram identifier — COO uses it to know who is authorised to send commands.

1. Send any message to the bot you just created
2. Open the following URL in your browser (replace <TOKEN> with your token):

   https://api.telegram.org/bot<TOKEN>/getUpdates
   

3. Find the field "chat":{"id":...} in the response — that is your TELEGRAM_CHAT_ID

1.3 Add to .env

TELEGRAM_BOT_TOKEN=123456789:AAxxxxxx...
TELEGRAM_CHAT_ID=987654321

Step 2 — Configure openclaw.json

Edit openclaw/openclaw.json to wire up the Telegram channel, routing, inter-agent communication, and agent defaults.

2.1 Add Telegram coo account in channels

"channels": {
  "telegram": {
    "accounts": {
      "default": {
        ...
      },
      "coo": {
        "enabled": true,
        "dmPolicy": "pairing",
        "botToken": "123456789:AAxxxxxx...",
        "groupPolicy": "allowlist",
        "streaming": {
          "mode": "partial"
        }
      }
    }
  }
}

The coo account uses the bot token from Step 1. dmPolicy: "pairing" means only paired users can DM the bot.

2.2 Bindings — route inbound chat to agent coo

"bindings": [
  {
    "agentId": "coo",
    "match": {
      "channel": "telegram",
      "accountId": "coo",
      "peer": {
        "kind": "direct",
        "id": "<your-telegram-id>"
      }
    }
  }
]

Any direct message arriving on the coo Telegram account from your Telegram ID → routed to agent coo.

2.3 agentToAgent — allow agents to talk to each other

"tools": {
  "agentToAgent": {
    "enabled": true,
    "allow": ["coo", "finance", "scout"]
  }
}

Grants agent coo permission to dispatch tasks to finance and scout — and allows those agents to call each other as needed.

2.4 sessions.visibility — agents see each other’s runs

"tools": {
  "sessions": {
    "visibility": "all"
  }
}

By default an agent can only see its own sessions. Setting visibility: "all" lets every agent see all running sessions in the system — required so that COO can monitor subagent progress and orchestrate correctly.

Why this matters: Without "all", COO cannot see the result of a spawned finance or scout run; it would have to wait blindly. With "all", COO can poll or observe the subagent session directly.

2.5 Note on nested runs and Telegram routing

OpenClaw routing is deterministic — replies always return to the channel the message came from. The model cannot override this.

When an agent uses sessions_send to deliver a message to COO, COO runs in a nested run and text output goes to channel=webchat, not Telegram. This is a fixed architectural constraint.

Solution: Use the message built-in tool instead of text output:

# Get boss chat ID from env
exec: printenv TELEGRAM_CHAT_ID  → [BOSS_ID]

# Send via message tool — bypasses routing, goes directly to Telegram
message(
  channel: "telegram",
  target: [BOSS_ID],
  message: "Content to send to boss"
)

TELEGRAM_CHAT_ID is always available in the container since OpenClaw requires this env var to connect the Telegram channel.

2.5 Agent defaults

"agents": {
  "defaults": {
    "model": "9router/opentrader",
    "subagents": {
      "maxConcurrent": 8,
      "archiveAfterMinutes": 60
    }
  }
}

Step 3 — Create workspaces for 4 agents

Each agent needs a workspace — a directory containing behaviour files (AGENTS.md, SOUL.md). OpenClaw reads these files every time an agent starts a session.

Option A — Copy from template (recommended)

The repo already includes complete templates for the active agents in openclaw/workspace-*. Just copy them into the mount directory:

# Create mount directory (if not already present)
mkdir -p config workspace

# Copy per-agent workspaces
cp -r openclaw/workspace-coo     config/workspace-coo
cp -r openclaw/workspace-finance config/workspace-finance
cp -r openclaw/workspace-scout   config/workspace-scout

Result inside config/:

config/
├── openclaw.json
├── cron/
│   └── jobs.json
├── workspace-coo/
│   ├── AGENTS.md
│   └── SOUL.md
├── workspace-finance/
│   ├── AGENTS.md
│   └── SOUL.md
└── workspace-scout/
    ├── AGENTS.md
    └── SOUL.md

Option B — Create via OpenClaw chat

Once the container is running, you can ask the agent to create the workspace through the chat interface:

“Please create a new workspace named workspace-scout at /home/node/.openclaw/workspace-scout. Create the AGENTS.md and SOUL.md files with the following content: [paste content]”

OpenClaw will create the directory and write the files using its write tool.

Health-check alert path

ops is retired. Health checks now run via scripts/health_check.py under scripts/ops_runner.sh.

• The script checks system status directly.
• Any alert sent to boss bypasses the retired ops agent.
• COO still owns boss-facing incident communication when a nested run or manual check is involved, so COO docs continue to describe how to report system issues.

Step 4 — Configure SOUL.md and AGENTS.md

This is the most important step — it determines how each agent thinks and acts.

Two file types

Important: SOUL.md is not injected into isolated cron sessions. Therefore all critical rules (timeouts, thresholds, output format) must be in AGENTS.md, not SOUL.md. See: SOUL.md vs AGENTS.md

Agent roles

Upload files via OpenClaw chat

Once the container is running, you can update AGENTS.md / SOUL.md content directly via chat without accessing the server:

Example prompt:

“Here are the AGENTS.md and SOUL.md files for the finance agent. Please replace the current content in workspace /home/node/.openclaw/workspace-finance:

[AGENTS.md] (paste full AGENTS.md content)

[SOUL.md] (paste full SOUL.md content)

After writing, confirm the contents of each file.“

The agent uses its write tool to write directly into the workspace. Changes take effect in the next session — no container restart needed.

Syncing USER.md and IDENTITY.md

OpenClaw automatically creates USER.md (information about the user) and IDENTITY.md (agent self-description) in the workspace after the first session. If they need to reflect the agent’s role:

Example prompt to sync finance:

“Please update IDENTITY.md in workspace-finance to match this role: an agent that protects open positions, manages trailing stops, monitors drawdown, and reports PnL. Signal confirmation and execution are handled server-side via /api/signal/{symbol}/confirm. Tone: steady on protection, honest on reports.”

This helps the agent maintain an accurate self-awareness across sessions.

Step 5 — Editing after deployment

When you need to change an agent’s behaviour:

# Edit local template
nano openclaw/workspace-finance/AGENTS.md

# Sync into config (mount dir)
cp openclaw/workspace-finance/AGENTS.md config/workspace-finance/AGENTS.md

Changes take effect in the next new session — OpenClaw re-reads the file every time a session starts, no container restart required.

To edit via chat, use a prompt as shown above — the agent writes directly to the workspace path.

Verification

After completing setup:

# Start the full system
docker compose up -d

# View openclaw logs to confirm agents loaded correct workspaces
docker logs openclaw -f

# Test: send a message to the Telegram bot
# → COO should reply within a few seconds

Check agent status at http://localhost:8000/api/dashboard.