참조

요약

opencode.json의 최상위 references 키는 현재 프로젝트 외부의 리소스를 마운트하고 별칭을 부여합니다. 로컬 디렉터리에는 path(상대·절대·~/ 경로), Git 리포지토리에는 repository(Git URL, host/path 또는 GitHub owner/repo 축약 표기, 선택적 branch)를 사용합니다. description을 추가하면 에이전트가 각 참조를 언제 적용해야 할지 알 수 있습니다. "hidden": true를 설정하면 TUI의 @ 자동 완성에서는 제외되지만 컨텍스트에는 계속 제공됩니다. @별칭으로 첨부하고 @별칭/으로 탐색합니다. 참조된 경로는 자동으로 외부 디렉터리 권한 경계를 넘지만, 일반 도구 권한은 그대로 적용됩니다.

참조(reference)를 통해 OpenCode는 현재 프로젝트 외부의 디렉터리에 접근할 수 있습니다. 각 참조에는 별칭이 할당되며, 이를 사용해 내용을 대화에 첨부할 수 있습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "제품 기능 관련 질문에 답할 때 사용"
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "SDK 기반 코드를 작성할 때 사용"
    }
  }
}

로컬 디렉터리

path 필드로 로컬 디렉터리를 참조합니다. 상대 경로는 프로젝트 루트를 기준으로 확인되고, 절대 경로는 그대로 사용되며, ~/로 시작하는 경로는 홈 디렉터리로 확인됩니다:

{
  "references": {
    "shared": { "path": "~/projects/shared-libs" }
  }
}

추가 옵션이 필요 없을 때는 단순 문자열이 path의 축약 표현입니다:

{
  "references": {
    "shared": "~/projects/shared-libs"
  }
}

Git 리포지토리

repository 필드로 Git 리포지토리를 참조합니다. 전체 Git URL, host/path 형식, GitHub owner/repo 축약 표기를 모두 사용할 수 있습니다. 리포지토리는 캐시에 클론되어 비동기적으로 새로 고쳐지므로 참조가 항상 최신 상태로 유지됩니다:

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

branch 필드는 브랜치나 ref를 선택합니다. 생략하면 기본 브랜치가 사용됩니다. 로컬 디렉터리와 마찬가지로, 브랜치가 필요 없을 때는 문자열 값도 축약 표현이 됩니다.

용도 설명

description을 추가하여 각 참조의 용도와 언제 참고해야 하는지 에이전트에게 알립니다. 설명이 없는 참조는 에이전트에 능동적으로 노출되지 않습니다:

{
  "references": {
    "design-system": {
      "path": "../design-tokens",
      "description": "UI 컴포넌트 또는 디자인 토큰을 구현할 때 사용"
    }
  }
}

자동 완성 항목 숨기기

"hidden": true를 설정하면 해당 참조가 TUI의 @ 자동 완성 메뉴에서 제외됩니다. 설명이 있는 숨겨진 참조는 여전히 에이전트의 컨텍스트에 포함됩니다:

{
  "references": {
    "archive": {
      "path": "../legacy-archive",
      "description": "마이그레이션 작업을 위한 과거 맥락",
      "hidden": true
    }
  }
}

참조 사용

TUI에서 @ 뒤에 별칭을 입력하면 참조의 내용을 메시지에 첨부할 수 있고, @별칭/을 입력하면 그 안의 파일을 퍼지 검색할 수 있습니다. 관련 단축키는 키바인드를 참고하세요.

참조된 디렉터리는 권한 문서에서 설명하는 외부 디렉터리 권한 경계를 자동으로 넘어가므로, 도구는 추가 승인 없이 읽을 수 있습니다. 일반 도구 수준의 권한 규칙도 계속 적용됩니다.

구성 필드

필드	로컬	Git	설명
path	✓		참조할 로컬 디렉터리
repository		✓	Git URL, host/path 또는 owner/repo
branch		✓	선택적 브랜치 또는 ref. 생략 시 기본 브랜치 사용
description	✓	✓	이 참조를 언제 사용할지에 대한 에이전트 안내
hidden	✓	✓	TUI @ 자동 완성에서 제외

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