mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-28 13:26:04 -06:00
Peter Steinberger
7f7448e96d
One shared agent could not give different people different execution isolation: sandbox selection saw only the agent's mode and the session key, never who created the session. Teams that share an agent had to choose between sandboxing everyone or no one. Add a closed, optional role axis sandbox?: "inherit" | "required" (default "inherit", so existing deployments are unchanged). The Gateway resolves it from the authenticated session creator and stamps it write-once onto genuinely new session entries; the agents layer reads that immutable fact and forces a sandbox even when the agent config says mode: "off". Anchoring on the creator keeps a session's isolation stable for its lifetime: a maintainer replying inside a guest session cannot un-sandbox it, and a caller whose role requires a sandbox is refused inside an unstamped session rather than silently inheriting host execution. Reset, rewind, rollover and fast-path all carry the requirement forward so a session cannot be reset out of its sandbox. Because exec injects the agent's managed GitHub identity only for gateway-host execution and blanks GH_TOKEN/GITHUB_TOKEN otherwise, a forced-sandbox session also loses access to the shared agent's credentials — the property that makes one shared agent safe for untrusted guests. Session entries are JSON; no SQLite schema, schema-version, or protocol change. Docs also correct the sandbox backend list, which omitted the first-class podman backend.
5.9 KiB
5.9 KiB
summary, read_when, title
| summary | read_when | title | ||
|---|---|---|---|---|
| Elevated exec mode: run commands outside the sandbox from a sandboxed agent |
|
Elevated mode |
When an agent runs inside a sandbox, its exec commands are confined to the sandbox environment. Elevated mode lets the agent break out of ordinary agent-configured sandboxing and run commands outside the sandbox instead, with configurable approval gates. Sessions whose creator role requires sandboxing cannot use elevated mode to escape.
Directives
Control elevated mode per-session with slash commands:
| Directive | What it does |
|---|---|
/elevated on |
Run outside the sandbox on the configured host path, keep approvals |
/elevated ask |
Same as on (alias) |
/elevated full |
Run outside the sandbox on the configured host path and skip approvals when the mode/host approval policy is already permissive |
/elevated off |
Return to sandbox-confined execution |
Also available as /elev on|off|ask|full.
Send /elevated with no argument to see the current level.
How it works
Elevated must be enabled in config and the sender must be on the allowlist:```json5
{
tools: {
elevated: {
enabled: true,
allowFrom: {
discord: ["user-id-123"],
whatsapp: ["+15555550123"],
},
},
},
}
```
```
/elevated full
```
Or use it inline (applies to that message only):
```
/elevated on run the deployment script
```
Resolution order
- Inline directive on the message (applies only to that message)
- Session override (set by sending a directive-only message)
- Global default (
agents.defaults.elevatedDefaultin config)
Availability and allowlists
- Global gate:
tools.elevated.enabled(must betrue) - Sender allowlist:
tools.elevated.allowFromwith per-channel lists - Per-agent gate:
agents.entries.*.tools.elevated.enabled(can only further restrict; both the global and per-agent gate must betrue) - Per-agent allowlist:
agents.entries.*.tools.elevated.allowFrom(sender must match both global + per-agent) - Channel-provided fallback allowlist: channel plugins can optionally supply a fallback allowlist through an SDK adapter hook, used when
tools.elevated.allowFrom.<provider>is not configured. No bundled channel currently implements this hook, so in practice every provider needs an explicittools.elevated.allowFrom.<provider>entry today. - All gates must pass; otherwise elevated is treated as unavailable
Allowlist entry formats:
| Prefix | Matches |
|---|---|
| (none) | Sender ID, E.164, or From field |
name: |
Sender display name |
username: |
Sender username |
tag: |
Sender tag |
id:, from:, e164: |
Explicit identity targeting |
What elevated does not control
- Tool policy: if
execis denied by tool policy, elevated cannot override it. - Required role sandboxing: if the authenticated session creator's operator role required a sandbox, elevated mode cannot run commands on the Gateway or a node.
- Host selection policy: elevated does not turn
autointo a free cross-host override. It uses the configured/session exec target rules, choosingnodeonly when the target is alreadynode. - Separate from
/exec: the/execdirective adjusts per-session exec defaults (host, security, ask, node) for authorized senders and does not require elevated mode.