한국어
문서
설정

설정

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: 설정 파일은 교체되는 것이 아니라 함께 병합됩니다.

설정 파일은 교체되는 것이 아니라 함께 병합됩니다. 다음 설정 위치들의 설정이 결합됩니다. 나중 설정은 충돌하는 키에 대해서만 이전 설정을 재정의합니다. 모든 설정의 충돌하지 않는 항목은 보존됩니다.

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

우선순위 순서

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

  1. 원격 설정(.well-known/opencode에서) - 조직 기본값
  2. 전역 설정(~/.config/opencode/opencode.json) - 사용자 환경설정
  3. 커스텀 설정(OPENCODE_CONFIG 환경 변수) - 커스텀 재정의
  4. 프로젝트 설정(프로젝트 내 opencode.json) - 프로젝트별 설정
  5. .opencode 디렉터리 - 에이전트, 명령어, 플러그인
  6. 인라인 설정(OPENCODE_CONFIG_CONTENT 환경 변수) - 런타임 재정의
  7. 관리형 설정 파일(macOS에서 /Library/Application Support/opencode/) - 관리자 제어
  8. macOS 관리형 환경설정(MDM을 통한 .mobileconfig) - 최우선순위, 사용자가 재정의할 수 없음

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

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

원격

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

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

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

Remote config from .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에 배치하세요. 프로바이더, 모델, 권한 같은 사용자 전체의 서버/런타임 환경설정에는 전역 설정을 사용하세요.

TUI 전용 설정에는 ~/.config/opencode/tui.json을 사용하세요.

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

프로젝트별

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

프로젝트별 TUI 설정의 경우, 그 옆에 tui.json을 추가하세요.

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

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.json 또는 opencode.jsonc 파일을 배치하세요:

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

이 디렉터리는 쓰기에 관리자/루트 권한이 필요하므로, 사용자가 수정할 수 없습니다.

macOS 관리형 환경설정

macOS에서 OpenCode는 ai.opencode.managed 환경설정 도메인에서 관리형 환경설정을 읽습니다. MDM(Jamf, Kandji, FleetDM)을 통해 .mobileconfig를 배포하면 설정이 자동으로 강제됩니다.

OpenCode는 다음 경로를 확인합니다:

  1. /Library/Managed Preferences/<user>/ai.opencode.managed.plist
  2. /Library/Managed Preferences/ai.opencode.managed.plist

plist 키는 opencode.json 필드에 직접 매핑됩니다. MDM 메타데이터 키(PayloadUUID, PayloadType 등)는 자동으로 제거됩니다.

.mobileconfig 생성

ai.opencode.managed PayloadType을 사용하세요. OpenCode 설정 키는 페이로드 딕셔너리에 직접 들어갑니다:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>ai.opencode.managed</string>
      <key>PayloadIdentifier</key>
      <string>com.example.opencode.config</string>
      <key>PayloadUUID</key>
      <string>GENERATE-YOUR-OWN-UUID</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>share</key>
      <string>disabled</string>
      <key>server</key>
      <dict>
        <key>hostname</key>
        <string>127.0.0.1</string>
      </dict>
      <key>permission</key>
      <dict>
        <key>*</key>
        <string>ask</string>
        <key>bash</key>
        <dict>
          <key>*</key>
          <string>ask</string>
          <key>rm -rf *</key>
          <string>deny</string>
        </dict>
      </dict>
    </dict>
  </array>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadIdentifier</key>
  <string>com.example.opencode</string>
  <key>PayloadUUID</key>
  <string>GENERATE-YOUR-OWN-UUID</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
</dict>
</plist>

uuidgen으로 고유한 UUID를 생성하세요. 조직의 요구사항에 맞게 설정을 커스터마이즈하세요.

MDM을 통한 배포

  • Jamf Pro: Computers > Configuration Profiles > Upload > 대상 기기 또는 스마트 그룹으로 범위 지정
  • FleetDM: .mobileconfig를 gitops 저장소의 mdm.macos_settings.custom_settings 아래에 추가하고 fleetctl apply 실행

기기에서 검증

테스트를 위해 .mobileconfig를 더블 클릭하여 로컬에 설치하고(System Settings > Privacy & Security > Profiles에 표시됨), 다음을 실행하세요:

opencode debug config

모든 관리형 환경설정 키가 해석된 설정에 표시되며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다.

스키마

서버/런타임 설정 스키마는 opencode.ai/config.json (opens in a new tab)에 정의되어 있습니다.

TUI 설정은 opencode.ai/tui.json (opens in a new tab)을 사용합니다.

에디터가 스키마를 기반으로 검증하고 자동완성할 수 있어야 합니다.

TUI

TUI 전용 설정에는 전용 tui.json(또는 tui.jsonc) 파일을 사용하세요.

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

OPENCODE_TUI_CONFIG를 사용하여 커스텀 TUI 설정 파일을 가리킵니다.

attention.enabled를 설정하면 TUI 데스크톱 알림과 소리를 켭니다. TUI attention을 참조하세요.

opencode.json의 레거시 theme, keybinds, 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에 허용할 추가 오리진. 값은 전체 오리진(scheme + host + 선택적 port)이어야 합니다. 예: https://app.example.com.

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

셸

shell 옵션을 사용하여 대화형 터미널에 사용되는 셸을 설정할 수 있습니다. 호환 셸은 에이전트 도구 호출에도 사용됩니다.

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

지정하지 않으면, OpenCode는 운영체제에 따라 적절한 기본값을 자동으로 검색하여 사용합니다(예: Windows에서는 pwsh 또는 cmd.exe, macOS/Linux에서는 /bin/zsh 또는 /bin/bash). 절대 경로 또는 짧은 이름을 제공할 수 있습니다.

도구

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, chunkTimeout, setCacheKey가 포함될 수 있습니다:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}
  • timeout - 요청 타임아웃(밀리초, 기본값: 300000). 비활성화하려면 false로 설정.
  • chunkTimeout - 스트리밍 응답 청크 간 타임아웃(밀리초). 시간 내에 청크가 도착하지 않으면 요청이 중단됩니다.
  • setCacheKey - 지정된 프로바이더에 대해 항상 캐시 키가 설정되도록 보장합니다.

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

이미지 첨부

OpenCode는 이미지 첨부를 모델로 보내기 전에 정규화합니다. 기본적으로 이미지가 2000x2000 픽셀 또는 5242880 base64 바이트를 초과하면 크기가 조정됩니다.

attachment.image 옵션으로 이미지 첨부 제한을 설정합니다:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880
    }
  }
}
  • auto_resize - 프로바이더 요청 전에 설정된 제한을 초과하는 이미지의 크기를 조정합니다. 대신 크기가 큰 이미지를 거부하려면 false로 설정.
  • max_width - 크기 조정 또는 거부 전 최대 이미지 너비(픽셀).
  • max_height - 크기 조정 또는 거부 전 최대 이미지 높이(픽셀).
  • max_base64_bytes - 최대 인코딩된 이미지 페이로드 크기. 이는 원본 파일 크기가 아니라 base64 페이로드 크기입니다.

크기를 조정한 후에도 이미지가 맞지 않으면, OpenCode는 크기가 큰 도구 결과 이미지를 생략하거나 크기가 큰 사용자 제공 이미지를 이미지 크기 오류로 실패시킵니다.

프로바이더별 옵션

일부 프로바이더는 일반적인 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가 우선합니다.

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

Amazon Bedrock 설정에 대해 자세히 알아보기.

테마

tui.json에서 UI 테마를 설정합니다.

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

여기서 자세히 알아보기.

에이전트

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": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

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

기본 에이전트

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

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

기본 에이전트는 (서브에이전트가 아닌) 기본(primary) 에이전트여야 합니다. "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/에서 마크다운 파일을 사용하여 명령어를 정의할 수도 있습니다. 여기서 자세히 알아보기.

키바인드

tui.json에서 keybinds로 TUI 키보드 단축키를 커스터마이즈합니다.

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

keybinds는 내장 기본값과 병합되므로, 변경하고 싶은 단축키만 설정하면 됩니다.

여기서 자세히 알아보기.

스냅샷

OpenCode는 스냅샷을 사용하여 에이전트 작업 중 파일 변경을 추적하므로, 세션 내에서 변경을 취소하고 되돌릴 수 있습니다. 스냅샷은 기본적으로 활성화되어 있습니다.

대규모 저장소나 서브모듈이 많은 프로젝트의 경우, 스냅샷 시스템이 내부 git 저장소를 사용하여 모든 변경을 추적하므로 느린 인덱싱과 상당한 디스크 사용량을 유발할 수 있습니다. snapshot 옵션을 사용하여 스냅샷을 비활성화할 수 있습니다.

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

스냅샷을 비활성화하면 에이전트가 만든 변경을 UI를 통해 롤백할 수 없게 됩니다.

자동 업데이트

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

내장 포매터를 활성화 상태로 유지하면서 재정의나 커스텀 포매터를 설정하려면 객체를 사용하세요.

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

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

LSP 서버

lsp 옵션을 통해 LSP 서버를 활성화하고 설정할 수 있습니다. LSP를 비활성화 상태로 유지하려면 생략하세요.

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

내장 서버를 활성화 상태로 유지하면서 재정의나 커스텀 LSP 서버를 설정하려면 객체를 사용하세요.

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

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

권한

기본적으로 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,
    "reserved": 10000
  }
}
  • auto - 컨텍스트가 가득 찼을 때 세션을 자동으로 압축(기본값: true).
  • prune - 토큰을 절약하기 위해 오래된 도구 출력을 제거(기본값: true).
  • reserved - 압축을 위한 토큰 버퍼. 압축 중 오버플로를 방지하기에 충분한 윈도를 남깁니다.

워처

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

Note: disabled_providers는 enabled_providers보다 우선합니다.

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

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

활성화된 프로바이더

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

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

OpenCode가 특정 프로바이더만 사용하도록 제한하고 싶을 때, 하나씩 비활성화하는 대신 유용합니다.

Note: disabled_providers는 enabled_providers보다 우선합니다.

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

실험적

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

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

Caution: 실험적 옵션은 안정적이지 않습니다. 사전 통보 없이 변경되거나 제거될 수 있습니다.

변수

설정 파일에서 변수 치환을 사용하여 환경 변수와 파일 내용을 참조할 수 있습니다.

환경 변수

{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 키 같은 민감한 데이터를 별도 파일에 보관.
  • 설정을 어지럽히지 않고 대규모 지침 파일 포함.
  • 여러 설정 파일에서 공통 설정 스니펫 공유.
소개프로바이더