OpenCode 설정(opencode.json) 완전 정리: 어디에 두고, 어떤 키를 쓰면 될까?

OpenCode 설정(opencode.json) 완전 정리: 어디에 두고, 어떤 키를 쓰면 될까?

OpenCode를 제대로 쓰려면 결국 한 번은 **설정 파일(opencode.json / opencode.jsonc)**을 잡아야 합니다.
모델/툴 권한/에이전트/명령어/MCP까지, 프로젝트마다 “일하는 방식”을 안정적으로 고정할 수 있어요. (OpenCode)

이번 글에서는 OpenCode 공식 문서 기준으로 설정 파일 형식, 위치 우선순위(머지 방식), 자주 쓰는 핵심 옵션만 딱 정리해볼게요. (OpenCode)

---

1) 설정 파일 형식: JSON도 되고 JSONC도 된다

OpenCode 설정은 JSON / JSONC(JSON + 주석) 둘 다 지원합니다.
그래서 opencode.jsonc로 두고 주석 달아가며 관리하는 게 꽤 편해요. (OpenCode)

예시(문서 예시):

{
  "$schema": "https://opencode.ai/config.json",
  // Theme configuration
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

(OpenCode)

---

2) 설정은 “덮어쓰기”가 아니라 “머지(merge)”

중요 포인트: OpenCode 설정은 여러 위치의 설정 파일을 합쳐서(merge) 사용합니다.
뒤에 로드된 설정이 충돌 키만 override하고, 충돌 없는 값은 유지돼요. (OpenCode)

예: 글로벌에서 theme, autoupdate를 정하고 프로젝트에서 model만 정하면 최종 설정엔 3개가 다 포함됩니다. (OpenCode)

---

3) 설정 파일 위치와 우선순위(Precedence)

문서 기준 로딩 순서는 아래예요. (뒤에 올수록 우선) (OpenCode)

1. Remote config: .well-known/opencode (조직 기본값)
2. Global config: ~/.config/opencode/opencode.json (개인 기본값)
3. Custom config: OPENCODE_CONFIG 환경변수로 지정한 파일
4. Project config: 프로젝트 루트의 opencode.json
5. .opencode 디렉터리: agents/commands/plugins 등
6. Inline config: OPENCODE_CONFIG_CONTENT 환경변수(런타임 override) (OpenCode)

실무 팁:

• 팀 공통 기본값은 Remote config(조직 레벨)로 밀고,
• 개인 취향은 Global,
• 프로젝트 성격은 Project config로 잡는 구조가 가장 깔끔합니다. (OpenCode)

또한 .opencode / ~/.config/opencode 아래의 하위 폴더명은 agents/, commands/, plugins/ 같은 복수형을 권장하지만, 예전 호환을 위해 단수형도 지원합니다. (OpenCode)

---

4) “자주 만지는 핵심 옵션”만 빠르게 정리

(1) 모델: model / small_model

• model: 메인 모델
• small_model: 타이틀 생성 같은 가벼운 작업용 별도 모델(가능하면 더 저렴한 모델을 쓰도록 설계) (OpenCode)

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

(OpenCode)

(2) tools / permission: “AI가 할 수 있는 행동” 통제

• tools: 특정 도구(예: write, bash) 자체를 켜고 끄기 (OpenCode)
• permission: 기본은 다 허용인데, ask/deny/allow로 승인 흐름을 만들 수 있음 (OpenCode)

{
  "$schema": "https://opencode.ai/config.json",
  "permission": { "edit": "ask", "bash": "ask" }
}

(OpenCode)

(3) agent / default_agent: 역할별 에이전트 세팅

에이전트를 “코드리뷰 전용(쓰기/수정 금지)” 같은 형태로 만들 수 있고, default_agent로 기본 에이전트도 지정 가능해요. (OpenCode)

(4) command: 반복 작업을 슬래시 명령어로

/test, /component 같은 반복 작업을 config에 등록할 수 있습니다. (OpenCode)

(5) formatter / compaction / watcher: 품질 + 토큰 + 소음 관리

• formatter: 포매터 비활성/커스텀 커맨드 지정 가능 (OpenCode)
• compaction: 컨텍스트가 찼을 때 자동 압축/도구 출력 prune (OpenCode)
• watcher.ignore: node_modules 같은 감시 제외 패턴 (OpenCode)

(6) mcp / plugin / instructions: 확장 기능 3종 세트

• mcp: MCP 서버 설정(별도 문서로 연결) (OpenCode)
• plugin: 플러그인을 로컬 폴더나 npm으로 로드 (OpenCode)
• instructions: 규칙 파일(예: CONTRIBUTING.md, 가이드라인)을 경로/글롭 패턴 배열로 묶어서 로드 (OpenCode)

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

(OpenCode)

(7) enabled_providers / disabled_providers: 공급자 허용·차단

• enabled_providers: 허용 리스트(이것만 켬) (OpenCode)
• disabled_providers: 차단 리스트(환경변수//connect로 키가 있어도 로드 안 됨) (OpenCode)
• 둘 다 있으면 disabled가 우선 (OpenCode)

---

5) 변수 치환(Variables): 키를 코드에 박지 말자

설정 파일에서 민감정보를 안전하게 관리할 수 있도록 변수 치환을 지원합니다. (OpenCode)

Env vars

{env:VARIABLE_NAME} 형태로 환경변수를 삽입합니다. 없으면 빈 문자열로 대체돼요. (OpenCode)

Files

{file:path/to/file} 형태로 파일 내용을 삽입합니다. 경로는 config 기준 상대경로 또는 /·~ 절대경로 가능.
API 키를 파일로 분리하거나, 큰 지침 파일을 깔끔하게 관리할 때 유용합니다. (OpenCode)

---

마무리: 내가 추천하는 “최소 세팅” 방향

처음 세팅이라면 아래 3개만 잡아도 체감이 큽니다.

1. model / small_model 분리
2. permission에서 edit, bash는 최소 ask
3. 팀 규칙은 instructions로 모듈화(문서/컨벤션 파일들을 글롭으로) (OpenCode)

---