Ch2. 고급 설정
구성 파일 계층, 환경 변수, AGENTS.md 규칙, 원격 설정
OpenCode 설정은 JSON/JSONC 구성 파일과 환경 변수로 제어합니다. 팀 환경에서는 일관된 기본값을 먼저 설계하고 프로젝트별로 최소한만 덮어쓰는 방식이 효과적입니다.
구성 파일 계층 (우선순위)
나중에 로드되는 설정이 앞선 설정을 덮어씁니다.
| 순서 | 위치 | 용도 |
|---|---|---|
| 1 | .well-known/opencode 엔드포인트 | 조직 기본값 (원격) |
| 2 | ~/.config/opencode/opencode.json | 사용자 기본값 |
| 3 | OPENCODE_CONFIG 환경 변수 | 사용자 지정 오버라이드 |
| 4 | opencode.json (프로젝트 루트) | 프로젝트 전용 |
| 5 | .opencode/ 디렉토리 | agents/commands/plugins |
| 6 | OPENCODE_CONFIG_CONTENT 환경 변수 | 런타임 오버라이드 |
전체 설정 예시
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-5",
"small_model": "anthropic/claude-haiku-4-5",
"provider": {
"anthropic": {
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
}
},
"tools": {
"write": true,
"bash": true
},
"permission": {
"edit": "ask",
"bash": "ask",
"webfetch": "allow"
},
"agent": {},
"autoupdate": true,
"share": "manual",
"lsp": {},
"plugin": [],
"instructions": ["docs/guidelines.md"]
}변수 치환
설정 파일 내에서 동적 값을 주입할 수 있습니다.
| 문법 | 설명 | 예시 |
|---|---|---|
{env:VAR} | 환경 변수 참조 | "{env:ANTHROPIC_API_KEY}" |
{file:path} | 파일 내용 참조 | "{file:.secrets/key}" |
비밀정보 관리
API 키는 opencode.json에 직접 넣지 말고 반드시 {env:VAR} 형식으로 환경 변수에서 주입하세요.
AGENTS.md 규칙 시스템
LLM 행동을 커스터마이즈하는 규칙 파일입니다. Cursor의 rules와 유사한 개념입니다.
파일 위치와 우선순위
| 위치 | 범위 |
|---|---|
프로젝트 루트 AGENTS.md | 팀 공유 (Git 커밋 대상) |
~/.config/opencode/AGENTS.md | 개인 전역 설정 |
CLAUDE.md (호환 모드) | Claude Code에서 마이그레이션 시 |
AGENTS.md가 CLAUDE.md보다 우선합니다. Claude Code 호환 모드를 끄려면 OPENCODE_DISABLE_CLAUDE_CODE 환경 변수를 설정합니다.
외부 파일 참조
{
"instructions": ["docs/guidelines.md", "packages/*/AGENTS.md"]
}자동 생성
/init 슬래시 커맨드로 프로젝트를 분석해 AGENTS.md를 자동 생성할 수 있습니다.
주요 환경 변수
| 변수 | 용도 |
|---|---|
OPENCODE_CONFIG | 커스텀 설정 파일 경로 |
OPENCODE_CONFIG_CONTENT | 인라인 JSON 설정 |
OPENCODE_SERVER_PASSWORD | HTTP 인증 활성화 |
OPENCODE_CLIENT | 클라이언트 식별자 (기본: cli) |
OPENCODE_DISABLE_AUTOUPDATE | 자동 업데이트 비활성화 |
OPENCODE_EXPERIMENTAL_LSP_TOOL | 실험적 LSP 도구 활성화 |
OPENCODE_ENABLE_EXA | 웹 검색 도구 활성화 |
OPENCODE_DISABLE_LSP_DOWNLOAD | LSP 서버 자동 설치 방지 |
OPENCODE_TUI_CONFIG | TUI 설정 파일 경로 |
OPENCODE_DISABLE_CLAUDE_CODE | CLAUDE.md 호환 모드 비활성화 |
TUI 설정 분리 (tui.json)
v1.2.15부터 TUI 설정은 별도 파일로 관리합니다.
{
"$schema": "https://opencode.ai/tui.json",
"theme": "dark",
"keybinds": {
"session_compact": "none",
"session_new": "<leader>n"
},
"scroll_speed": 3,
"scroll_acceleration": {
"enabled": true
},
"diff_style": "auto"
}원격 설정 활용
조직 공통 설정을 원격에 두고, 로컬에서 최소한만 덮어쓰는 패턴입니다.
원격 엔드포인트 구성
조직 도메인의 .well-known/opencode 경로에 JSON 설정을 호스팅합니다.
프로젝트별 오버라이드
opencode.json에서 조직 기본값 위에 프로젝트 고유 설정만 추가합니다.
고급 팁
- 환경별 분리: CI 전용 설정은
OPENCODE_CONFIG로 분리 - 비밀정보 분리: 토큰은
{env:VAR}형식으로만 관리 - 커스텀 디렉토리:
.opencode/하위에 agents, commands, plugins 분리 - 성능 튜닝: TUI 스크롤 속도/가속을 팀 표준으로 고정
참고 문서
- 설정 파일과 우선순위: https://opencode.ai/docs/config
- 규칙 시스템 (AGENTS.md): https://opencode.ai/docs/rules
- TUI 설정: https://opencode.ai/docs/tui