권한

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

OpenCode는 permission 설정을 사용하여 특정 작업을 자동으로 실행할지, 프롬프트할지, 차단할지 결정합니다.

v1.1.1부터 레거시 tools 불리언 설정은 더 이상 사용되지 않으며 permission에 병합되었습니다. 기존 tools 설정은 하위 호환성을 위해 여전히 지원됩니다.

액션

각 권한 규칙은 다음 중 하나로 해석됩니다:

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

자동 모드

명시적으로 거부되지 않은 권한 요청을 자동으로 승인하려면 --auto로 OpenCode를 시작하세요.

opencode --auto

opencode run에서도 자동 모드를 사용할 수 있습니다.

opencode run --auto "Refactor this module"

명시적인 "deny" 규칙은 여전히 적용됩니다. 자동 모드는 원래라면 승인을 요청했을 요청만 변경합니다.

TUI에서는 명령 팔레트를 열고 자동 승인 권한 활성화 또는 자동 승인 권한 비활성화를 선택하여 모드를 변경할 수 있습니다. 자동 모드가 활성화되면, 프롬프트는 현재 에이전트 옆에 흐릿한 auto 표시를 보여줍니다.

설정

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

opencode.json

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

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

opencode.json

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

세밀한 규칙 (객체 구문)

대부분의 권한에서는 도구 입력에 따라 서로 다른 액션을 적용하도록 객체를 사용할 수 있습니다.

opencode.json

{
  "$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/ 아래의 모든 것에 대한 접근을 허용합니다:

opencode.json

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

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

opencode.json

{
  "$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 파일은 기본적으로 거부됩니다:

opencode.json

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

"Ask"가 하는 일

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

once — 이 요청만 승인
always — 제안된 패턴과 매칭되는 향후 요청 승인(현재 OpenCode 세션의 나머지 동안)
reject — 요청 거부

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

에이전트

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

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

opencode.json

{
  "$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에서도 에이전트 권한을 설정할 수 있습니다:

~/.config/opencode/agents/review.md

---
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 *")이 필요합니다.

포매터 정책