권한

어떤 작업이 실행 승인을 필요로 하는지 제어하세요.

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)에 필요한 추가 allow 또는 deny 규칙을 계층화하세요.

사용 가능한 권한

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

• read — 파일 읽기(파일 경로와 매칭)
• edit — 모든 파일 수정(edit, write, patch 포함)
• glob — 파일 globbing(glob 패턴과 매칭)
• grep — 내용 검색(정규식 패턴과 매칭)
• bash — 셸 명령 실행(git status --porcelain 같은 파싱된 명령과 매칭)
• task — 서브에이전트 실행(서브에이전트 유형과 매칭)
• 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* 같은 안전한 명령 접두사를 허용 목록에 추가합니다).

에이전트

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

Note: 더 자세한 패턴 매칭 예시는 위의 세밀한 규칙(객체 구문) 섹션을 참조하세요.

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

Markdown에서도 에이전트 권한을 설정할 수 있습니다:

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---
 
Only analyze code and suggest changes.

Tip: 인수가 있는 명령에는 패턴 매칭을 사용하세요. "grep *"는 grep pattern file.txt를 허용하지만, "grep"만으로는 이를 차단합니다. git status 같은 명령은 기본 동작에서는 작동하지만, 인수가 전달될 때는 명시적 권한(예: "git status *")이 필요합니다.