# 설정 필드 참조

<a id="overview"></a>

이 색인은 public configuration struct의 **exported field 전부**를 production source에서 계수해 설명한다. `llm.Config`의 비공개 `limiter`는 16번째 내부 field지만 public 설정 분모 15개에서 제외한다. “default”는 zero value가 그대로 쓰이는지, constructor가 보정하는지를 구분한다. `noa.Config`를 직접 넘기면 `DefaultConfig`와 field별 merge하지 않는다.

<a id="agentcore-options"></a>

## `agentcore.Options` — 52 fields

| field | type | default | override/consumer | failure semantics |
|---|---|---|---|---|
| `Provider` | `llm.Provider` | 없음 | 그대로 harness에 전달 | nil/오동작 provider는 첫 model call에서 실패 |
| `SystemPrompt` | `[]string` | 빈 목록 | 정적 system prefix | host policy가 없으면 SDK가 보충하지 않음 |
| `AppendSystemPrompt` | `[]string` | 빈 목록 | SystemPrompt 뒤에 결합 | untrusted text를 넣으면 system 권한으로 전송 |
| `DynamicBoundary` | `int` | 0: cache boundary 없음 | provider cacheable prefix 경계 | 범위가 끝 이상이면 Anthropic은 전체를 cacheable로 처리 |
| `Tools` | `[]tool.CoreTool` | nil: DefaultTools 9개; 빈 slice: 0개 | 명시 slice가 기본값 대체 | 중복 name은 registry에서 마지막 항목이 대체 |
| `DeferredTools` | `[]string` | 빈 목록: 비활성 | schema 노출에서 이름을 숨기고 access tool 2개 추가 | registry 실행 차단이 아니며 잘못된 이름은 발견 불가 |
| `UnlockSet` | `*tool.UnlockSet` | nil+deferred: 전부 unlocked로 seed | host set이 호출 gate 대체 | resume으로 자동 복원되지 않음 |
| `CanUseTool` | `permission.CanUseTool` | nil | ask 단계 host callback | 승인이 필요하면 nil은 deny |
| `AllowedTools` | `[]string` | 없음 | permission name rule allow | argument/resource scope는 평가하지 않음 |
| `DisallowedTools` | `[]string` | 없음 | permission name rule deny; allow보다 우선 | name-only match |
| `PermissionMode` | `permission.Mode` | 빈 값→default | session mode; plan controller가 동적으로 대체 가능 | unknown/empty semantics를 host가 명시하지 않으면 의도 혼동 |
| `Hooks` | `harness.HookRunner` | nil: 비활성 | lifecycle/tool/stop callback | timeout·panic recovery 없음 |
| `Compaction` | `*compaction.Config` | nil: 비활성 | built-in compactor 생성 | Compactor도 있으면 무시되고 OnWarn |
| `Compactor` | `harness.Compactor` | nil | host context manager; Compaction보다 우선 | ContextView 구현은 API message array 전체 책임 |
| `OnWarn` | `func(string)` | nil: 경고 폐기 | NewSession/adapter 비치명 진단 | nil이면 misconfiguration 관측 불가 |
| `Plan` | `*PlanOptions` | nil: 비활성 | plan tools와 mode controller 설치 | target/approver 오류는 실행 중 드러남 |
| `Memory` | `*MemoryOptions` | nil 또는 Store nil: 비활성 | memory tools·index·prompt injection | file 오류/낮은 relevance는 tool 결과 또는 누락 |
| `Skills` | `*skill.Registry` | nil: 비활성 | Skill tool 설치 | skill text는 user guidance로 주입 |
| `EnableWebFetch` | `bool` | false | true면 WebFetch 설치 | URL scope는 SDK가 제한하지 않음 |
| `WebFetchProxy` | `string` | 빈 값 + TLS zero: default transport proxy env; TLS override면 direct | WebFetchConfig.Proxy로 전달 | proxy 오류 fallback도 env를 다시 탈 수 있어 direct 보장 없음 |
| `WebFetchCACert` | `string` | 빈 값: system roots | InsecureTLS=false일 때 custom CA 추가 | read/parse 실패를 조용히 무시해 system roots로 남을 수 있음 |
| `WebFetchInsecureTLS` | `bool` | false | true면 CA보다 우선해 verify skip | TLS 진위 보장 상실 |
| `EnableWebSearch` | `bool` | false | true면 backend tool 구성 | 구성 오류 시 NewSession이 오류/경고 없이 tool을 생략 |
| `WebSearchBackend` | `string` | 빈 값→ddgs | backend 선택 | 알 수 없는 값은 tool 생략 |
| `BraveSearchAPIKey` | `string` | 없음 | brave-free일 때만 사용 | 필수 key 없음→tool 생략 |
| `TavilySearchAPIKey` | `string` | 없음 | tavily일 때만 사용 | 필수 key 없음→tool 생략 |
| `DeepSeekSearchBaseURL` | `string` | 없음 | deepseek Anthropic-format root | 없음/형식 불일치→생략 또는 HTTP 실패 |
| `DeepSeekSearchAPIKey` | `string` | 없음 | deepseek x-api-key | 없음→tool 생략 |
| `DeepSeekSearchModel` | `string` | 없음 | deepseek request model | 없음→tool 생략 |
| `WebSearchProxy` | `string` | 빈 값 + TLS zero: default transport proxy env; TLS override면 direct | search HTTP client proxy | scope/recording 강제점이 아님 |
| `WebSearchCACert` | `string` | 빈 값: system roots | search custom CA | invalid file/PEM은 조용히 무시 |
| `WebSearchInsecureTLS` | `bool` | false | true면 verify skip | TLS 진위 보장 상실 |
| `Todos` | `*tool.TodoStore` | nil: 비활성 | TodoWrite 설치·reminder source | in-memory라 process 재시작 시 소실 |
| `AskUser` | `tool.AskUserFunc` | nil: 비활성 | AskUserQuestion 설치 | callback은 동기 block; timeout 없음 |
| `SystemReminderFunc` | `func() string` | nil: 날짜만 | 매 Prompt마다 날짜 뒤 extra 생성 | callback 실패 계약 없음 |
| `MaxTurns` | `int` | 0: 제한 없음 | harness main turn cap | 업무 완료가 아니라 max_turns terminal |
| `MaxDuration` | `time.Duration` | 0: 제한 없음 | turn 경계 budget·tool context deadline | model stream hard timeout이 아님 |
| `Settlement` | `*harness.Settlement` | nil/빈 Prompt: 비활성 | budget 종료 뒤 bounded wrap-up | 원래 terminal reason은 유지 |
| `MaxTokens` | `int` | 0: provider별 기본/생략 | model output cap | Anthropic은 8192; 다른 format 의미가 다름 |
| `Temperature` | `*float64` | nil: 생략 | provider request | gateway가 지원하지 않으면 request 실패 |
| `MaxConcurrency` | `int` | <=0→10 | concurrency-safe tool semaphore | tool metadata가 틀리면 shared-state race |
| `WorkingDir` | `string` | 빈 값 그대로 | file/process tool base | sandbox가 아니며 absolute/.. 차단 없음 |
| `ToolOutputDir` | `string` | 빈 값: spill 안 함 | oversize result full-text spill | evidence store/atomic ledger가 아님 |
| `MaxToolOutputChars` | `int` | <=0→30000 | model에 보낼 tool output head | 초과분은 spill 없으면 손실 |
| `BashEnv` | `[]string` | 빈 값: inherited env | Bash/background child env override | secret와 proxy가 child로 전파 |
| `Transcript` | `*transcript.Store` | nil: memory-only | JSONL writer·Resume prerequisite | append 오류는 Writer.Err에 남고 terminal로 자동 승격 안 됨 |
| `SessionID` | `string` | 빈 값→random id | transcript/task path identity | host 제공 값의 path 안전성 검증 없음 |
| `TokenBudget` | `int` | <=0: 비활성 | 약 90%까지 continuation nudge | 비용 상한/업무 성공 보장이 아님 |
| `EscalateMaxTokens` | `bool` | false | max_tokens 때 64k 재시도 우선 | provider cap/비용 증가 가능 |
| `DisableBackgroundTasks` | `bool` | false | true면 자동 task tools/manager 미설치 | global env disable도 별도 우선 |
| `NonStreaming` | `bool` | false: streaming | true면 Provider.Complete | event는 조립 뒤 한꺼번에 전달 |
| `Deps` | `harness.QueryDeps` | zero: production defaults | model/tool/time side-effect boundary 대체 | 부분 override는 withDefaults가 빈 항목 보충 |

[소스 근거](evidence:agentcore-newsession)

<a id="plan-options"></a>

## `agentcore.PlanOptions` — 3 fields

| field | type | default | override/consumer | failure semantics |
|---|---|---|---|---|
| `Approver` | `plan.Approver` | nil: 자동 승인 | ExitPlanMode 승인 callback | 동기 callback; 거부 feedback만 tool result |
| `StartInPlanMode` | `bool` | false | true면 초기 mode=plan | mutating tools가 deny |
| `TargetMode` | `permission.Mode` | 빈 값 → `acceptEdits` | 승인 뒤 controller mode | 빈 값도 파일 편집을 자동 허용하므로 더 좁은 target이 필요하면 명시해야 함 |

[소스 근거](evidence:agentcore-newsession)

<a id="memory-options"></a>

## `agentcore.MemoryOptions` — 4 fields

| field | type | default | override/consumer | failure semantics |
|---|---|---|---|---|
| `Store` | `*memory.Store` | nil: memory 기능 미설치 | tool/index/injection 소유자 | directory I/O 오류 |
| `AutoInject` | `bool` | false | Prompt마다 Relevant 결과 선행 user text로 주입 | relevance는 단순 token match |
| `MaxInject` | `int` | <=0→3 | auto-inject 개수 | 큰 값은 context 증가 |
| `IncludeIndexInPrompt` | `bool` | false | system segments에 MEMORY.md index 추가 | index가 stale/누락일 수 있음 |

[소스 근거](evidence:agentcore-prompt)

<a id="llm-config"></a>

## `llm.Config` — 15 exported fields

| field | type | default | override/consumer | failure semantics |
|---|---|---|---|---|
| `Format` | `llm.Format` | 없음 | anthropic/openai/openai-responses adapter 선택 | 알 수 없는 값은 NewProvider error |
| `BaseURL` | `string` | format env→공식 endpoint | 명시 값이 env/default보다 우선 | path suffix가 예상과 다르면 잘못된 endpoint |
| `APIKey` | `string` | format env | 명시 값이 env보다 우선 | 빈 값도 construction 성공, HTTP auth 실패 |
| `Model` | `string` | 없음 | request model | 빈/unsupported model은 HTTP 실패 |
| `APIVersion` | `string` | Anthropic 2023-06-01 | Anthropic header | 다른 format은 무시 |
| `HTTPClient` | `*http.Client` | nil→built-in client | 설정 시 Proxy 포함 built-in transport 전체 대체 | nil transport timeout은 host 책임 |
| `Proxy` | `string` | 빈 값→`HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` 또는 lowercase alias | HTTPClient가 nil일 때 built-in transport만 사용 | CGI `REQUEST_METHOD` 환경의 HTTP proxy 거부; scheme 누락/unsupported는 NewProvider error |
| `MaxRetries` | `int` | 0→3; 음수→0 | request establishment retry | mid-stream drop은 retry 안 함 |
| `RetryInterval` | `time.Duration` | 0→0.5/1/2s… max 8s | 양수는 fixed interval | context 취소로 중단 |
| `EmptyResponseRetries` | `int` | 0→2; 음수→0 | OpenAI Chat 정상 empty response 전체 재요청 | prompt 비용 재발생; 다른 format 무관 |
| `EmptyResponseInterval` | `time.Duration` | 0→exponential | empty-response retry wait | 다른 format 무관 |
| `RateLimit` | `*llm.RateLimit` | nil: 비활성 | provider instance 공유 request gate | retry는 추가 count 안 됨; 분산/global limit 아님 |
| `ThinkingType` | `string` | 빈 값: omitted | request/per-request override가 우선 | provider-specific invalid value는 HTTP 실패 |
| `ReasoningEffort` | `string` | 빈 값: omitted | Anthropic output_config/OpenAI reasoning field | gateway 지원 여부에 따라 실패 |
| `MaxTokensField` | `string` | 빈 값→max_tokens | OpenAI Chat에서 completion variant opt-in | Anthropic/Responses는 무시 |

[소스 근거](evidence:llm-provider)

<a id="coordinator-config"></a>

## `coordinator.Config` — 10 fields

| field | type | default | override/consumer | failure semantics |
|---|---|---|---|---|
| `Provider` | `llm.Provider` | 없음 | 모든 worker | nil은 model call 실패 |
| `WorkerTools` | `*tool.Registry` | nil | child parent registry | nil이면 worker tools 0개 |
| `WorkerPrompt` | `[]string` | 빈 값→DefaultWorkerPrompt | worker system | host policy는 별도 |
| `PermissionMode` | `permission.Mode` | 빈 값→acceptEdits | worker mode | shared working dir 부작용 가능 |
| `WorkingDir` | `string` | 빈 값 | RunParallel child directory | sandbox 아님 |
| `MaxTurns` | `int` | 0: 제한 없음 | 각 worker Definition | 무제한 loop 가능 |
| `MaxDepth` | `int` | <=0→subagent 3 | child recursion | depth 초과 tool error |
| `MaxParallel` | `int` | <=0→4 | RunParallel semaphore | shared tools/filesystem race |
| `CanUseTool` | `permission.CanUseTool` | nil | worker approval | ask action deny |
| `Hooks` | `harness.HookRunner` | nil | worker hooks | concurrent callback 안전성 host 책임 |

[소스 근거](evidence:coordinator)

<a id="subagent-config"></a>

## `subagent.Config` — 7 fields

| field | type | default | override/consumer | failure semantics |
|---|---|---|---|---|
| `Provider` | `llm.Provider` | 없음 | child model | nil 실패 |
| `ParentTools` | `*tool.Registry` | nil | Definition.Tools로 filter | nil→빈 registry |
| `Agents` | `map[string]Definition` | nil | agent_type catalog | unknown type tool error |
| `MaxDepth` | `int` | <=0→3 | context depth guard | 초과 tool error |
| `CanUseTool` | `permission.CanUseTool` | nil | child permission | ask action deny |
| `Hooks` | `harness.HookRunner` | nil | SubagentStart와 child hooks | callback isolation 없음 |
| `Transcript` | `*transcript.Store` | nil | sidechain writer | parent session id 없으면 새 id; append 오류 별도 |

[소스 근거](evidence:subagent)

<a id="noa-config"></a>

## `noa.Config` — 10 top-level fields

| field | type | default | override/consumer | failure semantics |
|---|---|---|---|---|
| `ModelContextLimit` | `int` | DefaultConfig 인자; adapter 최종 <=0→200000 | pressure 비율 기준 | 실제 model window 불일치 시 잘못된 압축 |
| `Tiers` | `noa.TierConfig` | DefaultConfig: enabled,max=3,triggers=5/10 | multi-tier consolidation | partial Config는 default merge 안 됨; validation은 warning |
| `Nudge` | `noa.NudgeConfig` | DefaultConfig: .75/.45/.95, growth 50k 등 | nudge cadence/pressure | 잘못된 비율은 warning 후 계속 |
| `Truncate` | `noa.TruncateConfig` | threshold .95 | mechanical last resort | 범위 밖은 warning 후 계속 |
| `Compress` | `noa.CompressConfig` | range 5000 chars, summary 50..20000 | Compress input validation | min>=max는 warning 후 계속 |
| `ProtectedTools` | `[]string` | 없음; Compress는 별도 always-protected | pattern-based exclusion | pattern 과포함/누락 |
| `IsToolProtected` | `func(string) bool` | nil | host protection predicate | callback panic recovery 없음 |
| `PreserveRecentMessages` | `int` | 5 | tail soft zone | partial Config zero면 보존 감소 |
| `PreserveRecentTokens` | `int` | 5000 | tail soft token zone | estimator 오차 |
| `MaxCompressAttempts` | `int` | 3 | nudge suppression threshold | <1 warning 후 계속 |

[소스 근거](evidence:noa-config)

<a id="noaadapter-options"></a>

## `noaadapter.Options` — 7 fields

| field | type | default | override/consumer | failure semantics |
|---|---|---|---|---|
| `ArchiveBaseDir` | `string` | 필수 | session archive/state root | 빈 값→ErrNoArchiveDir |
| `SessionID` | `string` | 빈 값 허용 | base dir 아래 subdir | 빈/unsafe id collision/path risk |
| `Config` | `*noa.Config` | nil→DefaultConfig(ModelContextLimit) | non-nil은 전체 대체, merge 아님 | partial config zero values 유지 |
| `ModelContextLimit` | `int` | Config nil일 때 사용; 최종 <=0→200000 | default config sizing | 실제 model과 불일치 |
| `ParentSessionIDs` | `[]string` | 없음 | 자기 block 없을 때 최근 ancestor state 상속 | 최대 깊이/누락 시 fresh |
| `OnWarn` | `func(string)` | nil: warning 폐기 | config/state/inheritance 진단 | corrupt state fallback을 놓침 |
| `Now` | `func() time.Time` | nil→time.Now | archive/state timestamps | test/host clock 품질 |

[소스 근거](evidence:noa-projection)

<a id="webfetch-config"></a>

## `tool.WebFetchConfig` — 3 fields

| field | type | default | override/consumer | failure semantics |
|---|---|---|---|---|
| `Proxy` | `string` | 빈 값 + TLS zero: default transport proxy env; TLS override면 direct | explicit http(s) proxy | invalid URL은 조용히 proxy 없이 동작 가능 |
| `CACert` | `string` | 빈 값: system roots | InsecureTLS=false일 때 pool 추가 | read/PEM 실패 조용히 무시 |
| `InsecureTLS` | `bool` | false | true면 verify skip, CACert 무시 | TLS 진위 상실 |

[소스 근거](evidence:webfetch-config)

<a id="websearch-config"></a>

## `tool.WebSearchConfig` — 9 fields

| field | type | default | override/consumer | failure semantics |
|---|---|---|---|---|
| `Backend` | `string` | 빈 값→ddgs | provider selector | unknown→constructor error |
| `BraveAPIKey` | `string` | 없음 | brave-free auth | 없음→error |
| `TavilyAPIKey` | `string` | 없음 | tavily body auth | 없음→error |
| `DeepSeekBaseURL` | `string` | 없음 | Anthropic-format /v1/messages root | 없음→error; wrong profile HTTP 실패 |
| `DeepSeekAPIKey` | `string` | 없음 | x-api-key | 없음→error |
| `DeepSeekModel` | `string` | 없음 | model id | 없음→error |
| `Proxy` | `string` | 빈 값 + TLS zero: default transport proxy env; TLS override면 direct | backend explicit HTTP transport | recording/scope gate 아님 |
| `CACert` | `string` | 빈 값: system roots | custom trust | invalid 값 조용히 무시 |
| `InsecureTLS` | `bool` | false | verify skip | TLS 진위 상실 |

[소스 근거](evidence:websearch-config)

<a id="precedence"></a>

## 자주 틀리는 우선순위

1. `Compactor`가 있으면 `Compaction`은 무시되고 `OnWarn`으로만 알린다.
2. custom `HTTPClient`는 `llm.Config.Proxy`보다 우선한다. built-in LLM client에서 빈 Proxy만 `HTTP_PROXY`·`HTTPS_PROXY`·`NO_PROXY`와 lowercase alias를 사용하며, `REQUEST_METHOD`가 있는 CGI 환경의 HTTP proxy에는 표준 라이브러리 거부 규칙이 적용된다.
3. WebFetch/WebSearch는 Proxy·CA·insecure가 모두 zero일 때 nil Transport를 통해 default transport와 proxy environment를 상속한다. CA 또는 insecure만 설정하면 새 transport의 Proxy가 nil이어서 환경 proxy를 우회한다.
4. `Tools == nil`만 기본 9개를 넣는다. 의도적으로 빈 slice를 주면 기본 tool도 없다.
5. `noaadapter.Options.Config != nil`이면 전체 struct가 채택된다. 부분 override라는 의미가 아니다.
6. `EnableWebSearch`의 config 오류는 `NewSession` 반환값이 없어 호출자에게 전파되지 않고 tool이 조용히 빠진다. 직접 검증하려면 `tool.NewWebSearch` 또는 `WebSearchProbe` 결과를 확인한다.

[LLM transport 근거](evidence:llm-http-client) [Web tool transport 근거](evidence:web-tool-http-client)