ki-copilot/04-fortgeschrittene-konfiguration.md

Kapitel 4

Fortgeschrittene Konfiguration – Settings, Trust und Sandbox

Kern in einem Satz: Settings, Trusted Dirs, URL-Regeln und Sandbox sind die harten Räder am Harness – sie entscheiden, wo und wie weit Copilot CLI arbeiten darf, bevor der Agent überhaupt denkt.

Du hast Instructions und Permissions (Kap. 2) und den Alltag mit Plan, Diff und GitHub-Flow (Kap. 3). Jetzt geht es um die Schichten darunter und daneben: Welche settings.json gewinnt? Warum greift eine Repo-Regel bei dir, aber nicht im CI? Was passiert, wenn du ein zweites Repo einbindest?

Stand: Mitte/Ende 2026 · Primär: docs.github.com/en/copilot · bei Drift: copilot help config und /help in der Session.

---

4.1 Settings-Hierarchie: später schlägt früher

Du startest copilot im Repo und wunderst dich: Deine persönliche Default-Einstellung greift nicht. Oft liegt die Ursache nicht am Modell, sondern an der Merge-Reihenfolge.

Einstellungen werden von oben nach unten geladen; später überschreibt früher:

#	Quelle	Typischer Ort / Mechanismus
1	Built-in Defaults	fest in der CLI
2	MDM managed settings	Unternehmensverwaltung
3	User settings	~/.copilot/settings.json (oder $COPILOT_HOME/settings.json)
4	Repository settings	.github/copilot/settings.json (committbar, Team)
5	Local settings	.github/copilot/settings.local.json (gitignore)
6	Environment variables	Shell / CI
7	CLI flags	Startbefehl, Session

Warum so? Defaults und MDM legen die Basis. User und Repo teilen die Arbeit privat vs. teamweit. Local und Env/Flags decken Maschinen- und Lauf-Sonderfälle ab, ohne das Repo zu verschmutzen.

{width=90%}

Scope	Pfad	Zweck
User	~/.copilot/settings.json	persönliche Defaults für alle Repos
Repo	.github/copilot/settings.json	geteilte Team-Baseline
Local	.github/copilot/settings.local.json	deine Overrides auf diesem Checkout

JSONC (Kommentare) ist in settings.json üblich. Ungültige Werte werden oft ignoriert und mit einer Startup-Warnung gemeldet – dann Datei reparieren statt raten.

/settings und Datei-Edit

In der interaktiven Session:

/settings
/settings show theme
/settings autoUpdate off

/config ist Alias von /settings. Viele Keys greifen sofort; manche brauchen Neustart (CLI sagt das). Listen und sicherheitskritische Werte oft nur über die Datei bzw. Editor (Ctrl+E im Settings-Dialog, falls angeboten).

Schnelle Referenz im Terminal: copilot help config.

COPILOT_HOME ersetzt den gesamten Config-Baum

export COPILOT_HOME=/path/to/my/copilot-config

Das ersetzt ~/.copilot komplett – Settings, Permissions, MCP, Skills, Hooks, Plugins, Session-State. Bestehende Daten werden nicht magisch mitgenommen; bei Umzug Inhalt kopieren. Der Cache (Marketplace, Auto-Update) folgt Plattformpfaden und COPILOT_CACHE_HOME, nicht automatisch COPILOT_HOME.

Achtung: Zwei Shells mit unterschiedlichem COPILOT_HOME sind zwei getrennte Welten – Auth, Approvals und History teilen sich nicht.

---

4.2 Bypass sperren: permissions.disableBypassPermissionsMode

YOLO und Verwandte (--allow-all, --yolo, --allow-all-tools, --allow-all-paths, --allow-all-urls) sind bequem und riskant. In Settings:

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

Wert "disable" unterdrückt diese Bypass-Flags und die zugehörigen Slash-Kommandos beim Start. MDM mit "disable" gewinnt immer – User-Settings können das nicht aufheben. Enterprise-Policy schlägt persönliche Bequemlichkeit.

Faustregel (Hebel aus Kap. 2, hier nur am Gelenk): enge Deny/Allowlist vor Session-YOLO. Wenn Bypass abgeschaltet ist, bleibst du bei gezielten --allow-tool / Interaktions-Approvals.

Siehe Vorlage: vorlagen/settings.permissions-hints.md · Beispiel: beispiele/configs/settings.repo.example.jsonc. Stabile Kernfassung im Buch: Anhang A.4. Vollständig und aktuell: Begleit-Service → Material.

---

4.3 Path-scoped Instructions: Konflikt und Diagnose

Orte, Frontmatter applyTo und Kombinationslogik („keine generelle Precedence“) stehen in Kapitel 2 – dort ist der Kanon. Hier der Praxis-Hebel: warum greift eine path-scoped Datei manchmal nicht?

Häufige Ursachen:

1. Falscher Glob – applyTo matcht die Dateien der aktuellen Arbeit nicht.
2. Widerspruch zu einer anderen geladenen Datei – kombiniert heißt: beide Texte landen im Kontext; das Modell muss priorisieren.
3. Zu groß / zu speziell – gehört eher in einen Skill (Kap. 5) als in „immer gültig“.
4. --no-custom-instructions oder Session ohne Trust.

Konflikt vermeiden: Globale Regeln kurz halten (Build, Branch, „nie push ohne Auftrag“). Spezifisches in path-scoped Dateien oder Skills. Nicht denselben Fakt an drei Stellen mit drei Formulierungen pflegen.

Vorlage: vorlagen/path-instructions.example.md. Diagnose: /instructions und /context.

---

4.4 Trusted Directories und Multi-Repo

Trusted Directories steuern, wo die CLI Dateien lesen, ändern und ausführen darf. Beim ersten Start in einem Verzeichnis: Trust nur für die Session oder dauerhaft merken. Home-Verzeichnis pauschal vertrauen ist riskant.

Dauerhaft vertrauenswürdige Ordner liegen in der verwalteten config.json (Array trustedFolders) unter ~/.copilot bzw. $COPILOT_HOME – manuell editieren geht, aber sparsam und mit Backup.

Zusätzliche Verzeichnisse in der Session

Wenn die Arbeit über den aktuellen Checkout hinausgeht (Shared-Docs, Monorepo-Nachbar, generiertes Artefakt-Repo):

/add-dir /path/to/directory

Startflag (mehrfach möglich):

copilot --add-dir=/path/to/shared-docs

Gespeicherte Extra-Pfade pro Location können auch in permissions-config.json unter allowed_directories landen (siehe unten) – das ist Path-Gate, kein Ersatz für Tool-Approval.

Arbeitsverzeichnis in der Session wechseln (wie in Kap. 1; Labels können driften – bei Abweichung ? / /help):

/cwd /path/to/directory

(laut Doku auch /cd)

Pattern: Ein Repo ist Session-CWD und Trust-Anker; Nachbarpfade nur per Allowlist (/add-dir / Flags / allowed_directories), Scope eng halten, Diff lesen bevor etwas committed wird.

---

4.5 URL allow / deny

Netzwerk ist ein eigener Risk-Kanal: web_fetch und ausgewählte Shell-Tools (curl, wget, …). Default: URLs brauchen Approval.

Mechanismus	Wirkung
allowedUrls in Settings	Domains/URLs ohne Prompt (Muster wie *.github.com)
deniedUrls in Settings	immer blockiert
--allow-url=DOMAIN / --deny-url=DOMAIN	pro Start
--allow-all-urls	Verifikation aus (weit)

Deny schlägt Allow. Gespeicherte URL-Regeln gehören in settings.json, nicht in permissions-config.json.

{
  "allowedUrls": ["*.github.com", "docs.github.com"],
  "deniedUrls": ["*.evil.example"]
}

Limitierungen (Doku): URLs in Dateiinhalten, obfuskiert oder in Custom-Env-Vars werden nicht zuverlässig erkannt; HTTP und HTTPS sind getrennt.

---

4.6 Sandbox: lokal und Cloud

Wenn Allow-all verlockend wird, ist die Gegenmaßnahme oft Sandbox, nicht mehr YOLO.

Lokal

/sandbox enable

Lokal sandboxt die CLI nicht sich selbst, sondern die Befehle und Tools, die sie in deinem Auftrag ausführt (Filesystem, Netzwerk, Capabilities – je nach OS-Support und Settings). Auch: copilot --sandbox für die Session ohne dauerhafte Einstellung; sandbox.enabled in Settings speichert den Default.

Cloud

copilot --cloud

Die Session läuft in einer isolierten Cloud-Umgebung (Public Preview / Produktstand kann sich ändern – aktuelle Doku lesen). Gut für riskante Experimente und wenn die Maschine „sauber“ bleiben soll; nicht identisch mit /delegate (Cloud Agent / PR-Flow, Kap. 3/6).

Achtung: Sandbox ersetzt weder Diff-Lesen noch enge Denys. Sie begrenzt Schaden; sie ersetzt keine Review-Kultur.

---

4.7 Session-State (Überblick)

Unter ~/.copilot/session-state/ (bzw. $COPILOT_HOME) liegen Session-Historie und Workspace-Artefakte (Events, Pläne, Checkpoints). Resume:

copilot --continue
copilot --resume

Details zu Compact, Hygiene, Chronicle, Remote Control und Rollback: Kapitel 7. Hier nur: State ist lokal und wertvoll; blind löschen = Resume weg. Session-Sync (Default oft an) und Remote Control (steerable) sind verschiedene Dinge – Kap. 7.

---

4.8 permissions-config.json: gespeicherte Approvals

Pfad-Auflösung (erste Treffer gewinnt):

1. --config-dir=…/permissions-config.json (legacy; lieber COPILOT_HOME)
2. $COPILOT_HOME/permissions-config.json
3. ~/.copilot/permissions-config.json

Die Datei speichert Approvals pro Location (absolut, Git-Root bzw. CWD). Keine Deny-Regeln, keine URL-Policy, keine Team-shared Policy im Repo. Denys und Defaults: Flags und Settings.

Schema (Überblick)

{
  "locations": {
    "/Users/YOUR-USER/src/your-org/your-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": [
            "pytest",
            "ruff check .",
            "git status",
            "git diff",
            "git log",
            "git:*"
          ]
        },
        { "kind": "write" },
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": null
        }
      ],
      "allowed_directories": []
    }
  }
}

kind (Auswahl)	Bedeutung
commands	Shell via commandIdentifiers
write	Datei schreiben (Path-Gate kann trotzdem greifen)
read	Read-Tools (interaktiv oft schon freier)
mcp	serverName + toolName oder null = alle Tools des Servers
mcp-sampling	Sampling für einen Server
memory	Copilot-Memory write/vote (Produkt-Memory, nicht Instruction-Dateien)
custom-tool	exakter Custom-Tool-Name

Shell-Matching: literal; git:* matcht git und Subcommands; git* (ohne Doppelpunkt-Stern-Semantik) ist kein allgemeines Glob.

Während einer laufenden Session die Datei nicht wild editieren. Location-Key muss zum Git-Root passen (Worktrees teilen den Main-Root).

---

So baust du das nach (Baseline-Repo)

1. Repo-Baseline committen: .github/copilot/settings.json mit allowedUrls, ggf. permissions.disableBypassPermissionsMode: "disable", kurzer companyAnnouncements-Reminder („Diff vor Commit“).
2. .github/copilot/settings.local.json in .gitignore – persönliche Overrides nur lokal.
3. Path-Instructions für tests/** (oder euer Äquivalent) anlegen – Frontmatter wie in Kap. 2.
4. Session starten, Trust bestätigen, mit enger Allowlist arbeiten – nicht mit YOLO beginnen.
5. Häufige Shells einmal bewusst freigeben (Session oder gespeichert), riskante Commands deny’en.
6. Optional /sandbox enable testen; Multi-Repo nur mit /add-dir.

Checkliste

• Weiß ich, welche Settings-Schicht gewinnt?
• Ist Local gitignored?
• Sind URL-Denys für Unbekanntes sinnvoll gesetzt?
• Ist Bypass per Policy/Settings gesperrt, wo nötig?
• Kenne ich den Git-Root-Key in permissions-config.json?

Häufige Fehler

Symptom	Typische Ursache
Repo-Setting greift nicht	Local/Env/Flag überschreibt; oder Key-Name falsch
Approvals „weg“	anderer COPILOT_HOME / anderer Location-Key
YOLO geht trotz Team-Policy	Business/Enterprise MDM – erwartetes Verhalten
Instruction wirkt random	Konflikt + Kombinationslogik; Glob prüfen
Extra-Pfad immer promptet	weder /add-dir noch allowed_directories

---

Jetzt selbst machen

1. Lege .github/copilot/settings.json nach dem Muster in beispiele/configs/ an (ohne Secrets).
2. Setze deniedUrls auf etwas Unnötiges und teste, ob Fetch blockt.
3. Starte mit copilot --deny-tool='shell(rm)' und einem erlaubten Testbefehl; lies den Diff nach der ersten Änderung.
4. Notiere dir, wo deine permissions-config.json liegt (COPILOT_HOME?).

---

Was du jetzt kannst

• Die Settings-Hierarchie erklären und bewusst wählen: User vs. Repo vs. Local vs. Flag.
• Bypass-Modus und MDM-Vorrang einordnen.
• Path-scoped Instructions diagnostizieren und Konflikte vermeiden (Kanon in Kap. 2).
• Trusted Dirs und Extra-Pfade für Multi-Repo-Szenarien steuern.
• URL allow/deny und Sandbox als harte Grenzen nutzen.
• permissions-config.json als Speicher für Approvals (nicht für Denys) lesen und pflegen.

Nächste Schritte

Kapitel 5 erweitert den Harness nach außen und in die Tiefe: MCP, Skills, Hooks, Custom Agents, Plugins und /fleet. Wenn Settings die Leitplanken sind, sind das die austauschbaren Module – mit eigener Härte und eigener Angriffsfläche.

Vorlagen und Beispiele zu diesem Kapitel:

• vorlagen/settings.permissions-hints.md
• vorlagen/permissions-config.example.json
• vorlagen/settings.local.example.jsonc
• vorlagen/path-instructions.example.md
• beispiele/configs/settings.repo.example.jsonc
• Rezept Permissions: beispiele/rezepte/01-enge-permissions.md