~18 min · options, configuration, ClaudeAgentOptions
Level 0Observer
0 XP0/64 lessons0/13 achievements
0/150 XP to next level150 XP to go0% complete
설정 객체가 실행 계약이야
ClaudeAgentOptions에는 작업 디렉터리, 시스템 프롬프트, 존재하는 도구와 미리 승인한 도구, MCP 서버, 훅, 모델, 사고 설정, 환경변수가 들어가. 자유로운 키워드 인자 주머니로 흩뜨리지 말고 타입이 있는 정책 구조체로 다뤄야 어떤 에이전트가 무엇을 할 수 있는지 한눈에 보여.
자주 쓰는 손잡이를 구분해
cwd는 작업 범위, system_prompt는 프리셋이나 직접 쓴 지침, tools는 기본 도구 중 무엇이 존재할지([]면 전부 꺼져), allowed_tools는 그중 무엇이 권한 질문 없이 돌지 정해. allowed_tools는 아무것도 막지 않아. 아예 빼려면 disallowed_tools야. model은 Claude 티어를 정해. permission_mode는 default·acceptEdits·bypassPermissions·plan·dontAsk(새 릴리스엔 더 있어) 중 고르고, mcp_servers와 hooks, env가 외부 능력과 실행 환경을 잇지.
bypassPermissions는 운영 기본값이 아니야
permission_mode='bypassPermissions'는 모든 권한 문을 없애. 이미 다른 검토를 통과한 신뢰 가능한 CI에는 쓸 수 있지만 사용자 요청을 받는 에이전트에는 위험해. 기본적으로 default나 파일 편집만 자동 승인하는 acceptEdits를 택하고, 우회가 꼭 필요하면 이유와 피해 범위를 기록해.
원칙: 에이전트 행동은 프롬프트 문구만이 아니라 Options 객체가 정한 정책의 결과야.
Code
운영 모양의 options 객체·python
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
cwd="/srv/myapp",
model="claude-sonnet-4-6",
system_prompt="You are a deployment review assistant. Read CHANGELOG.md and report risks.",
tools=["Read", "Grep", "Bash"], # 존재하는 도구: Write도 Edit도 없어
allowed_tools=["Read", "Grep"], # 묻지 않고 도는 도구
permission_mode="default", # Bash는 여전히 물어
env={"PATH": "/usr/local/bin:/usr/bin"}, # 부모 환경 위에 덮어써져
thinking={"type": "adaptive"}, # max_thinking_tokens는 deprecated
)
읽기 전용으로 도구 줄이기·python
from claude_agent_sdk import ClaudeAgentOptions
# tools=는 무엇이 존재할지 정하고, allowed_tools=는 무엇이 질문을 건너뛸지만 정해.
READ_ONLY_TOOLS = ["Read", "Grep", "Glob", "WebFetch"]
options = ClaudeAgentOptions(
cwd="/data/audit",
tools=READ_ONLY_TOOLS, # Write, Edit, Bash는 모델 도구함에 아예 없어
allowed_tools=READ_ONLY_TOOLS, # 그리고 이 넷은 묻지 않고 돌아
system_prompt="You are a read-only auditor. Never modify files.",
)