let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: wire multi-agent config and routing

Browse Source 
Co-authored-by: Mark Pors <1078320+pors@users.noreply.github.com>
This commit is contained in:
Peter Steinberger
2026-01-09 12:44:23 +00:00
parent 81beda0772
commit 7b81d97ec2
189 changed files with 4340 additions and 2903 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
docs/multi-agent-sandbox-tools.md
View File

@@ -10,8 +10,8 @@ status: active
## Overview
Each agent in a multi-agent setup can now have its own:
- **Sandbox configuration** (`mode`, `scope`, `workspaceRoot`, `workspaceAccess`, `tools`)
- **Tool restrictions** (`allow`, `deny`)
- **Sandbox configuration** (`agents.list[].sandbox` overrides `agents.defaults.sandbox`)
- **Tool restrictions** (`tools.allow` / `tools.deny`, plus `agents.list[].tools`)
This allows you to run multiple agents with different security profiles:
- Personal assistant with full access
@@ -28,18 +28,17 @@ For how sandboxing behaves at runtime, see [Sandboxing](/gateway/sandboxing).
```json
{
"routing": {
"defaultAgentId": "main",
"agents": {
"main": {
"agents": {
"list": [
{
"id": "main",
"default": true,
"name": "Personal Assistant",
"workspace": "~/clawd",
"sandbox": {
"mode": "off"
}
// No tool restrictions - all tools available
"sandbox": { "mode": "off" }
},
"family": {
{
"id": "family",
"name": "Family Bot",
"workspace": "~/clawd-family",
"sandbox": {
@@ -51,21 +50,21 @@ For how sandboxing behaves at runtime, see [Sandboxing](/gateway/sandboxing).
"deny": ["bash", "write", "edit", "process", "browser"]
}
}
},
"bindings": [
{
"agentId": "family",
"match": {
"provider": "whatsapp",
"accountId": "*",
"peer": {
"kind": "group",
"id": "120363424282127706@g.us"
}
]
},
"bindings": [
{
"agentId": "family",
"match": {
"provider": "whatsapp",
"accountId": "*",
"peer": {
"kind": "group",
"id": "120363424282127706@g.us"
}
}
]
}
}
]
}
```
@@ -79,13 +78,15 @@ For how sandboxing behaves at runtime, see [Sandboxing](/gateway/sandboxing).
```json
{
"routing": {
"agents": {
"personal": {
"agents": {
"list": [
{
"id": "personal",
"workspace": "~/clawd-personal",
"sandbox": { "mode": "off" }
},
"work": {
{
"id": "work",
"workspace": "~/clawd-work",
"sandbox": {
"mode": "all",
@@ -97,7 +98,7 @@ For how sandboxing behaves at runtime, see [Sandboxing](/gateway/sandboxing).
"deny": ["browser", "gateway", "discord"]
}
}
}
]
}
}
```
@@ -108,21 +109,23 @@ For how sandboxing behaves at runtime, see [Sandboxing](/gateway/sandboxing).
```json
{
"agent": {
"sandbox": {
"mode": "non-main", // Global default
"scope": "session"
}
},
"routing": {
"agents": {
"main": {
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main", // Global default
"scope": "session"
}
},
"list": [
{
"id": "main",
"workspace": "~/clawd",
"sandbox": {
"mode": "off" // Override: main never sandboxed
}
},
"public": {
{
"id": "public",
"workspace": "~/clawd-public",
"sandbox": {
"mode": "all", // Override: public always sandboxed
@@ -133,7 +136,7 @@ For how sandboxing behaves at runtime, see [Sandboxing](/gateway/sandboxing).
"deny": ["bash", "write", "edit"]
}
}
}
]
}
}
```
@@ -142,40 +145,40 @@ For how sandboxing behaves at runtime, see [Sandboxing](/gateway/sandboxing).
## Configuration Precedence
When both global (`agent.*`) and agent-specific (`routing.agents[id].*`) configs exist:
When both global (`agents.defaults.*`) and agent-specific (`agents.list[].*`) configs exist:
### Sandbox Config
Agent-specific settings override global:
```
routing.agents[id].sandbox.mode > agent.sandbox.mode
routing.agents[id].sandbox.scope > agent.sandbox.scope
routing.agents[id].sandbox.workspaceRoot > agent.sandbox.workspaceRoot
routing.agents[id].sandbox.workspaceAccess > agent.sandbox.workspaceAccess
routing.agents[id].sandbox.docker.* > agent.sandbox.docker.*
routing.agents[id].sandbox.browser.* > agent.sandbox.browser.*
routing.agents[id].sandbox.prune.* > agent.sandbox.prune.*
agents.list[].sandbox.mode > agents.defaults.sandbox.mode
agents.list[].sandbox.scope > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
```
**Notes:**
- `routing.agents[id].sandbox.{docker,browser,prune}.*` overrides `agent.sandbox.{docker,browser,prune}.*` for that agent (ignored when sandbox scope resolves to `"shared"`).
- `agents.list[].sandbox.{docker,browser,prune}.*` overrides `agents.defaults.sandbox.{docker,browser,prune}.*` for that agent (ignored when sandbox scope resolves to `"shared"`).
### Tool Restrictions
The filtering order is:
1. **Global tool policy** (`agent.tools`)
2. **Agent-specific tool policy** (`routing.agents[id].tools`)
3. **Sandbox tool policy** (`agent.sandbox.tools` or `routing.agents[id].sandbox.tools`)
4. **Subagent tool policy** (if applicable)
1. **Global tool policy** (`tools.allow` / `tools.deny`)
2. **Agent-specific tool policy** (`agents.list[].tools`)
3. **Sandbox tool policy** (`tools.sandbox.tools` or `agents.list[].tools.sandbox.tools`)
4. **Subagent tool policy** (`tools.subagents.tools`, if applicable)
Each level can further restrict tools, but cannot grant back denied tools from earlier levels.
If `routing.agents[id].sandbox.tools` is set, it replaces `agent.sandbox.tools` for that agent.
If `agents.list[].tools.sandbox.tools` is set, it replaces `tools.sandbox.tools` for that agent.
### Elevated Mode (global)
`agent.elevated` is **global** and **sender-based** (per-provider allowlist). It is **not** configurable per agent.
`tools.elevated` is **global** and **sender-based** (per-provider allowlist). It is **not** configurable per agent.
Mitigation patterns:
- Deny `bash` for untrusted agents (`routing.agents[id].tools.deny: ["bash"]`)
- Deny `bash` for untrusted agents (`agents.list[].tools.deny: ["bash"]`)
- Avoid allowlisting senders that route to restricted agents
- Disable elevated globally (`agent.elevated.enabled: false`) if you only want sandboxed execution
- Disable elevated globally (`tools.elevated.enabled: false`) if you only want sandboxed execution
---
@@ -184,10 +187,16 @@ Mitigation patterns:
**Before (single agent):**
```json
{
"agent": {
"workspace": "~/clawd",
"agents": {
"defaults": {
"workspace": "~/clawd",
"sandbox": {
"mode": "non-main"
}
}
},
"tools": {
"sandbox": {
"mode": "non-main",
"tools": {
"allow": ["read", "write", "bash"],
"deny": []
@@ -200,21 +209,20 @@ Mitigation patterns:
**After (multi-agent with different profiles):**
```json
{
"routing": {
"defaultAgentId": "main",
"agents": {
"main": {
"agents": {
"list": [
{
"id": "main",
"default": true,
"workspace": "~/clawd",
"sandbox": {
"mode": "off"
}
"sandbox": { "mode": "off" }
}
}
]
}
}
```
The global `agent.workspace` and `agent.sandbox` are still supported for backward compatibility, but we recommend using `routing.agents` for clarity in multi-agent setups.
Legacy `agent.*` configs are migrated by `clawdbot doctor`; prefer `agents.defaults` + `agents.list` going forward.
---
@@ -254,10 +262,10 @@ The global `agent.workspace` and `agent.sandbox` are still supported for backwar
## Common Pitfall: "non-main"
`sandbox.mode: "non-main"` is based on `session.mainKey` (default `"main"`),
`agents.defaults.sandbox.mode: "non-main"` is based on `session.mainKey` (default `"main"`),
not the agent id. Group/channel sessions always get their own keys, so they
are treated as non-main and will be sandboxed. If you want an agent to never
sandbox, set `routing.agents.<id>.sandbox.mode: "off"`.
sandbox, set `agents.list[].sandbox.mode: "off"`.
---
@@ -289,8 +297,8 @@ After configuring multi-agent sandbox and tools:
## Troubleshooting
### Agent not sandboxed despite `mode: "all"`
- Check if there's a global `agent.sandbox.mode` that overrides it
- Agent-specific config takes precedence, so set `routing.agents[id].sandbox.mode: "all"`
- Check if there's a global `agents.defaults.sandbox.mode` that overrides it
- Agent-specific config takes precedence, so set `agents.list[].sandbox.mode: "all"`
### Tools still available despite deny list
- Check tool filtering order: global → agent → sandbox → subagent
@@ -306,5 +314,5 @@ After configuring multi-agent sandbox and tools:
## See Also
- [Multi-Agent Routing](/concepts/multi-agent)
- [Sandbox Configuration](/gateway/configuration#agent-sandbox)
- [Sandbox Configuration](/gateway/configuration#agentsdefaults-sandbox)
- [Session Management](/concepts/session)