OpenCode 2 권한 설정: V1에서 마이그레이션하고 외부 접근 승인 복원하기

OpenCode 2로 업데이트한 뒤 외부 디렉터리 접근 승인 요청을 복원하려면 external_directory 규칙에 effect: "ask"를 명시합니다. 2026-10-31 기준 공식 마이그레이션 가이드는 V2 기본값을 allow로 설명하며, 이는 V1의 ask와 다릅니다. 권한 규칙을 V2의 순서가 있는 permissions 배열로 변환할 준비가 될 때까지 지원되는 V1 설정을 유지합니다.

이 가이드는 대화형 개발에 사용할 기본 설정과 OpenCode v2.2.0을 기준으로 한 검증 절차를 제공합니다. 예상 결과는 문서와 해당 버전 태그의 소스 코드에 근거합니다. 실제 클라이언트를 실행해서 얻은 테스트 결과는 아닙니다.

일치하는 규칙이 없으면 ask를 사용하는데, V2는 왜 외부 경로를 허용할까요?

내장 규칙도 평가에 참여하므로 사용자 규칙이 없다는 사실이 일치하는 규칙도 없다는 뜻은 아닙니다.

공식 V2 Defaults 설명에 따르면 모든 에이전트는 와일드카드 허용 규칙으로 시작합니다. 이 규칙에는 action: "*", resource: "*", effect: "allow"가 들어 있습니다. 뒤에 오는 기본 규칙은 *.env와 *.env.*를 읽기 전에 승인을 요청하고, 그다음 *.env.example 읽기를 허용합니다. 기본 제공 에이전트는 추가 제한을 적용할 수 있습니다.

따라서 일반적인 읽기, 편집, 셸 명령, 외부 디렉터리 검사에는 이미 일치하는 기본 규칙이 있습니다. 일치하지 않을 때 사용하는 ask는 평가하는 전체 규칙 집합에 일치 항목이 없을 때만 적용됩니다. 사용자 설정에 read나 edit를 생략했다고 해서 승인이 필요해지는 것은 아닙니다.

외부 디렉터리 승인과 파일 작업 승인은 별도로 검사합니다. 검사 범위에는 활성 Location과 프로젝트 작업 트리가 포함됩니다. 다만 작업 트리가 파일 시스템 루트인 경우에는 해당 작업 트리를 범위 판단에 사용하지 않습니다. 두 범위 밖에 있는 경로는 read나 edit보다 먼저 external_directory로 검사합니다. 여기서 Location은 현재 작업 위치를 뜻합니다. 따라서 외부 파일이 경계 검사를 통과해도 읽기나 편집 제한은 별도로 적용될 수 있습니다.

이 순서는 디렉터리 검사 방식이 정합니다. 배열에서 이름이 다른 액션 규칙을 어디에 배치하느냐로 결정되지 않습니다. external_directory 규칙을 read 규칙 위로 옮겨도 그 배치가 검사 순서를 만드는 것은 아닙니다.

V1 설정을 유지할 수 있으며, 어떤 이름이 바뀔까요?

유지할 수 있습니다. V2 전용 형식은 선택 사항입니다. 지원되는 V1 설정은 읽어 들일 때 내부 형식으로 정규화되므로 원본 파일을 다시 작성할 필요가 없습니다. 마이그레이션 안내는 전체 설정을 바꾸기 전에 기존 모델, 인증 정보, 에이전트, 권한, MCP 서버를 확인하도록 권장합니다.

V1은 권한 결정을 도구별로 묶습니다.

{
  "permission": {
    "bash": {
      "git push *": "ask"
    },
    "edit": "allow"
  },
  "tools": {
    "websearch": false
  }
}

문서에 나온 V2 변환 예시는 이 명시적인 설정을 순서가 있는 규칙으로 표현합니다.

{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

각 규칙에는 문자열 필드 action, resource, effect가 필요합니다. allow는 질문 없이 진행하고, deny는 작업을 차단하며, ask는 클라이언트에서 결정을 기다립니다.

이 예시는 표시된 설정만 변환합니다. 아래에서 권장하는 기본 설정과는 다릅니다. 여전히 편집을 허용하며 외부 디렉터리 승인 요청도 복원하지 않습니다.

액션 이름은 bash → shell, task → subagent, write/patch → edit로 바뀝니다. V2의 edit는 edit, write, patch 작업의 대상 경로를 제어합니다. subagent는 에이전트 ID와 대조하고, shell은 스캐너가 생성한 명령 문자열과 대조합니다. 액션 참조 문서는 doom_loop와 lsp가 현재 V2 Core 권한 액션에 포함되지 않는다고도 설명합니다.

최상위 설정, 에이전트 정의, 설정을 생성하는 스크립트를 검토합니다. 관련 없는 파일까지 같은 단어를 일괄 치환하지 않습니다. 의도적으로 형식을 변환한 뒤에는 서로 충돌하는 V1과 V2 권한 정의를 남기지 않습니다.

승인을 요구하는 V2 기본 권한 설정을 사용합니다

대화형 개발에서는 외부 접근, 셸 명령, 편집 전에 승인을 요청하도록 설정합니다. 일반적인 Git 확인 작업은 허용하고, 일치하는 push 명령과 예제 파일을 제외한 환경 설정 파일 읽기는 거부합니다.

저장소별 설정은 프로젝트 루트의 opencode.jsonc에 둡니다. 사용자 전체 설정에는 ~/.config/opencode/opencode.jsonc를 사용합니다. OpenCode는 .json 형식도 지원하며, 가능한 위치는 설정 참조 문서에서 설명합니다.

다음 배열을 기존 설정에 병합합니다. 파일 전체를 대체하지 말고 공급자 설정, 에이전트 정의, 기존 제한을 유지합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "edit", "resource": "*", "effect": "ask" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" }
  ]
}

.env.example 예외는 두 읽기 거부 규칙 뒤에 의도적으로 배치했습니다. 이 예외는 비밀 정보가 없는 예제 파일에만 사용합니다.

지정하지 않은 액션은 실제로 적용되는 기본 설정을 계속 상속합니다. 이 기본 설정이 모든 MCP 도구를 거부하거나, 가능한 모든 push 방식을 차단하거나, 호스트 파일 시스템을 격리하지는 않습니다. read 제한만으로 셸 명령이 같은 파일을 읽는 것까지 금지할 수도 없습니다.

OpenCode의 셸 관련 주의 사항은 셸 명령이 호스트 사용자 권한으로 실행된다고 설명합니다. 명령이 접근할 디렉터리를 추론하더라도 모든 경로를 찾아낸다고 보장하지는 않습니다. 승인 전에 명령을 검토하고, 파일 작업 규칙만으로 부족하다면 별도의 셸 제어를 적용합니다.

다른 클라이언트에는 Claude Code의 비밀 정보와 Git 권한 설정 가이드를 참고합니다. OpenCode 설정 문법을 그대로 사용하지 않습니다.

예외는 덮어쓸 규칙 뒤에 배치합니다

순서가 중요한 대상은 같은 액션과 리소스에 일치하는 규칙입니다. 나중에 일치하는 규칙이 앞선 결정을 대체합니다. 액션에 와일드카드를 쓰면 여러 액션 이름에 일치할 수 있습니다.

기본 설정에서는 shell: "*"가 먼저 승인을 요구합니다. 이후 git status *와 git diff * 규칙이 해당 명령을 허용합니다. git push * 규칙은 일치하는 push 명령을 거부합니다.

*로 끝나는 셸 패턴은 인수가 없는 명령에도 일치합니다. 따라서 git status *는 git status와 git status --short를 모두 포함합니다.

일치 규칙 참조 문서는 리소스 값 전체를 대상으로 와일드카드를 비교합니다. *는 /를 포함한 0개 이상의 문자에, ?는 문자 하나에 일치합니다. 경로 구분자는 슬래시로 정규화하며, Windows에서는 대소문자를 구분하지 않습니다.

여러 리소스를 다루는 작업에는 추가 판단이 필요합니다. 먼저 각 리소스에서 마지막으로 일치하는 규칙을 결정합니다. 그 결과 중 하나라도 거부라면 작업을 차단하고, 거부가 없더라도 승인이 필요한 결과가 있으면 확인을 요청합니다. 복합 셸 명령은 여러 리소스를 생성할 수 있습니다. Git 명령 하나가 허용된다고 해서 복합 명령 전체가 허용되는 것은 아닙니다.

신뢰할 수 있는 외부 디렉터리는 신중하게 추가합니다

신뢰하는 디렉터리의 경계를 넘는 접근과 파일 작업 권한을 별도로 설정합니다. 다음 선택 규칙은 기본 설정에 추가하는 항목이며, 전체 설정을 대체하지 않습니다.

[
  { "action": "external_directory", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "read", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "edit", "resource": "~/projects/reference/*", "effect": "deny" }
]

외부 접근 허용은 전체 경로를 대상으로 하는 external_directory의 ask 뒤에 둡니다. 읽기 허용은 환경 설정 파일의 거부 규칙 앞에 두어 기존 제한을 유지합니다. 편집 거부는 전체 편집에 승인을 요구하는 규칙 뒤에 둡니다.

디렉터리 규칙은 이러한 경로 액션에서 ~/처럼 홈 디렉터리를 가리키는 접두 표기를 지원합니다. 셸 리소스는 원래 명령 문자열을 유지하며, 설정을 읽을 때 이 경로 확장을 적용하지 않습니다.

편집 거부는 write와 patch 도구를 포함해 edit가 관리하는 작업을 차단합니다. 셸로 해당 디렉터리를 수정하는 작업까지 차단하지는 않습니다. 셸 제한은 별도로 유지하고, 해당 파일을 변경할 수 있는 승인 요청은 모두 검토합니다.

설정을 마이그레이션한 뒤 안전한 테스트 파일로 검증합니다

실제로 사용하는 파일을 백업하고, 변경안을 받은 다음, 승인한 설정을 별도의 테스트 프로젝트에서 검증합니다. 시작하기 전에 V2 클라이언트가 설치되어 있고 공급자와 모델 연결이 정상적으로 동작해야 합니다.

적용 전에 마이그레이션 변경안을 검토합니다

전역 설정과 프로젝트 설정을 백업합니다. .opencode/agents/의 에이전트 정의도 포함합니다. 공식 에이전트 파일 위치 안내에는 사용자 전체 정의를 두는 ~/.config/opencode/agents/도 나와 있습니다.

플러그인, 서버 API 연동, 터미널 설정은 별도로 처리합니다. 마이그레이션 가이드는 이러한 영역에 호환되지 않는 변경이 있다고 설명합니다.

OpenCode에 다음 프롬프트를 전달합니다. 먼저 변경안을 검토하고 승인 전에는 파일을 수정하지 않도록 요청하는 내용입니다.

Read the official OpenCode V1 migration and V2 permissions documentation.

Inspect my global, project, and agent permission configuration.
Do not modify any files yet.

Propose native V2 permissions rules.
Preserve unrelated settings and existing restrictions.
Map bash to shell, task to subagent, and write and patch to edit where applicable.
Identify unsupported fields and competing V1/V2 definitions.
Restore external_directory approval without weakening existing deny rules.
Use the baseline's shell and edit approval rules unless existing rules are stricter.
Put environment-file denies before the .env.example exception.
Show the complete proposed diff and explain every behavior change.
Wait for approval before applying it.

프로젝트 파일만 보지 말고 병합된 결과를 확인합니다. 에이전트별 권한은 해석이 끝난 최상위 규칙 뒤에 적용됩니다. 따라서 나중에 오는 에이전트의 허용 규칙이 일반적인 최상위 거부 규칙을 덮어쓸 수 있습니다.

조직에서 강제해야 하는 제한은 OpenCode 정책을 참고합니다. 정책은 에이전트 권한과 저장된 승인을 평가한 뒤에도 작업을 강제로 거부할 수 있습니다. 일반 권한 배열은 관리자가 강제하는 제한을 대신하지 않습니다.

변경안을 승인한 뒤 opencode reload로 설정을 다시 읽습니다. 이 명령은 CLI 참조 문서에 설명되어 있습니다. 계속 진행하기 전에 설정 경고를 확인합니다.

전체 검증 절차를 한 차례 수행합니다

아래 예상 결과의 기준은 v2.2.0과 내장 build 에이전트입니다. 표는 기본 설정이 실제로 적용되며, 충돌하는 에이전트 규칙이나 저장된 승인, 추가 정책이 없다고 가정합니다.

Bash에서 민감한 정보가 없는 테스트 파일을 만듭니다.

lab=$(mktemp -d)
mkdir -p "$lab/project" "$lab/outside"
git -C "$lab/project" init -q
printf 'ordinary fixture\n' > "$lab/project/README.md"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env.example"
printf 'outside fixture\n' > "$lab/outside/fixture.txt"
cd "$lab/project"

이 프로젝트의 opencode.jsonc에 기본 설정을 저장한 뒤 opencode를 실행합니다. 터미널 인터페이스 가이드에 따라 /agents에서 build를 선택합니다.

에이전트에 지정된 도구로 각 작업을 따로 시도하도록 요청합니다. 터미널에서 직접 실행한 명령은 에이전트 권한 검사를 대신하지 않습니다.

에이전트 작업	예상 권한 결과
read로 README.md 읽기	기본 읽기 규칙에 따라 허용합니다
read로 ../outside/fixture.txt 읽기	외부 디렉터리 승인을 요청하며, 승인 후 일반 읽기를 허용합니다
read로 .env 읽기	거부합니다
read로 .env.example 읽기	허용합니다
edit, write, patch로 README.md 수정하기	edit를 통해 승인을 요청합니다
shell로 git status, git status --short, git diff 실행하기	허용합니다
shell로 git push 실행하기	일치하는 셸 규칙에 따라 거부합니다
shell로 pwd 실행하기	승인을 요청합니다

push를 검사하기 전에 직접 git remote를 실행하고 아무 이름도 표시되지 않는지 확인합니다. 원격 저장소를 추가하지 않습니다. 원격 저장소가 없다는 Git 오류는 권한 규칙이 명령을 거부했다는 증거가 아닙니다.

승인 테스트에서는 Allow always 대신 Allow once를 선택해 한 번만 허용합니다. 저장된 승인은 프로젝트에 유지되며 이후 승인 요청이 나타나지 않게 할 수 있습니다. 다만 설정된 거부 규칙을 덮어쓰지는 않습니다. 자동 승인은 비활성화한 상태로 유지합니다.

실제 도구 요청, 권한 결정, 파일 변경을 확인합니다. 모델이 push하지 않거나 파일을 읽지 않겠다고 답하는 것만으로는 권한 엔진이 작업을 차단했다고 볼 수 없습니다.

규칙을 완화하기 전에 예상과 다른 원인을 확인합니다

먼저 불러온 설정과 선택된 에이전트를 확인합니다. CLI 디버깅 명령에는 opencode debug config와 opencode debug agents가 있습니다. 출력은 로컬에서 확인하고, 인증 정보나 민감한 설정은 공유하지 않습니다.

외부 접근 승인 요청이 없다면 대상이 Location과 프로젝트 작업 트리 모두의 외부에 있는지 확인합니다. 다음으로 저장된 승인과 자동 승인을 확인합니다. 파일 읽기 결과가 예상과 다르다면 에이전트가 shell이 아닌 read를 사용했는지 확인합니다.

Git 명령이 차단되면 스캐너가 만든 리소스와 추가 하위 명령을 확인합니다. .env.example 읽기가 거부된다면 나중의 *.env.* 규칙이나 추가 정책이 의도한 예외를 덮어쓰는지 살펴봅니다.

기존 공급자, 모델 ID, 인증, Base URL도 별도로 확인합니다. BetterToken의 OpenCode 연동 안내는 https://www.bettertoken.ai/v1을 사용하는 사용자 지정 OpenAI 호환 연결을 설명합니다. 이 연결은 OpenCode의 권한 설정을 대신하지 않습니다.

마이그레이션 과정에서 도구 선택도 검토한다면 Cursor와 OpenCode의 설정 및 접근 방식 비교를 참고합니다. 다른 터미널 작업 방식을 평가할 때는 Git 프로젝트의 Aider 또는 OpenCode에 같은 테스트 작업을 적용합니다.

v2.2.0의 파일 시스템 수정은 무엇을 바꿀까요?

이 수정은 외부 디렉터리 검사에서 프로젝트 파일을 찾는 방식을 바꿉니다. 승인 규칙을 명시하라는 권장 사항은 바뀌지 않습니다.

v2.2.0 릴리스 노트는 프로젝트 파일 시스템을 사용하도록 바꾼 내용을 포함합니다. PR #59089는 원격 프로젝트나 메모리 내 프로젝트에서도 이전에는 호스트 컴퓨터의 디스크를 조회했다고 설명합니다. 작성자는 일반적인 로컬 프로젝트는 영향을 받지 않는다고 밝힙니다.

원격 프로젝트에서는 해당 프로젝트의 실제 파일 시스템을 대상으로 외부 디렉터리 검사를 다시 수행합니다. 2026-10-31에 문서화된 V2 기본 동작에서는 이러한 경계 제한이 필요할 때 여전히 external_directory에 ask 또는 deny를 명시해야 합니다.