권한
헬피코드는 영향이 큰 작업을 하기 전에 사용자에게 묻습니다. 수락 모드, 권한 카드, "항상 허용"의 범위, 항상 확인하는 보호 파일을 설명합니다.
수락 모드
입력창 아래 칩에서 대화별로 수락 모드를 고릅니다. 새 대화는 마지막으로 쓴 모드로 시작하며, 첫 메시지부터 그 모드로 판단됩니다. 모드를 저장하지 못하면 수동 수락으로 돌아갑니다.
| 모드 | 설명 |
|---|---|
| 수동 수락 (기본) | 변경 전 항상 확인합니다. 행동하는 모든 작업(파일 편집, 읽기 전용이 아닌 명령, 웹, MCP·플러그인 도구)은 묻고, 조회성 작업(glob, grep, list, lsp, 일반 파일 읽기)은 묻지 않고 실행합니다. |
| 자동 수락 | 변경사항을 자동 반영합니다. 안전한 작업은 묻지 않고, 애매한 작업은 AI 판정(분류기) 이 허용·차단을 결정합니다. |
수동 수락에서 묻지 않는 것
- 파일 읽기·검색(
read,glob,grep,list,lsp). 단,.env,.env.*같은 환경 변수 파일 읽기는 묻습니다(.env.example은 묻지 않음). - 읽기 전용으로 분류된 셸 명령(
ls,cat등)은 규칙을 확인하기 전에 통과합니다. - 결과물 표시(
present_files)와 헬피비전 문서 OCR(document_vision). - 스킬 로드(
skill). 단, 내부용customize-opencode는 거부됩니다. - 첨부 폴더 읽기. 업로드한 파일은 권한 카드 없이 읽습니다.
자동 수락의 동작 방식
자동 수락은 2단계로 판단합니다.
- 1단계(규칙): 규칙, 셸 분류기, 보호 경로, 편집 검사로 확실한 것을 결정합니다.
- 프로젝트 안의 파일 편집과 환경 변수 파일 읽기는 허용합니다.
- 프로젝트 밖 읽기도 허용합니다.
- 2단계(AI 판정): 1단계가 "묻는다"로 분류한 호출을 AI 판정이 허용 또는 차단합니다. 판정은 최근 결정 기록(세션 단위, 최대 100개)을 참고합니다.
- 차단된 호출은 사용자에게 묻지 않고 막히며, AI는 막혔다는 사실을 전달받아 다른 방법을 찾습니다. 같은 호출을 쪼개서 다시 시도해도 기록에 남 아 계속 차단됩니다.
- 판정이 실패하거나, 시간이 초과되거나, 결과가 불분명하면 사용자에게 묻습니다.
자동 수락에서도 항상 사용자에게 묻는 것 (AI 판정이 대신하지 않습니다)
- 프로젝트나 루트 삭제, 링크를 따라 밖으로 나가는 쓰기, Windows 네트워크 경로(
\\host\share), 헬피코드 자체 폴더 접근 - 사용자 규칙이 "묻기"로 지정한 것
- 사용자에게만 답할 수 있는 질문: 반복 호출(
doom_loop), 계획 모드 전환(plan_enter/plan_exit),question
자동 수락 진입 시 비활성화되는 허용 규칙: 모든 도구를 허용하는 규칙(*), 서브에이전트 호출 허용(task), 임의 코드를 실행하는 명령 허용(인터프리터, 셸, 스크립트 러너, curl/wget/ssh 같은 다운로드·원격 도구, npm run, docker run 등)은 자동 수락에서는 적용되지 않습니다. 범위가 좁은 규칙(예: bash git status, MCP 도구)은 유지됩니다.
권한 패널
권한이 필요한 작업이 생기면 입력창을 가리는 권한 패널이 나타납니다. 아래 rail(프로젝트 칩, 수락 모드)은 그대로 보입니다. 요청이 여러 개면 요청 시각 순으로 첫 번째 하나만 표시하고, 응답하면 다음이 나타납니다. 서브에이전트가 낸 요청도 같은 패널로 올라옵니다.
권한 유형
| 유형 | 제목 | 대상 |
|---|---|---|
edit | 파일편집 | 파일 편집·생성·이동(경로 목록 표시). write, apply_patch도 여기에 속합니다. |
bash | 시스템 명령 실행 | 셸 명령(명령이 보라색으로 표시) |
guard | 주의가 필요한 명령 실행 | 되돌릴 수 없는 변경 가능성이 있는 명령, 보호 파일 수정 |
| 복합 | 여러 권한이 필요한 명령 실행 | 한 명령에 여러 권한이 필요한 경우. 항목별 칸에 "항상 허용"으로 기억되는 범위 또는 "이번만 허용"이 표시됩니다. |
external_directory | 외부 경로 접근 | 프로젝트 밖 경로. 쓰기뿐 아니라 read·glob·grep이 밖을 볼 때도 포함됩니다. |
network | 외부 네트워크 접근 | 접속 대상 호스트, 또는 패키지 설치(설치 도구) |
read | 민감한 파일 읽기 | 환경 변수·비밀 정보가 있을 수 있는 파일 |
| 기타 | 권한 요청 | webfetch, MCP 도구, 서브에이전트 호출 등 {permission} 작업 |
응답 옵션
| 선택 | 의미 |
|---|---|
| 거부 | 이 작업을 막습니다. |
| 이번만 허용 | 지금 요청만 허용합니다. |
| 항상 허용 | 같은 범위의 비슷한 요청을 앞으로 허용합니다. |
- 기본 선택은 파일 편집·외부 경로가 항상, 나머지가 이번만입니다. 한 카드에 여러 항목이 있고 하나라도 "이번만"이 기본이면 전체 기본이 "이번만"입니다.
- "항상 허용" 설명에는 허용 범위가 표시됩니다. 예: "이 프로젝트에서
python3 …실행 허용", "{호스트}접속 허용", "npm설치 허용", "프로젝트 안에서rm허용". - 다음은 "항상 허용"이 제공되지 않습니다(거부·이번만 허용만 표시): 프로젝트 밖으로 향하는
rm, 홈·루트·상위 폴더 접근, 덮어쓰기·인라인 코드·프로젝트 밖 실행, 와일드카드 호스트 접속,doom_loop. - 응답 중에는 버튼이 비활성화됩니다. 앱을 새로고침하거나 대화로 돌아와도 대기 중인 요청은 다시 표시됩니다.
"항상 허용"은 얼마나 유지되나요
- 파일 편집의 "항상 허용"은 해당 대화(세션) 안에서만 유효합니다. 서브에이전트도 같은 범위를 공유합니다.
- 그 외의 "항상 허용"은 프로젝트 단위로 저장됩니다(엔진 데이터 폴더의
permission/*.jsonl, 프로젝트 경로 해시로 구분, git worktree는 메인 저장소와 같은 승인을 공유).
권한 패널의 문구는 "(앱을 닫을 때까지)"로 안내하지만, 엔진 코드상 편집 외 승인은 프로젝트 단위로 저장되어 앱을 다시 켠 뒤에도 유지됩니다.
항상 확인하는 보호 파일
에이전트 구성이나 이후 명령을 실행하는 파일은 수락 모드와 상관없이 수정 전에 확인(guard)합니다. 사용자 규칙으로도 "허용"으로 바꿀 수 없습니다.
| 분류 | 경로 |
|---|---|
| 에이전트 구성 | opencode.json*, .opencode/, AGENTS.md, CLAUDE.md, .claude/, .claude.json, .mcp.json |
| Git | .git/(전체), .gitconfig, .gitmodules, .config/git |
| 훅·자동 실행 | .husky/, .pre-commit-config.yaml, lefthook*.yml, .envrc, .devcontainer/ |
| 에디터·도구 설정 | .vscode/, .idea/, .cargo/, .yarn/, .mvn/, .npmrc, .yarnrc*, bunfig.toml |
| 셸 시작 파일 | .bashrc, .bash_profile, .zshrc, .zprofile, .zshenv, .profile |
이와 별개로 엔진 자체의 설정·데이터·상태 폴더에 쓰는 것은 항상 확인하고, 데이터·상태 폴더는 읽기도 확인합니다(자격 증명과 모든 세션 기록이 있기 때문).
계획 모드(plan)의 권한
/plan으로 실행되는 plan 에이전트는 파일을 바꾸지 않습니다. 계획 파일(.opencode/plans/*.md 또는 엔진 데이터 폴더의 plans/*.md)만 쓸 수 있고, 문서 편집 도구(document_*)와 general 서브에이전트 호출은 거부됩니다.
서브에이전트와 권한
서브에이전트의 권한 처리를 요약하면 다음과 같습니다.
- 서브에이전트가 만든 권한 요청도 같은 패널에 표시됩니다.
- "항상 허용" 승인과 AI 판정 기록은 루트 대화 단위로 공유되어, 서브에이전트가 부모의 결정을 이어받습니다.
- 서브에이전트의 자식 세션은 부모의 거부 규칙과 외부 경로 규칙을 물려받습니다.
todowrite,task는 서브에이전트 자신의 규칙에 명시하지 않으면 거부됩니다. - 부모가 어떤 서브에이전트를 부를 수 있는지는
task권한으로 제어합니다.
사용자 규칙으로 권한 바꾸기
엔진 설정의 permission에서 도구별로 allow / ask / deny를 지정할 수 있습니다. 사용자 규칙은 deny가 가장 강하고, 그다음 ask, allow 순서로 우선하며, 에이전트 자체 규칙의 deny(예: explore의 편집 금지)는 사용자 규칙으로 열 수 없습니다.
{
"permission": {
"bash": { "git status": "allow", "git push*": "deny" },
"webfetch": "ask"
}
}
설정 파일 위치와 적용 범위는 설정 참조를 보세요.