한국어
문서
설정

설정

OpenCode JSON 설정 사용하기.

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

형식

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

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  // 테마 설정
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

위치

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

참고: 설정 파일은 대체되지 않고 병합됩니다.

설정 파일은 대체되지 않고 병합됩니다. 다음 설정 위치의 설정이 결합됩니다. 나중 설정은 충돌하는 키에 대해서만 이전 설정을 재정의합니다. 모든 설정의 충돌하지 않는 설정은 유지됩니다.

예를 들어, 전역 설정이 theme: "opencode"와 autoupdate: true를 설정하고 프로젝트 설정이 model: "anthropic/claude-sonnet-4-5"를 설정하면 최종 설정에는 세 가지 설정이 모두 포함됩니다.

우선순위

설정 소스는 다음 순서로 로드됩니다 (나중 소스가 이전 소스를 재정의):

  • 원격 설정 (.well-known/opencode에서) - 조직 기본값
  • 전역 설정 (~/.config/opencode/opencode.json) - 사용자 기본 설정
  • 사용자 정의 설정 (OPENCODE_CONFIG 환경 변수) - 사용자 정의 재정의
  • 프로젝트 설정 (프로젝트의 opencode.json) - 프로젝트별 설정
  • .opencode 디렉토리 - 에이전트, 명령어, 플러그인
  • 인라인 설정 (OPENCODE_CONFIG_CONTENT 환경 변수) - 런타임 재정의

이는 프로젝트 설정이 전역 기본값을 재정의할 수 있고, 전역 설정이 원격 조직 기본값을 재정의할 수 있음을 의미합니다.

참고: .opencode와 ~/.config/opencode 디렉토리는 하위 디렉토리에 복수형 이름을 사용합니다: agents/, commands/, modes/, plugins/, skills/, tools/, themes/. 단수형 이름(예: agent/)도 하위 호환성을 위해 지원됩니다.

원격

조직은 .well-known/opencode 엔드포인트를 통해 기본 설정을 제공할 수 있습니다. 이것은 지원하는 프로바이더로 인증할 때 자동으로 가져옵니다.

원격 설정은 먼저 로드되어 기본 레이어 역할을 합니다. 다른 모든 설정 소스(전역, 프로젝트)가 이러한 기본값을 재정의할 수 있습니다.

예를 들어, 조직이 기본적으로 비활성화된 MCP 서버를 제공하는 경우:

.well-known/opencode의 원격 설정
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

로컬 설정에서 특정 서버를 활성화할 수 있습니다:

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

전역

전역 OpenCode 설정을 ~/.config/opencode/opencode.json에 배치하세요. 테마, 프로바이더 또는 키바인드와 같은 사용자 전체 기본 설정에 전역 설정을 사용하세요.

전역 설정은 원격 조직 기본값을 재정의합니다.

프로젝트별

프로젝트 루트에 opencode.json을 추가하세요. 프로젝트 설정은 표준 설정 파일 중 가장 높은 우선순위를 가집니다 - 전역 및 원격 설정을 모두 재정의합니다.

팁: 프로젝트별 설정을 프로젝트 루트에 배치하세요.

OpenCode가 시작되면 현재 디렉토리에서 설정 파일을 찾거나 가장 가까운 Git 디렉토리까지 위로 탐색합니다.

이것은 Git에 체크인해도 안전하며 전역 설정과 동일한 스키마를 사용합니다.

사용자 정의 경로

OPENCODE_CONFIG 환경 변수를 사용하여 사용자 정의 설정 파일 경로를 지정하세요.

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

사용자 정의 설정은 우선순위에서 전역과 프로젝트 설정 사이에 로드됩니다.

사용자 정의 디렉토리

OPENCODE_CONFIG_DIR 환경 변수를 사용하여 사용자 정의 설정 디렉토리를 지정하세요. 이 디렉토리는 표준 .opencode 디렉토리처럼 에이전트, 명령어, 모드, 플러그인을 검색하며 동일한 구조를 따라야 합니다.

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

사용자 정의 디렉토리는 전역 설정과 .opencode 디렉토리 이후에 로드되므로 해당 설정을 재정의할 수 있습니다.

스키마

설정 파일에는 opencode.ai/config.json (opens in a new tab)에 정의된 스키마가 있습니다.

에디터가 스키마를 기반으로 유효성 검사와 자동완성을 할 수 있어야 합니다.

TUI

tui 옵션을 통해 TUI 관련 설정을 구성할 수 있습니다.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

사용 가능한 옵션:

  • scroll_acceleration.enabled - macOS 스타일 스크롤 가속 활성화. scroll_speed보다 우선합니다.
  • scroll_speed - 사용자 정의 스크롤 속도 배율 (기본값: 3, 최소값: 1). scroll_acceleration.enabled가 true이면 무시됩니다.
  • diff_style - diff 렌더링 제어. "auto"는 터미널 너비에 맞게 조정하고, "stacked"는 항상 단일 열을 표시합니다.

TUI 사용에 대해 자세히 알아보기.

서버

server 옵션을 통해 opencode serve와 opencode web 명령에 대한 서버 설정을 구성할 수 있습니다.

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 - 브라우저 기반 클라이언트에서 HTTP 서버를 사용할 때 CORS에 허용할 추가 출처. 값은 전체 출처(스킴 + 호스트 + 선택적 포트)여야 합니다. 예: https://app.example.com.

서버에 대해 자세히 알아보기.

도구

tools 옵션을 통해 LLM이 사용할 수 있는 도구를 관리할 수 있습니다.

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

도구에 대해 자세히 알아보기.

모델

provider, model, small_model 옵션을 통해 OpenCode 설정에서 사용할 프로바이더와 모델을 구성할 수 있습니다.

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

small_model 옵션은 제목 생성과 같은 가벼운 작업을 위한 별도의 모델을 구성합니다. 기본적으로 OpenCode는 프로바이더에서 더 저렴한 모델이 있으면 사용하려고 하고, 그렇지 않으면 메인 모델로 폴백합니다.

프로바이더 옵션에는 timeout과 setCacheKey가 포함될 수 있습니다:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}
  • timeout - 요청 타임아웃(밀리초) (기본값: 300000). 비활성화하려면 false로 설정.
  • setCacheKey - 지정된 프로바이더에 대해 캐시 키가 항상 설정되도록 보장.

로컬 모델도 구성할 수 있습니다. 자세히 알아보기.

프로바이더별 옵션

일부 프로바이더는 일반적인 timeout과 apiKey 설정 외에 추가 구성 옵션을 지원합니다.

Amazon Bedrock

Amazon Bedrock은 AWS 관련 구성을 지원합니다:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}
  • region - Bedrock용 AWS 리전 (AWS_REGION 환경 변수 또는 us-east-1이 기본값)
  • profile - ~/.aws/credentials의 AWS 명명된 프로필 (AWS_PROFILE 환경 변수가 기본값)
  • endpoint - VPC 엔드포인트용 사용자 정의 엔드포인트 URL. AWS 관련 용어를 사용하는 일반 baseURL 옵션의 별칭입니다. 둘 다 지정되면 endpoint가 우선합니다.

참고: Bearer 토큰(AWS_BEARER_TOKEN_BEDROCK 또는 /connect)은 프로필 기반 인증보다 우선합니다. 자세한 내용은 인증 우선순위를 참조하세요.

Amazon Bedrock 구성에 대해 자세히 알아보기.

테마

theme 옵션을 통해 OpenCode 설정에서 사용할 테마를 구성할 수 있습니다.

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

자세히 알아보기.

에이전트

agent 옵션을 통해 특정 작업을 위한 전문 에이전트를 구성할 수 있습니다.

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // 리뷰 전용 에이전트를 위해 파일 수정 도구 비활성화
        "write": false,
        "edit": false
      }
    }
  }
}

~/.config/opencode/agents/ 또는 .opencode/agents/에 마크다운 파일을 사용하여 에이전트를 정의할 수도 있습니다. 자세히 알아보기.

기본 에이전트

default_agent 옵션을 사용하여 기본 에이전트를 설정할 수 있습니다. 이것은 명시적으로 지정되지 않았을 때 어떤 에이전트가 사용되는지 결정합니다.

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

기본 에이전트는 기본 에이전트여야 합니다(서브에이전트가 아님). "build" 또는 "plan"과 같은 내장 에이전트이거나 정의한 사용자 정의 에이전트일 수 있습니다. 지정된 에이전트가 존재하지 않거나 서브에이전트인 경우 OpenCode는 경고와 함께 "build"로 폴백합니다.

이 설정은 모든 인터페이스에 적용됩니다: TUI, CLI (opencode run), 데스크톱 앱, GitHub Action.

공유

share 옵션을 통해 공유 기능을 구성할 수 있습니다.

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

다음 값을 사용합니다:

  • "manual" - 명령을 통한 수동 공유 허용 (기본값)
  • "auto" - 새 대화 자동 공유
  • "disabled" - 공유 완전히 비활성화

기본적으로 공유는 /share 명령을 사용하여 명시적으로 대화를 공유해야 하는 수동 모드로 설정됩니다.

명령어

command 옵션을 통해 반복 작업을 위한 사용자 정의 명령어를 구성할 수 있습니다.

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

~/.config/opencode/commands/ 또는 .opencode/commands/에 마크다운 파일을 사용하여 명령어를 정의할 수도 있습니다. 자세히 알아보기.

키바인드

keybinds 옵션을 통해 키바인드를 사용자 정의할 수 있습니다.

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

자세히 알아보기.

자동 업데이트

OpenCode는 시작할 때 새 업데이트를 자동으로 다운로드합니다. autoupdate 옵션으로 이를 비활성화할 수 있습니다.

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

업데이트를 원하지 않지만 새 버전이 있을 때 알림을 받고 싶다면 autoupdate를 "notify"로 설정하세요. 이것은 Homebrew와 같은 패키지 관리자를 사용하여 설치하지 않은 경우에만 작동합니다.

포매터

formatter 옵션을 통해 코드 포매터를 구성할 수 있습니다.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

포매터에 대해 자세히 알아보기.

권한

기본적으로 opencode는 명시적 승인 없이 모든 작업을 허용합니다. permission 옵션을 사용하여 이를 변경할 수 있습니다.

예를 들어, edit와 bash 도구가 사용자 승인을 요구하도록 하려면:

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

권한에 대해 자세히 알아보기.

압축

compaction 옵션을 통해 컨텍스트 압축 동작을 제어할 수 있습니다.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}
  • auto - 컨텍스트가 가득 차면 자동으로 세션 압축 (기본값: true).
  • prune - 토큰을 절약하기 위해 오래된 도구 출력 제거 (기본값: true).

감시자

watcher 옵션을 통해 파일 감시자 무시 패턴을 구성할 수 있습니다.

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

패턴은 glob 구문을 따릅니다. 파일 감시에서 시끄러운 디렉토리를 제외하는 데 사용하세요.

MCP 서버

mcp 옵션을 통해 사용할 MCP 서버를 구성할 수 있습니다.

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

자세히 알아보기.

플러그인

플러그인은 사용자 정의 도구, 훅, 통합으로 OpenCode를 확장합니다.

.opencode/plugins/ 또는 ~/.config/opencode/plugins/에 플러그인 파일을 배치하세요. plugin 옵션을 통해 npm에서 플러그인을 로드할 수도 있습니다.

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

자세히 알아보기.

지침

instructions 옵션을 통해 사용 중인 모델에 대한 지침을 구성할 수 있습니다.

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

지침 파일에 대한 경로와 glob 패턴의 배열을 사용합니다. 규칙에 대해 자세히 알아보기.

비활성화된 프로바이더

disabled_providers 옵션을 통해 자동으로 로드되는 프로바이더를 비활성화할 수 있습니다. 자격 증명이 있어도 특정 프로바이더가 로드되지 않도록 하려는 경우 유용합니다.

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

참고: disabled_providers는 enabled_providers보다 우선합니다.

disabled_providers 옵션은 프로바이더 ID 배열을 받습니다. 프로바이더가 비활성화되면:

  • 환경 변수가 설정되어 있어도 로드되지 않습니다.
  • /connect 명령을 통해 API 키가 구성되어 있어도 로드되지 않습니다.
  • 프로바이더의 모델이 모델 선택 목록에 나타나지 않습니다.

활성화된 프로바이더

enabled_providers 옵션을 통해 프로바이더 허용 목록을 지정할 수 있습니다. 설정하면 지정된 프로바이더만 활성화되고 다른 모든 프로바이더는 무시됩니다.

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

하나씩 비활성화하는 대신 OpenCode가 특정 프로바이더만 사용하도록 제한하려는 경우 유용합니다.

참고: disabled_providers는 enabled_providers보다 우선합니다.

프로바이더가 enabled_providers와 disabled_providers 모두에 나타나면 하위 호환성을 위해 disabled_providers가 우선합니다.

실험적

experimental 키에는 활발히 개발 중인 옵션이 포함됩니다.

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}"
      }
    }
  }
}

파일 경로는:

  • 설정 파일 디렉토리를 기준으로 상대 경로
  • 또는 / 또는 ~로 시작하는 절대 경로

다음에 유용합니다:

  • API 키와 같은 민감한 데이터를 별도 파일에 보관.
  • 설정을 어지럽히지 않고 큰 지침 파일 포함.
  • 여러 설정 파일에서 공통 설정 스니펫 공유.
소개프로바이더