구성

OpenCode JSON 구성을 사용합니다.

JSON 구성 파일을 사용하여 OpenCode를 구성할 수 있습니다.

형식

OpenCode는 JSON 및 JSONC (주석이 있는 JSON) 형식을 모두 지원합니다.

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}

위치

구성을 여러 위치에 배치할 수 있으며 우선순위가 다릅니다.

[!NOTE] 구성 파일은 병합되며 대체되지 않습니다.

구성 소스는 이 순서로 로드됩니다 (이후 소스가 이전 소스를 재정의):

원격 구성 (.well-known/opencode에서) - 조직 기본값
전역 구성 (~/.config/opencode/opencode.json) - 사용자 기본 설정
커스텀 구성 (OPENCODE_CONFIG 환경 변수) - 커스텀 재정의
프로젝트 구성 (프로젝트의 opencode.json) - 프로젝트별 설정
.opencode 디렉토리 - 에이전트, 명령어, 플러그인
인라인 구성 (OPENCODE_CONFIG_CONTENT 환경 변수) - 런타임 재정의
관리 구성 파일 (macOS의 /Library/Application Support/opencode/) - 관리자 제어
macOS 관리 기본 설정 (MDM을 통한 .mobileconfig) - 가장 높은 우선순위, 사용자 재정의 불가

원격

조직은 .well-known/opencode 엔드포인트를 통해 기본 구성을 제공할 수 있습니다.

opencode.json

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

전역

전역 OpenCode 구성을 ~/.config/opencode/opencode.json에 배치합니다.

프로젝트별

프로젝트 루트에 opencode.json을 추가합니다.

[!TIP] 프로젝트별 구성을 프로젝트 루트에 배치합니다.

커스텀 경로

OPENCODE_CONFIG 환경 변수를 사용하여 커스텀 구성 파일 경로를 지정합니다.

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

커스텀 디렉토리

OPENCODE_CONFIG_DIR 환경 변수를 사용하여 커스텀 구성 디렉토리를 지정합니다.

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

관리 설정

조직은 사용자가 재정의할 수 없는 구성을 적용할 수 있습니다.

플랫폼	경로
macOS	`/Library/Application Support/opencode/`
Linux	`/etc/opencode/`
Windows	`%ProgramData%\opencode`

스키마

서버/런타임 구성 스키마는 opencode.ai/config.json에 정의되어 있습니다.

편집기에서 스키마를 기반으로 검증 및 자동완성을 수행할 수 있습니다.

TUI

TUI별 설정에는 전용 tui.json (또는 tui.jsonc) 파일을 사용합니다.

tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "scroll_speed": 3,
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

서버

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

사용 가능한 옵션:

port - 수신 대기 포트
hostname - 수신 대기 호스트명, mdns 활성화 시 기본값 0.0.0.0
mdns - mDNS 서비스 검색 활성화,局域网 내 다른 기기가 OpenCode 서버를 검색할 수 있도록 허용
mdnsDomain - 커스텀 mDNS 도메인 이름, 기본값 opencode.local
cors - 추가 CORS 허용 오리진, 값은 전체 출처여야 함 (scheme + host + 선택적 포트)

셸

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "shell": "pwsh"
}

도구

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

모델

opencode.json

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

Provider 옵션:

timeout - 요청 시간 제한 (밀리초), 기본값 300000
chunkTimeout - 스트리밍 응답 청크 간 시간 제한
setCacheKey - 지정된 provider에 항상 캐시 키 설정 보장

정책

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "policies": [
      {
        "effect": "deny",
        "action": "provider.use",
        "resource": "openai"
      }
    ]
  }
}

이미지 첨부

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880
    }
  }
}

테마

tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight"
}

에이전트

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "모범 사례 및 잠재적 문제에 대해 코드 검토",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "당신은 코드 검토자입니다.",
      "tools": {
        "write": false,
        "edit": false,
      },
    },
  },
}

기본 에이전트

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan"
}

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

"manual" - 명령으로 수동 공유 (기본값)
"auto" - 새 대화 자동 공유
"disabled" - 공유 완전 비활성화

명령어

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "전체 테스트 스위트를 커버리지 보고서와 함께 실행합니다.",
      "description": "커버리지와 함께 테스트 실행",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5",
    },
  },
}

키바인드

tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {
    "command_list": "ctrl+p"
  }
}

스냅샷

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "snapshot": false
}

자동 업데이트

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false
}

false - 자동 업데이트 비활성화
"notify" - 자동 업데이트하지 않지만 새 버전이 있으면 알림

포맷터

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": true
}

LSP 서버

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": true
}

권한

opencode.json

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

압축

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": false,
    "reserved": 10000
  }
}

auto - 컨텍스트가 가득 찼을 때 자동 압축 (기본값 true)
prune - 토큰을 절약하기 위해 이전 도구 출력 삭제 (기본값 false)
reserved - 압축 시 유지할 토큰 버퍼

워처

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

MCP 서버

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}

플러그인

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

지침

opencode.json

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

비활성화된 provider

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

활성화된 provider

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

[!NOTE] disabled_providers가 enabled_providers보다 우선합니다

실험적

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {}
}

변수

환경 변수

{env:VARIABLE_NAME}을 사용하여 환경 변수를 참조합니다:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

파일

{file:path/to/file}을 사용하여 파일 내용을 참조합니다:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

구성

구성

형식

위치

원격

전역

프로젝트별

커스텀 경로

커스텀 디렉토리

관리 설정

스키마

TUI

서버

셸

도구

모델

정책

이미지 첨부

테마

에이전트

기본 에이전트

공유

명령어

키바인드

스냅샷

자동 업데이트

포맷터

LSP 서버

권한

압축

워처

MCP 서버

플러그인

지침

비활성화된 provider

활성화된 provider

실험적

변수

환경 변수

파일