권한
실행에 승인이 필요한 작업을 제어합니다.
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"
}
}
}규칙은 패턴 매칭으로 평가되며, 마지막으로 일치하는 규칙이 우선합니다. 일반적인 패턴은 catch-all "*" 규칙을 먼저 두고, 더 구체적인 규칙을 그 뒤에 두는 것입니다.
와일드카드
권한 패턴은 간단한 와일드카드 매칭을 사용합니다:
*는 0개 이상의 모든 문자와 일치?는 정확히 하나의 문자와 일치- 다른 모든 문자는 리터럴로 일치
홈 디렉토리 확장
패턴 시작 부분에 ~ 또는 $HOME을 사용하여 홈 디렉토리를 참조할 수 있습니다. 이는 external_directory 규칙에 특히 유용합니다.
~/projects/*->/Users/username/projects/*$HOME/projects/*->/Users/username/projects/*~->/Users/username
외부 디렉토리
external_directory를 사용하여 OpenCode가 시작된 작업 디렉토리 외부의 경로에 접근하는 도구 호출을 허용합니다. 이는 경로를 입력으로 받는 모든 도구에 적용됩니다(예: read, edit, list, 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,multiedit포함)glob— 파일 글로빙 (글로브 패턴과 일치)grep— 콘텐츠 검색 (정규식 패턴과 일치)list— 디렉토리의 파일 나열 (디렉토리 경로와 일치)bash— 셸 명령어 실행 (git status --porcelain과 같은 파싱된 명령어와 일치)task— 서브에이전트 시작 (서브에이전트 유형과 일치)skill— 스킬 로드 (스킬 이름과 일치)lsp— LSP 쿼리 실행 (현재 비세밀)todoread,todowrite— 할 일 목록 읽기/업데이트webfetch— URL 가져오기 (URL과 일치)websearch,codesearch— 웹/코드 검색 (쿼리와 일치)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"
}
}
}
}
}Markdown에서도 에이전트 권한을 설정할 수 있습니다:
---
description: Code review without edits
mode: subagent
permission:
edit: deny
bash: ask
webfetch: deny
---
Only analyze code and suggest changes.팁: 인수가 있는 명령어에는 패턴 매칭을 사용하세요.
"grep *"는grep pattern file.txt를 허용하지만,"grep"단독으로는 차단됩니다.git status와 같은 명령어는 기본 동작에서 작동하지만, 인수가 전달될 때는 명시적 권한(예:"git status *")이 필요합니다.