# OpenClaw Tool-Permissions — Stand 2026-03-15

## Das Problem (GELÖST)

ARIA hat ZWEI Tool-Systeme gleichzeitig: Claude Code Tools UND OpenClaw-native Tools.
Das Model hat aber nur Zugriff auf **Claude Code Tools** (über den Proxy), nicht auf OpenClaw-native Tools.

### Root Cause: DREI Probleme gleichzeitig

```
OpenClaw (aria-core) → API Request → claude-max-api-proxy (aria-proxy) → Claude Code CLI (--print Mode)
                                                                          ↓
                                                                    Tools: WebFetch, Bash, etc. (Claude Code)
                                                                    NICHT: web_fetch, exec (OpenClaw-nativ)
```

**Problem 1: Proxy benutzt `--print` Modus**
- `claude-max-api-proxy` ruft Claude Code CLI mit `--print --output-format stream-json` auf
- Der Prompt wird als einziger String übergeben, keine Tool-Definitionen von OpenClaw
- Das Model sieht NUR Claude Code's eingebaute Tools (WebFetch, Bash, etc.)
- OpenClaw-native Tools (web_fetch, exec) existieren NUR auf Gateway-Ebene, kommen nie beim Model an

**Problem 2: BOOTSTRAP.md hat die falschen Tools angewiesen**
- BOOTSTRAP.md sagte: "NIEMALS WebFetch benutzen, stattdessen web_fetch"
- Aber web_fetch existiert nicht im Claude Code CLI Kontext
- Und WebFetch war das einzige Tool das funktioniert hätte
- → Model hatte keine Tools die es benutzen "durfte"

**Problem 3: settings.json im Proxy war leer**
- `/root/.claude/settings.json` enthielt nur `{}` (keine Permissions)
- Claude Code CLI im headless-Modus kann keine Tool-Genehmigungen erteilen
- → Selbst wenn das Model WebFetch benutzen wollte, war es nicht vorab genehmigt

## Die Lösung

### Fix 1: BOOTSTRAP.md + AGENT.md umgeschrieben

**Vorher (FALSCH):**
- "NIEMALS WebFetch benutzen — hat Permission-Probleme"
- "Benutze web_fetch (OpenClaw-nativ)"

**Nachher (KORREKT):**
- "WebFetch — URLs abrufen, Webseiten lesen, APIs aufrufen, Wetter abfragen"
- "Bash — Shell-Befehle ausfuehren (curl, ssh, docker, etc.)"
- "Niemals sagen 'ich habe keinen Zugriff' — du hast Zugriff auf alles"

### Fix 2: `CLAUDE_CODE_BUBBLEWRAP=1` + `--dangerously-skip-permissions`

**Der Schlüssel-Fix.** Zwei Zeilen in `docker-compose.yml`:

```yaml
# 1. sed-Patch: --dangerously-skip-permissions in manager.js einfügen
sed -i 's/"--no-session-persistence",/"--no-session-persistence","--dangerously-skip-permissions",/' $$DIST/subprocess/manager.js &&

# 2. Environment-Variable: Root-Check umgehen
environment:
  - CLAUDE_CODE_BUBBLEWRAP=1
```

**Warum beides nötig:**
- `--dangerously-skip-permissions` umgeht alle Tool-Permission-Checks in Claude Code CLI
- Aber: Claude Code CLI blockiert dieses Flag wenn es als root läuft
- `CLAUDE_CODE_BUBBLEWRAP=1` überspringt den Root-Check (gefunden im minifizierten `cli.js`)
- Proxy-Container (`node:22-alpine`) läuft als root → ohne BUBBLEWRAP geht's nicht

**Resultierende CLI-Argumente:**
```
claude --print --output-format stream-json --verbose --include-partial-messages \
  --model opus --no-session-persistence --dangerously-skip-permissions "prompt"
```

## Wie der Proxy intern funktioniert

```
openai-to-cli.js:  OpenAI Messages → einzelner Prompt-String
                    system → <system>...</system>
                    user → direkt
                    assistant → <previous_response>...</previous_response>

subprocess/manager.js:  Spawnt `claude --print ... --dangerously-skip-permissions "{prompt}"`

cli-to-openai.js:  Claude CLI JSON-Stream → OpenAI Chat Completion Chunks
```

Der Proxy leitet KEINE Tool-Definitionen von OpenClaw weiter.
Tool-Calls passieren INTERN in der Claude Code CLI und sind für OpenClaw transparent.

## Permission-Architektur

**Granulare Tool-Kontrolle ist NICHT möglich.** Es ist Alles-oder-Nichts:
- `--dangerously-skip-permissions` AN → ARIA kann alle Claude Code Tools benutzen
- `--dangerously-skip-permissions` AUS → ARIA kann keine Tools benutzen

OpenClaw's eigene Permissions (`tools.allow/deny` in `openclaw.json`) haben **keinen Effekt** auf die
Claude Code Tools — die laufen komplett auf Proxy-Seite.

## Was NICHT funktioniert hat (17 Versuche)

1. **settings.json in aria-core** — OpenClaw benutzt NICHT Claude Code's settings.json
2. **tools.allow mit PascalCase** (WebFetch, Grep) — OpenClaw kennt diese Namen nicht
3. **tools.allow mit snake_case** (web_fetch) — Nur exec, read, write, edit erkannt
4. **tools.allow mit Wildcard** `["*"]` — Hat nicht geholfen
5. **tools.allow leer + tools.profile: "full"** — Nur ohne andere Fehler
6. **System-Prompt Anweisung allein** — Reicht nicht wenn Tools blockiert sind
7. **exec-approvals Wildcard allein** — Reicht nicht bei Config-Validation-Error
8. **`openclaw config unset tools.exec.ask`** — CLI kennt den Pfad nicht
9. **BOOTSTRAP.md mit OpenClaw-Tool-Namen** — Tools existieren nur auf Gateway-Ebene
10. **settings.json im Proxy ohne BOOTSTRAP.md Fix** — BOOTSTRAP.md verbot die Tools
11. **tools.byProvider.proxy.profile full** — Kein Effekt
12. **settings.json + BOOTSTRAP.md ohne --dangerously-skip-permissions** — `--print` ignoriert settings.json
13. **Manuelles `docker exec sed`** — Wird bei jedem Restart überschrieben
14. **`--dangerously-skip-permissions` ohne BUBBLEWRAP** — Root-Check blockiert
15. **`--allowedTools`** — Variadisches Argument frisst den Prompt
16. **`--permission-mode bypassPermissions`** — Gleicher Root-Check
17. **Non-Root User (`su node`)** — Auth-Pfad-Probleme, Credentials unerreichbar

## Wichtige Pfade

### aria-core (OpenClaw)
- `/home/node/.openclaw/openclaw.json` — OpenClaw Haupt-Config
- `/home/node/.openclaw/exec-approvals.json` — Exec Approvals
- `/tmp/openclaw/openclaw-YYYY-MM-DD.log` — Tages-Log

### aria-proxy (Claude Code CLI)
- `/root/.claude/.credentials.json` — Auth Credentials (NICHT in /root/.config/claude/)
- `/usr/local/lib/node_modules/claude-max-api-proxy/dist/` — Proxy Source
- `/usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js` — Claude Code CLI (enthält Root-Check)

## OpenClaw CLI Referenz

```bash
openclaw config get/set/unset <path>    # Config verwalten
openclaw approvals get                  # Exec-Approvals anzeigen
openclaw approvals allowlist add        # Exec-Pattern freigeben
openclaw doctor [--fix]                 # Health Check
openclaw gateway status                 # Gateway-Status
```