devclaw-gitea/docs/CONTEXT-AWARENESS.md

Context-Aware DevClaw

DevClaw now adapts its behavior based on how you interact with it.

Design Philosophy

One Group = One Project = One Team

DevClaw enforces strict boundaries between projects:

• Each Telegram/WhatsApp group represents a single project
• Each project has its own dedicated dev/qa workers
• Project work happens inside that project's group
• Setup and configuration happen outside project groups

This design prevents:

• ❌ Cross-project contamination (workers picking up wrong project's tasks)
• ❌ Confusion about which project you're working on
• ❌ Accidental registration of wrong groups
• ❌ Setup discussions cluttering project work channels

This enables:

• ✅ Clear mental model: "This group = this project"
• ✅ Isolated work streams: Each project progresses independently
• ✅ Dedicated teams: Workers focus on one project at a time
• ✅ Clean separation: Setup vs. operational work

Three Interaction Contexts

1. Via Another Agent (Setup Mode)

When you talk to your main agent (like Henk) about DevClaw:

• ✅ Use: devclaw_onboard, devclaw_setup
• ❌ Avoid: task_pickup, queue_status (operational tools)

Example:

User → Henk: "Can you help me set up DevClaw?"
Henk → Calls devclaw_onboard

2. Direct Message to DevClaw Agent

When you DM the DevClaw agent directly on Telegram/WhatsApp:

• ✅ Use: queue_status (all projects), session_health (system overview)
• ❌ Avoid: task_pickup (project-specific work), setup tools

Example:

User → DevClaw DM: "Show me the status of all projects"
DevClaw → Calls queue_status (shows all projects)

3. Project Group Chat

When you message in a Telegram/WhatsApp group bound to a project:

• ✅ Use: task_pickup, task_complete, task_create, queue_status (auto-filtered)
• ❌ Avoid: Setup tools, system-wide queries

Example:

User → OpenClaw Dev Group: "@henk pick up issue #42"
DevClaw → Calls task_pickup (only works in groups)

How It Works

Context Detection

Each tool automatically detects:

• Agent ID - Is this the DevClaw agent or another agent?
• Message Channel - Telegram, WhatsApp, or CLI?
• Session Key - Is this a group chat or direct message?
  • Format: agent:{agentId}:{channel}:{type}:{id}
  • Telegram group: agent:devclaw:telegram:group:-5266044536
  • WhatsApp group: agent:devclaw:whatsapp:group:120363123@g.us
  • DM: agent:devclaw:telegram:user:657120585
• Project Binding - Which project is this group bound to?

Guardrails

Tools include context-aware guidance in their responses:

{
  "contextGuidance": "🛡️ Context: Project Group Chat (telegram)\n
    You're in a Telegram group for project 'openclaw-core'.\n
    Use task_pickup, task_complete for project work.",
  ...
}

Integrated Tools

✅ devclaw_onboard

• Works best: Via another agent or direct DM
• Blocks: Group chats (setup shouldn't happen in project groups)

✅ queue_status

• Group context: Auto-filters to that project
• Direct context: Shows all projects
• Via-agent context: Suggests using devclaw_onboard instead

✅ task_pickup

• ONLY works: In project group chats
• Blocks: Direct DMs and setup conversations

✅ project_register

• ONLY works: In the Telegram/WhatsApp group you're registering
• Blocks: Direct DMs and via-agent conversations
• Auto-detects: Group ID from current chat (projectGroupId parameter now optional)

Why this matters:

• Project Isolation: Each group = one project = one dedicated team
• Clear Boundaries: Forces deliberate project registration from within the project's space
• Team Clarity: You're physically in the group when binding it, making the connection explicit
• No Mistakes: Impossible to accidentally register the wrong group when you're in it
• Natural Workflow: "This group is for Project X" → register Project X here

Testing

Debug Tool

Use context_test to see what context is detected:

# In any context:
context_test

# Returns:
{
  "detectedContext": { "type": "group", "projectName": "openclaw-core" },
  "guardrails": "🛡️ Context: Project Group Chat..."
}

Manual Testing

1. Setup Mode: Message your main agent → "Help me configure DevClaw"
2. Status Check: DM DevClaw agent (Telegram/WhatsApp) → "Show me the queue"
3. Project Work: Post in project group (Telegram/WhatsApp) → "@henk pick up #42"

Each context should trigger different guardrails.

Configuration

Add to ~/.openclaw/openclaw.json:

"plugins": {
  "entries": {
    "devclaw": {
      "config": {
        "devClawAgentIds": ["henk-development", "devclaw-test"],
        "models": { ... }
      }
    }
  }
}

The devClawAgentIds array lists which agents are DevClaw orchestrators.

Implementation Details

• Module: lib/context-guard.ts
• Tests: tests/unit/context-guard.test.ts (15 passing)
• Integrated tools: 4 key tools (devclaw_onboard, queue_status, task_pickup, project_register)
• Detection logic: Checks agentId, messageChannel, sessionKey pattern matching

WhatsApp Support

DevClaw fully supports WhatsApp groups with the same architecture as Telegram:

• ✅ WhatsApp group detection via sessionKey.includes("@g.us")
• ✅ Projects keyed by WhatsApp group ID (e.g., "120363123@g.us")
• ✅ Context-aware tools work identically for both channels
• ✅ One project = one group (Telegram OR WhatsApp)

To register a WhatsApp project:

1. Go to the WhatsApp group chat
2. Call project_register from within the group
3. Group ID auto-detected from context

The architecture treats Telegram and WhatsApp identically - the only difference is the group ID format.

Future Enhancements

• Integrate into remaining tools (task_complete, session_health, task_create, devclaw_setup)
• System prompt injection (requires OpenClaw core support)
• Context-based tool filtering (hide irrelevant tools)
• Per-project context overrides