Ch4. 권한 정책

allow·ask·deny 세 권한 레벨, Bash 명령 glob 패턴 매칭 순서, task 서브에이전트 권한과 에이전트별 오버라이드로 안전한 정책을 설계하는 방법입니다.

핵심 요약

권한은 allow(즉시 실행)·ask(승인 요청)·deny(완전 차단) 세 레벨로, edit·bash·webfetch에 적용합니다.
기본값을 ask로 두고 작업 범위가 명확한 에이전트에만 허용을 확대하는 최소 권한 원칙이 안전합니다.
Bash 명령은 glob 패턴으로 선택 제어하며 위에서 아래로 먼저 매칭된 규칙이 적용되므로 구체적 규칙을 위에 배치합니다.
task 권한으로 서브에이전트를 만들고 실행하는 동작을 제어하고, 에이전트별 permission 블록으로 독립 정책을 덮어씁니다.
위험 명령(rm·sudo)을 먼저 deny, 부수효과 없는 읽기 명령을 allow, 나머지는 ask로 두는 3단계 설계를 권장합니다.

권한 설정은 OpenCode 운영 안정성을 좌우합니다. 기본값은 ask로 두고, 작업 범위가 명확한 에이전트에만 허용을 확대하는 방식이 안전합니다.

권한 레벨

레벨	동작
`allow`	승인 없이 즉시 실행
`ask`	실행 전 사용자 승인 요청
`deny`	도구 접근 완전 차단

적용 대상: edit, bash, webfetch

기본 권한 설정

{
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "webfetch": "allow"
  }
}

Bash 명령 Glob 패턴

특정 명령만 골라 허용하거나 차단합니다. 위에서 아래로 훑어 내려가다 처음 걸리는 규칙이 적용됩니다.

{
  "permission": {
    "bash": {
      "grep *": "allow",
      "git status": "allow",
      "git diff *": "allow",
      "git push *": "ask",
      "git *": "ask",
      "rm *": "deny",
      "sudo *": "deny",
      "*": "deny"
    }
  }
}

패턴 매칭 순서

git push origin main은 "git push *": "ask" 규칙에 먼저 매칭되므로 승인 요청이 뜹니다. 더 구체적인 규칙을 위에 배치하세요.

서브에이전트 태스크 권한

서브에이전트를 만들고 실행하는 동작을 제어합니다.

{
  "permission": {
    "task": {
      "*": "deny",
      "reviewer-*": "allow",
      "explore": "allow"
    }
  }
}

에이전트별 권한 오버라이드

커스텀 에이전트마다 독립된 권한 정책을 둘 수 있습니다.

{
  "agent": {
    "deploy": {
      "description": "배포 에이전트",
      "permission": {
        "bash": {
          "deploy.sh": "allow",
          "*": "deny"
        },
        "edit": "deny"
      }
    }
  }
}

실전 권한 정책 설계

1단계: 위험 명령 차단

rm -rf, sudo, docker rm 등 위험한 명령을 먼저 deny로 차단합니다.

2단계: 안전한 읽기 허용

grep, cat, git status, git log 등 부수효과가 없는 명령을 allow로 설정합니다.

3단계: 나머지는 ask

나머지 명령은 기본 ask로 유지하여 실행 전 확인합니다.

고급 팁

바로 차단할 규칙부터 정의: 위험한 명령을 먼저 deny
외부 디렉토리 제한: 프로젝트 외부 접근은 external_directory로 제한
무한 루프 방지: doom_loop 제약을 기본값으로 유지
최소 권한 원칙: 에이전트별로 필요한 최소 권한만 부여

참고 문서

권한 설정: https://opencode.ai/docs/permissions
에이전트와 권한: https://opencode.ai/docs/agents