본문으로 건너뛰기
V1 문서
로컬 디렉터리

참조

참조를 사용하면 OpenCode가 현재 프로젝트 외부의 디렉터리에 접근할 수 있습니다. 작업 중에 문서, 공유 라이브러리, 예제 또는 다른 저장소를 사용할 수 있게 하려면 참조를 활용하세요.

참조는 opencode.json 또는 opencode.jsonc에서 alias별로 설정합니다.

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and documentation conventions",
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "Use for JavaScript SDK implementation details",
    },
  },
}

로컬 디렉터리를 참조하려면 path를 사용하세요.

opencode.jsonc
{
  "references": {
    "docs": {
      "path": "../docs",
    },
  },
}

경로는 다음 형식을 사용할 수 있습니다.

  • 참조를 정의한 config 파일 기준 상대 경로
  • 절대 경로(예: /home/user/docs)
  • 홈 디렉터리 기준 상대 경로(예: ~/docs)

문자열 축약형도 사용할 수 있습니다.

opencode.jsonc
{
  "references": {
    "docs": "../docs",
  },
}

Git 저장소를 참조하려면 repository를 사용하세요. OpenCode는 저장소를 로컬 저장소 캐시에 구성하고, 체크아웃된 소스를 참조 디렉터리로 사용할 수 있게 합니다.

opencode.jsonc
{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}

repository는 Git URL, host/path 참조, GitHub owner/repo 축약형을 지원합니다. 선택 사항인 branch 필드로 branch 또는 ref를 선택합니다. branch가 없으면 OpenCode는 저장소의 기본 branch를 사용합니다.

branch, 설명 또는 기타 옵션이 필요 없으면 문자열 축약형을 사용할 수 있습니다.

opencode.jsonc
{
  "references": {
    "effect": "Effect-TS/effect",
  },
}

에이전트가 언제 참조를 사용해야 하는지 설명하려면 description을 추가하세요.

opencode.jsonc
{
  "references": {
    "design-system": {
      "path": "../design-system",
      "description": "Use when implementing UI components or design tokens",
    },
  },
}

OpenCode는 설명이 있는 참조를 에이전트 컨텍스트에 포함합니다. 설명은 짧게 작성하되, 내용이 비슷한 참조를 구분할 수 있을 만큼 구체적이어야 합니다. 설명이 없는 참조는 자동완성과 직접 사용으로 계속 사용할 수 있지만 에이전트에게 안내되지는 않습니다.


TUI의 @ 자동완성에서 참조를 제외하려면 hidden을 true로 설정하세요.

opencode.jsonc
{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true,
    },
  },
}

hidden은 자동완성에만 영향을 줍니다. 설명이 있는 숨겨진 참조는 계속 에이전트 컨텍스트에 포함됩니다.


설정한 참조는 TUI의 @ 자동완성에 표시됩니다. @alias를 입력하면 참조 루트를 첨부하고, @alias/를 입력하면 그 안의 파일을 검색합니다.

Compare this implementation with @sdk/src/client.ts

설명이 있는 설정된 참조의 경우 에이전트는 확인된 경로와 설명을 시스템 컨텍스트로도 받습니다. 따라서 직접 첨부하지 않아도 관련이 있을 때 에이전트가 참조를 살펴볼 수 있습니다.

OpenCode는 외부 디렉터리 권한 경계에서 참조 디렉터리를 자동으로 허용합니다. 일반 도구 권한은 그대로 적용됩니다. 예를 들어, 파일을 편집할 수 없는 에이전트는 디렉터리가 참조로 설정되어 있어도 편집 권한을 얻지 못합니다.


필드로컬Git설명
path예아니요로컬 참조 디렉터리
repository아니요예Git URL, host/path 또는 GitHub owner/repo 값
branch아니요예선택 사항인 Git branch 또는 ref
description예예참조를 언제 사용할지 설명하는 안내
hidden예예TUI @ 자동완성에서 참조 숨기기

참조 alias는 비워 둘 수 없으며 /, 공백, 백틱, 쉼표를 포함할 수 없습니다.