Ch2. 고급 설정
opencode.json 6단계 구성 파일 우선순위, env·file 변수 치환, AGENTS.md 규칙 시스템, tui.json 분리와 .well-known 원격 설정을 다룹니다.
핵심 요약
- 설정은 원격(
.well-known/opencode) → 글로벌 →OPENCODE_CONFIG→ 프로젝트opencode.json→.opencode/→OPENCODE_CONFIG_CONTENT순서로 6단계 우선순위가 정해지고, 나중 값이 앞을 덮어씁니다. - API 키는 파일에 직접 넣지 말고
{env:VAR}(환경 변수)나{file:path}(파일 참조)로 주입합니다. AGENTS.md는 LLM 행동 규칙 파일로CLAUDE.md보다 우선하며,/init으로 자동 생성하고OPENCODE_DISABLE_CLAUDE_CODE로 호환 모드를 끕니다.- v1.2.15부터 TUI 설정은
tui.json으로 분리되어 테마·키바인드·스크롤 속도를 관리합니다. - 조직 공통값은
.well-known/opencode에 원격으로 호스팅하고, 프로젝트에서는 고유 설정만 덮어쓰는 패턴을 권합니다.
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