사용자 설정

사용자 설정 (User Settings)

사용자 구성 파일의 전역 settings 블록에 대한 전체 참조예요.

출처: 문서

본문

설정이 위치하는 곳 (Where Settings Live)

Docker Agent는 어떤 에이전트 YAML과도 무관한 단일 사용자 레벨 구성 파일을 읽어요:

~/.config/cagent/config.yaml

그 안의 settings: 블록은 실행하는 모든 에이전트에 적용되는 선호 사항 — 모양, 동작, 알림, 몇 가지 전역 안전 기본값 — 을 담아요. settings: 아래의 모든 것은 선택 사항이에요; 설정되지 않은 필드는 문서화된 기본값으로 폴백돼요.

# ~/.config/cagent/config.yaml
settings:
  theme: dracula
  lean: false
  sound: true

이 파일을 손으로 편집할 일은 거의 없어요. 대부분의 필드는 TUI의 /settings 대화상자(Appearance, Behavior, Notifications 탭)에서 관리돼요 — 거기서 Enter를 누르면 변경을 적용하고 유지해요. 소수의 필드(permissions, hooks, keybindings)는 대화상자 UI가 없고 파일을 직접 편집해서만 설정돼요.

Note 이 페이지는 settings: 를 문서로 다뤄요. 사용자 구성 파일에는 settings: 밖의 최상위 섹션 — aliases:, providers:, board:, credential_helper:, sandbox_allowlist: — 도 있는데, 여기서는 다루지 않아요.

설정 참조 (Settings Reference)

레이아웃 설정 (Layout Settings)

layout 은 TUI의 사이드바를 커스터마이즈해요. 영(영) 값(생략된 layout: 블록, 또는 생략된 어떤 필드)이 기본이에요: 사이드바는 오른쪽, 모든 섹션 표시, 정상 간격.

settings:
  layout:
    sidebar_position: left
    section_spacing: compact
    hide_usage: true

완전한 예제 (Complete Example)

# ~/.config/cagent/config.yaml
settings:
  theme: auto
  theme_dark: dracula
  theme_light: default-light
  lean: false
  expand_thinking: false
  split_diff_view: true
  render_images: true
  hide_tool_results: false
  sound: true
  sound_threshold: 10
  snapshot: true
  cache_stable_prompts: true
  warn_on_cache_miss: true
  busy_send_mode: queue
  interrupt_confirmation: double-tap
  restore_tabs: true
  tab_title_max_length: 24
  layout:
    sidebar_position: right
    section_spacing: normal
  permissions:
    deny:
      - "shell:cmd=sudo*"
    allow:
      - "read_*"
  hooks:
    session_start:
      - type: command
        command: "~/.config/cagent/hooks/session-start.sh"
  keybindings:
    - action: "commands"
      keys: ["f2", "ctrl+k"]

우선순위 규칙 (Precedence Rules)

사용자 설정은 낮은 우선순위 소스예요: 그것들은 기본값을 세우고, 더 구체적인 것이 이겨요.

• CLI 플래그가 사용자 설정보다 이겨요 — true에서 false로 가는 단순 불리언 플래그는 제외. docker agent run 플래그가 설정을 미러링하는 곳에서, 특정 실행에 대해 플래그를 전달하면 그 실행에 한해 설정보다 우선하며, 플래그는 저장된 사용자 구성 파일을 결코 수정하지 않아요. 이는 --lean / lean, --theme / theme, 안전 플래그 --safety / --yolo(아래 참고)에 대해 깔끔하게 성립하며, 플래그가 명령줄에 명시적으로 전달됐는지 추적합니다. --hide-tool-results / hide_tool_results 는 그렇지 않아요: "명시적으로 설정됐는지" 추적이 없는 평범한 불리언이므로, --hide-tool-results=false 를 전달해도 그 실행에서 저장된 hide_tool_results: true 설정을 끌 수 없어요 — 저장된 true가 이기고 플래그 위에 다시 적용돼요. 켜기 위해 플래그를 전달하는 것은 저장된 설정과 무관하게 예상대로 동작해요.
• 안전은 자체의 완전히 지정된 체인을 가져요. 새 세션에 대해 이 순서의 첫 번째 소스가 이겨요: 명시적 --safety 플래그 > 명시적 --yolo 플래그 > alias safety / yolo 옵션 > settings.safety / settings.YOLO > 에이전트 YAML의 agents.<name>.safety > 에이전트 YAML의 runtime.safety > 내장 기본값(읽기 전용 도구 자동 승인, 나머지 다른 것 확인). 각 범위에서 safety 필드가 레거시 YOLO / yolo 불리언보다 이겨요. 따라서 당신의 설정은 에이전트 작성자가 YAML에서 선언한 어떤 것보다도 이겨요 — 파일, URL, OCI 레지스트리에서 로드된 에이전트 구성은 결코 settings.safety, alias 옵션, CLI 플래그를 재정의할 수 없어요. 명시적 --yolo=false 는 그 실행에 대해 저장된 YOLO: true / alias yolo 를 억제해요(다른 설정과 YAML 기본값은 여전히 적용). 재개된 세션은 저장된 모드를 유지해요: 설정과 alias 기본값은 절대 만지지 않아요; 오직 명시적 --safety 나 --yolo 플래그만 재개를 재정의해요. Safety Modes 참고.
• Alias는 CLI 플래그와 사용자 설정 사이에 위치해요. alias(docker agent alias add ...)는 자신의 yolo, safety, model, hide_tool_results, sandbox 기본값을 묶을 수 있어요; 그것들은 해당 플래그가 명시적으로 전달되지 않았을 때 적용되는데, 사용자 설정이 하는 것과 같지만 사용자 설정 이후에 해석되어 alias 자신의 선택이 당신의 전역 기본값보다 우선해요.
• 권한은 재정의가 아니라 병합돼요. 전역 settings.permissions 와 에이전트 자신의 permissions: 는 평가 전에 단일 deny → allow → ask 패턴 집합으로 결합돼요 — 전역 deny는 에이전트 구성이 무엇을 허용하든 항상 차단해요. Merging Behavior 참고.
• 훅은 재정의가 아니라 추가적(additive)이에요. 주어진 수명 주기 이벤트에 대해 에이전트 구성, settings.hooks, hooks.d/ drop-in, --hook-* CLI 플래그의 훅이 모두 그 순서로 실행돼요. 전역 훅은 개별 에이전트가 억제할 수 없어요.
• 다른 모든 것은 평범한 기본값이에요. CLI나 에이전트 구성에 대응이 없는 필드(sound, sound_threshold, restore_tabs, tab_title_max_length, split_diff_view, render_images, cache_stable_prompts, warn_on_cache_miss, busy_send_mode, keybindings, layout)는 오직 settings:(또는 그것을 쓰는 /settings 대화상자)에서만 오고 — 실행별로 재정의할 것이 없어요.

더 알아보기 (Learn more)