컨텐츠로 건너뛰기
쇼케이스 생태계 소스 코드 문서

권한

권한

OpenCode는 permission 구성을 사용하여 주어진 작업이 자동으로 실행, 메시지 표시 또는 차단되어야 하는지를 결정합니다.

v1.1.1부터 레거시 tools 부울 구성은 더 이상 사용되지 않으며 permission로 병합되었습니다. 이전 tools 구성은 하위 호환성을 위해 여전히 지원됩니다.

작업

각 권한 규칙은 다음 중 하나로 확인됩니다:

  • "allow" — 승인 없이 실행
  • "ask" — 승인 요청
  • "deny" — 작업 차단

구성

*로 전역으로 권한을 설정하고 특정 도구를 재정의할 수 있습니다.

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

모든 권한을 한 번에 설정할 수도 있습니다:

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

세분화된 규칙 (객체 구문)

대부분의 권한에 대해 도구 입력을 기반으로 다른 동작을 적용하는 객체를 사용할 수 있습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

규칙은 패턴 일치로 평가되며 마지막으로 일치하는 규칙이 적용됩니다. 일반적인 패턴은 포괄적인 "*" 규칙을 먼저 넣고 그 뒤에 더 구체적인 규칙을 넣는 것입니다.

와일드카드

권한 패턴은 간단한 와일드카드 일치를 사용합니다:

  • *는 0개 이상의 임의 문자 일치
  • ?는 정확히 한 문자 일치
  • 다른 모든 문자는 리터럴로 일치

홈 디렉토리 확장

패턴 시작 부분에 ~ 또는 $HOME을 사용하여 홈 디렉토리를 참조할 수 있습니다. 이는 external_directory 규칙에 특히 유용합니다.

  • ~/projects/* -> /Users/username/projects/*
  • $HOME/projects/* -> /Users/username/projects/*
  • ~ -> /Users/username

외부 디렉토리

external_directory를 사용하여 OpenCode가 시작된 작업 디렉토리 외부의 경로에 닿는 도구 호출을 허용합니다. 이는 경로를 입력으로 받는 모든 도구에 적용됩니다 (예: read, edit, glob, grep 및 많은 bash 명령).

홈 확장(~/...처럼)은 패턴을 작성하는 방법에만 영향을 줍니다. 이는 외부 경로를 현재 작업 공간의 일부로 만들지 않으므로 작업 디렉토리 외부의 경로는 여전히 external_directory를 통해 허용되어야 합니다.

예를 들어, 이것은 ~/projects/personal/ 아래의 모든 것에 대한 액세스를 허용합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

여기서 허용된 디렉토리는 현재 작업 공간과 동일한 기본값을 상속합니다. read가 기본값이 "allow"이므로 external_directory 아래 항목에 대한 읽기도 명시적 규칙으로 재정의하지 않는 한 허용됩니다. 읽기를 유지하면서 편집을 차단하는 등 특정 도구를 이러한 경로에서 제한해야 할 때 명시적 규칙을 추가합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    },
    "edit": {
      "~/projects/personal/**": "deny"
    }
  }
}

목록을 신뢰할 수 있는 경로에 집중시키고 다른 도구(예: bash)에 대해 필요에 따라 추가 허용 또는 거부 규칙을 계층화합니다.

사용 가능한 권한

OpenCode 권한은 도구 이름으로 키가 지정되며 몇 가지 안전 가드도 있습니다:

  • read — 파일 읽기 (파일 경로 일치)
  • edit — 모든 파일 수정 (edit, write, patch 포함)
  • glob — 파일 globbing (glob 패턴 일치)
  • grep — 콘텐츠 검색 (정규식 패턴 일치)
  • bash — 셸 명령 실행 (파싱된 명령 일치, 예: git status --porcelain)
  • task — 서브 에이전트 실행 (서브 에이전트 타입 일치)
  • skill — skill 로드 (skill 이름 일치)
  • lsp — LSP 쿼리 실행 (현재 비세분화)
  • question — 실행 중 사용자 질문
  • webfetch — URL 가져오기 (URL 일치)
  • websearch — 웹 검색 (쿼리 일치)
  • external_directory — 도구가 프로젝트 작업 디렉토리 외부의 경로에 닿을 때 트리거
  • doom_loop — 동일한 입력으로 동일한 도구 호출이 3번 반복될 때 트리거

기본값

아무것도 지정하지 않으면 OpenCode는 관대한 기본값에서 시작합니다:

  • 대부분의 권한은 "allow"가 기본값입니다.
  • doom_loop 및 external_directory는 "ask"가 기본값입니다.
  • read는 "allow"이지만 .env 파일은 기본적으로 거부됩니다:
{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

“Ask”의 동작

OpenCode가 승인을 요청하면 UI는 세 가지 결과를 제공합니다:

  • once — 이 요청만 승인
  • always — 추천된 패턴과 일치하는 향후 요청을 승인 (현재 OpenCode 세션의 나머지 부분)
  • reject — 요청 거부

always가 승인할 패턴 집합은 도구에서 제공됩니다 (예: bash 승인은 일반적으로 git status* 같은 안전한 명령 접두사를 허용 목록에 추가합니다).

에이전트

에이전트별로 권한을 재정의할 수 있습니다. 에이전트 권한은 전역 구성과 병합되며 에이전트 규칙이 우선합니다. 에이전트 권한에 대해 자세히 알아보기.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny",
      "grep *": "allow"
    }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
          "git commit *": "ask",
          "git push *": "deny",
          "grep *": "allow"
        }
      }
    }
  }
}

마크다운에서도 에이전트 권한을 구성할 수 있습니다:

---
description: 편집 없이 코드 검토
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---

코드만 분석하고 변경 사항을 제안합니다.