1. Where does a value come from?

Values resolve from lowest to highest priority:

1. Schema default
2. Global config, ~/.omp/agent/config.yml
3. Project config, <cwd>/.omp/config.yml
4. Ordered --config overlays, including PI_CONFIG_FILES
5. CLI and runtime overrides

Three facts people learn the hard way:

1. Project settings do not walk up ancestors. Context files (AGENTS.md, RULES.md, and standalone CLAUDE.md) do. A .omp/config.yml in a parent directory of where you launched is silently ignored.
2. Arrays replace wholesale, per layer. They do not merge. If a project .omp/config.yml defines bash.patterns, it deletes every global pattern for that project. If you keep global guardrails in an array, either never define that array at project level, or load the global version as a --config overlay (via PI_CONFIG_FILES in your shell profile) so it resolves after project config. Caveat: GUI-spawned omp (ACP, launchd) never sources your shell profile, so an env-based overlay does not reach it.
3. omp config get <key> shows the merged, effective value from wherever your shell runs it, overlays included. When a change seems to have no effect, ask which layer you edited and which layer wins.

Useful commands:

omp config list --json   # every key with its effective value
omp config get <key>
omp config set <key> <value>
omp config path          # which directory the global config lives in
/settings                # same thing with a UI

2. Which approval mode should I choose?

Fresh installs default to yolo. Start with write: read and workspace-write tools stay automatic, while exec-tier actions still require approval.

The mode is the baseline. tools.approval overrides it per tool, and the first matching bash.patterns rule overrides the bash policy:

tools:
  approvalMode: write
  approval:
    bash: prompt
bash:
  patterns:
    - { match: "git status*", approval: allow }
    - { match: "rm -r*", approval: deny }

Under yolo, only deny and prompt rules change bash behavior. deny blocks, prompt asks, and allow rules must match the full command while deny and prompt inspect compound-command segments. eval needs its own approval policy: Python and JavaScript cells can spawn exec-tier shells, so use tools.approval.eval when that boundary matters.

3. What belongs in my first config?

defaultThinkingLevel: auto
secrets:
  enabled: true
tools:
  approvalMode: write

4. What should I add later?

Full reference

The full key catalog stays sourced from data/settings.json. Search the list below for your install’s shipped defaults, or run omp config list --json for your effective values.