실행 승인

Exec 승인은 샌드박스된 에이전트가 실제 호스트(gateway 또는 node)에서 명령을 실행할 수 있도록 하는 컴패니언 앱/Node 호스트 보호 장치입니다. 명령은 정책, 허용 목록, 그리고 선택적인 사용자 승인이 모두 허용할 때만 실행됩니다. 승인은 도구 정책과 상승된 권한 게이트에 추가로 적용됩니다(상승된 권한 full은 승인을 건너뜁니다).

deny, allowlist, ask, auto, full, Codex Guardian 매핑, ACPX 하네스 권한을 모드 중심으로 개괄한 내용은 권한 모드를 참조하세요.

적용 위치

Exec 승인은 실행 호스트에서 로컬로 적용됩니다.

• Gateway 호스트 -> Gateway 시스템의 openclaw 프로세스.
• Node 호스트 -> Node 실행기(macOS 컴패니언 앱 또는 헤드리스 Node 호스트).

신뢰 모델

• Gateway 인증을 거친 호출자는 해당 Gateway의 신뢰할 수 있는 운영자로 간주됩니다.
• 페어링된 Node는 신뢰할 수 있는 운영자의 권한을 Node 호스트까지 확장합니다.
• 승인은 실수로 인한 실행 위험을 줄이지만 사용자별 인증 경계나 파일 시스템 읽기 전용 정책은 아닙니다.
• 명령이 승인되면 선택한 호스트 또는 샌드박스의 파일 시스템 권한에 따라 파일을 변경할 수 있습니다.
• 승인된 Node 호스트 실행은 정규 실행 컨텍스트, 즉 cwd, 정확한 argv, 존재하는 경우 환경 바인딩, 해당하는 경우 고정된 실행 파일 경로에 결속됩니다.
• 셸 스크립트와 인터프리터/런타임 파일을 직접 호출하는 경우 OpenClaw는 구체적인 로컬 파일 피연산자 하나에도 결속하려고 시도합니다. 승인 후 실행 전에 해당 파일이 변경되면 변경된 콘텐츠를 실행하는 대신 실행을 거부합니다.
• 파일 바인딩은 최선형 방식이며 모든 인터프리터/런타임 로더 경로를 완전히 포괄하는 모델은 아닙니다. 구체적인 로컬 파일을 정확히 하나 식별할 수 없는 경우 OpenClaw는 완전한 적용 범위를 가장하여 승인 기반 실행을 생성하지 않고 이를 거부합니다.

macOS 분리 구조

• Node 호스트 서비스는 로컬 IPC를 통해 system.run을 macOS 앱으로 전달합니다.
• macOS 앱은 승인을 적용하고 UI 컨텍스트에서 명령을 실행합니다.

유효 정책 검사

전체 CLI 참조(플래그, JSON 출력, 허용 목록 추가/제거): 승인 CLI.

로컬 범위에서 host=node를 요청하면 exec-policy show는 로컬 승인 파일을 진실의 원천으로 취급하는 대신 해당 범위가 런타임에서 Node에 의해 관리된다고 보고합니다.

컴패니언 앱 UI를 사용할 수 없는 경우 일반적으로 승인을 요청해야 하는 모든 요청은 질문 대체 정책(기본값: deny)에 따라 처리됩니다.

설정 및 저장소

승인은 실행 호스트의 로컬 JSON 파일에 저장됩니다. OPENCLAW_STATE_DIR이 설정되어 있으면 파일은 해당 상태 디렉터리를 따르고, 그렇지 않으면 기본 OpenClaw 상태 디렉터리를 사용합니다.

$OPENCLAW_STATE_DIR/exec-approvals.json# otherwise~/.openclaw/exec-approvals.json

기본 승인 소켓도 동일한 루트를 따릅니다. $OPENCLAW_STATE_DIR/exec-approvals.sock 또는 변수가 설정되지 않은 경우 ~/.openclaw/exec-approvals.sock입니다.

2026.6.6 이전 릴리스는 항상 파일을 ~/.openclaw에 보관했습니다. OPENCLAW_STATE_DIR이 다른 위치를 가리키고 기본 디렉터리에 승인 파일이 여전히 존재한다면 openclaw doctor --fix를 직접 한 번 실행하여 상태 디렉터리로 가져오세요(원본은 .migrated 접미사와 함께 보관됩니다). 대화형 Doctor에서도 가져오기를 미리 보고 확인할 수 있습니다. 자동 업데이트 및 Gateway 감시 복구 실행은 상태 디렉터리 간 가져오기를 수행하지 않습니다. 임시 또는 스테이징 상태 디렉터리가 기본 설치의 승인을 가져가서는 안 됩니다. 동일한 경계가 레거시 plugin-binding-approvals.json을 공유 SQLite 상태로 가져올 때도 적용됩니다.

스키마 예시:

{  "version": 1,  "socket": {    "path": "~/.openclaw/exec-approvals.sock",    "token": "base64url-token"  },  "defaults": {    "security": "deny",    "ask": "on-miss",    "askFallback": "deny",    "autoAllowSkills": false  },  "agents": {    "main": {      "security": "allowlist",      "ask": "on-miss",      "askFallback": "deny",      "autoAllowSkills": true,      "allowlist": [        {          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",          "pattern": "~/Projects/**/bin/rg",          "source": "allow-always",          "lastUsedAt": 1737150000000,          "lastUsedCommand": "rg -n TODO",          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"        }      ]    }  }}

정책 설정 항목

tools.exec.mode

tools.exec.mode는 호스트 Exec에 권장되는 정규화된 정책 표면입니다.

레거시 tools.exec.security / tools.exec.ask도 계속 지원되며 해당 범위에 mode가 설정되지 않은 모든 곳에 여전히 적용됩니다.

exec.security

exec.ask

askFallback

tools.exec.strictInlineEval

엄격 모드가 포착하는 예: python -c, node -e/--eval/-p, ruby -e, perl -e/-E, php -r, lua -e, osascript -e(awk, sed, make, find -exec, xargs 인라인 형식도 포함).

엄격 모드에서는 이러한 명령에 검토자 또는 명시적인 승인이 필요합니다. tools.exec.mode: "auto"를 사용하면 명령에 적용 가능한 계획이 있을 때 검토자가 위험도가 낮은 실행을 한 번 허용할 수 있으며, 그렇지 않으면 OpenClaw가 사람에게 묻습니다. 검토자 대체 경로에 도달하는 Codex app-server 명령 승인은 승인 요청에서 적용 가능한 확인된 실행 파일을 노출하지 않으므로 사람에게 묻습니다. allow-always는 인라인 평가 명령에 대한 새 허용 목록 항목을 영구 저장하지 않습니다.

tools.exec.commandHighlighting

전역에서는 tools.exec.commandHighlighting 아래에 설정하고, 에이전트별로는 agents.list[].tools.exec.commandHighlighting 아래에 설정합니다.

YOLO 모드(승인 없음)

승인 프롬프트 없이 호스트 Exec을 실행하려면 두 정책 계층을 모두 개방하세요. OpenClaw 구성의 요청된 Exec 정책(tools.exec.*)과 실행 호스트 승인 파일의 호스트 로컬 승인 정책입니다.

생략된 askFallback의 기본값은 deny입니다. UI가 없을 때 승인 프롬프트를 허용으로 대체해야 한다면 호스트 askFallback을 명시적으로 full로 설정하세요.

자체 비대화형 권한 모드를 노출하는 CLI 기반 제공자는 이 정책을 따를 수 있습니다. OpenClaw의 유효 실행 정책이 YOLO이면 Claude CLI는 --permission-mode bypassPermissions를 추가합니다. OpenClaw에서 관리하는 Claude 라이브 세션에서는 OpenClaw의 유효 실행 정책이 Claude의 기본 권한 모드보다 우선합니다. YOLO는 라이브 실행을 --permission-mode bypassPermissions로 정규화하고, 제한적인 유효 실행 정책은 원시 Claude 백엔드 인수에 다른 모드가 지정되어 있더라도 라이브 실행을 --permission-mode default로 정규화합니다.

더 보수적으로 설정하려면 OpenClaw 실행 정책을 allowlist / on-miss 또는 deny로 다시 강화하세요.

영구 Gateway 호스트 "프롬프트 표시 안 함" 설정

openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

openclaw approvals set --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

로컬 바로 가기

openclaw exec-policy preset yolo

로컬 tools.exec.host/security/ask와 로컬 승인 파일의 기본값(askFallback: "full" 포함)을 모두 업데이트합니다. 의도적으로 로컬에만 적용됩니다. Gateway 호스트 또는 Node 호스트의 승인을 원격으로 변경하려면 openclaw approvals set --gateway 또는 openclaw approvals set --node <id|name|ip>를 사용하세요.

기타 기본 제공 프리셋은 cautious(host=gateway, security=allowlist, ask=on-miss, askFallback=deny)와 deny-all(host=gateway, security=deny, ask=off, askFallback=deny)입니다. 같은 방식으로 적용합니다: openclaw exec-policy preset cautious.

전체 프리셋 대신 개별 필드를 설정하려면 해당 플래그 중 원하는 일부와 함께 openclaw exec-policy set --host <auto|sandbox|gateway|node> --security <deny|allowlist|full> --ask <off|on-miss|always> --ask-fallback <deny|allowlist|full>을 사용하세요.

Node 호스트

대신 Node에 동일한 승인 파일을 적용합니다.

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

세션 전용 바로 가기

• /exec security=full ask=off는 현재 세션만 변경합니다.
• /elevated full은 요청된 정책과 호스트 승인 파일이 모두 security: "full" 및 ask: "off"로 결정될 때만 실행 승인을 건너뛰는 비상용 바로 가기입니다. ask: "always"와 같이 더 엄격한 호스트 파일은 여전히 프롬프트를 표시합니다.

호스트 승인 파일이 구성보다 더 엄격하게 유지되면 더 엄격한 호스트 정책이 계속 우선합니다.

허용 목록(에이전트별)

허용 목록은 에이전트별입니다. 여러 에이전트가 있는 경우 macOS 앱에서 편집할 에이전트를 전환하세요. 패턴은 glob 방식으로 일치합니다.

패턴에는 해석된 바이너리 경로 glob 또는 명령어 이름만으로 구성된 glob을 사용할 수 있습니다. 이름만 있는 패턴은 PATH를 통해 호출된 명령에만 일치하므로, 명령이 rg이면 rg는 /opt/homebrew/bin/rg와 일치할 수 있지만 ./rg 또는 /tmp/rg와는 일치하지 않습니다. 특정 바이너리 위치 하나만 신뢰하려면 경로 glob을 사용하세요.

레거시 agents.default 항목은 로드 시 agents.main으로 마이그레이션됩니다. echo ok && pwd와 같은 셸 체인도 각 최상위 구간이 모두 허용 목록 규칙을 충족해야 합니다.

예:

• rg
• ~/Projects/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

argPattern으로 인수 제한하기

허용 목록 항목이 바이너리와 특정 인수 형태에 모두 일치해야 하는 경우 argPattern을 추가하세요. OpenClaw는 모든 호스트에서 ECMAScript(JavaScript) 정규식 의미론을 사용하며, 실행 파일 토큰(argv[0])을 제외한 파싱된 명령 인수를 대상으로 표현식을 평가합니다. 직접 작성한 항목에서는 인수를 공백 하나로 연결하므로 정확히 일치시켜야 할 때는 패턴에 앵커를 사용하세요.

{  "version": 1,  "agents": {    "main": {      "allowlist": [        {          "pattern": "python3",          "argPattern": "^safe\\.py$"        }      ]    }  }}

이 항목은 python3 safe.py를 허용하지만 python3 other.py는 허용 목록에 일치하지 않습니다. 동일한 바이너리에 대한 경로 전용 항목도 있으면 일치하지 않는 인수가 해당 경로 전용 항목으로 대체 일치할 수 있습니다. 바이너리를 선언된 인수로 제한하려는 경우 경로 전용 항목을 생략하세요.

승인 흐름에서 저장한 항목은 정확한 argv 일치를 위해 내부 구분자 형식을 사용합니다. 인코딩된 값을 직접 편집하기보다 UI 또는 승인 흐름을 사용하여 해당 항목을 다시 생성하는 것이 좋습니다. OpenClaw가 명령 구간의 argv를 파싱할 수 없으면 argPattern이 있는 항목은 일치하지 않습니다.

각 허용 목록 항목에서 지원하는 필드는 다음과 같습니다.

Skills CLI 자동 허용

Skills CLI 자동 허용(autoAllowSkills)이 활성화되면 알려진 Skills에서 참조하는 실행 파일이 Node(macOS Node 또는 헤드리스 Node 호스트)의 허용 목록에 있는 것으로 처리됩니다. 이는 Gateway RPC를 통해 skills.bins를 사용하여 Skills 바이너리 목록을 가져옵니다. 엄격한 수동 허용 목록을 사용하려면 이 기능을 비활성화하세요.

안전한 바이너리와 승인 전달

안전한 바이너리(stdin 전용 빠른 경로), 인터프리터 바인딩 세부 정보, 승인 프롬프트를 Slack/Discord/Telegram으로 전달하거나 기본 승인 클라이언트로 실행하는 방법은 실행 승인 - 고급을 참조하세요.

Control UI에서 편집하기

기본값, 에이전트별 재정의 및 허용 목록을 편집하려면 Control UI -> Nodes -> Exec approvals 카드를 사용하세요. 범위(Defaults 또는 에이전트)를 선택하고 정책을 조정한 다음 허용 목록 패턴을 추가하거나 제거하고 Save를 선택하세요. UI는 패턴별 마지막 사용 메타데이터를 표시하므로 목록을 깔끔하게 유지할 수 있습니다.

대상 선택기에서 Gateway(로컬 승인) 또는 Node를 선택합니다. Node는 system.execApprovals.get/set을 알릴 수 있어야 합니다(macOS 앱 또는 헤드리스 Node 호스트). Node가 아직 실행 승인 기능을 알리지 않는다면 로컬 승인 파일을 직접 편집하세요.

Windows 컴패니언을 포함한 일부 Node 호스트는 다른 승인 정책 형식을 자체적으로 관리합니다. Control UI는 이러한 호스트 기본 정책을 읽기 전용으로 표시합니다. 편집하려면 컴패니언 앱 또는 기본 정책 형식과 함께 openclaw approvals set --node <id|name|ip>를 사용하세요. 승인 CLI를 참조하세요.

CLI: openclaw approvals는 Gateway 또는 Node 편집을 지원합니다. 승인 CLI를 참조하세요.

승인 흐름

프롬프트가 필요하면 Gateway가 운영자 클라이언트에 exec.approval.requested를 브로드캐스트합니다. Control UI와 macOS 앱은 exec.approval.resolve를 통해 이를 처리한 다음, Gateway가 승인된 요청을 Node 호스트로 전달합니다.

host=node의 경우 승인 요청에 정규 systemRunPlan 페이로드가 포함됩니다. Gateway는 승인된 system.run 요청을 전달할 때 해당 계획을 명령/cwd/세션 컨텍스트의 기준으로 사용합니다.

• Node 실행 경로는 처음부터 하나의 정규 계획을 준비합니다.
• 승인 레코드는 해당 계획과 바인딩 메타데이터를 저장합니다.
• 승인되면 최종 전달되는 system.run 호출은 이후 호출자의 편집 내용을 신뢰하는 대신 저장된 계획을 재사용합니다.
• 승인 요청이 생성된 후 호출자가 command, rawCommand, cwd, agentId 또는 sessionKey를 변경하면 Gateway는 승인 불일치로 전달된 실행을 거부합니다.

시스템 이벤트 및 거부

Node에서 완료를 보고하면 실행 수명 주기가 에이전트 세션에 Exec finished 시스템 메시지를 게시합니다. OpenClaw는 승인이 허용된 후 tools.exec.approvalRunningNoticeMs가 경과하면 진행 중 알림도 보낼 수 있습니다(기본값 10000, 0이면 비활성화). 거부된 실행 승인은 호스트 명령에 대해 최종적이며, 명령은 실행되지 않습니다.

• 원본 세션이 있는 주 에이전트의 비동기 승인이 거부되면 OpenClaw는 해당 거부를 내부 후속 메시지로 세션에 다시 게시하여 에이전트가 비동기 명령 대기를 중단하고 누락된 결과 복구를 방지할 수 있도록 합니다.
• 세션이 없거나 세션을 재개할 수 없는 경우에도 OpenClaw는 운영자 또는 직접 채팅 경로에 간결한 거부 내용을 보고할 수 있습니다.
• 하위 에이전트 및 Cron 세션의 거부는 해당 세션에 다시 게시되지 않습니다.

Gateway 호스트 실행 승인도 동일한 완료 수명 주기 이벤트를 발생시킵니다. 승인으로 제한된 실행은 승인 ID를 재사용하여 대기 중인 요청과 완료/거부 메시지(Exec finished (gateway id=...) / Exec denied (gateway id=...))를 연관 짓습니다.

영향

• **full**은 강력하므로 가능하면 허용 목록을 사용하는 것이 좋습니다.
• **ask**는 빠른 승인을 허용하면서도 사용자가 계속 개입할 수 있게 합니다.
• 에이전트별 허용 목록은 한 에이전트의 승인이 다른 에이전트로 유출되는 것을 방지합니다.
• 승인은 권한이 부여된 발신자의 호스트 실행 요청에만 적용됩니다. 권한이 없는 발신자는 /exec를 실행할 수 없습니다.
• /exec security=full은 권한이 부여된 운영자를 위한 세션 수준 편의 기능이며 의도적으로 승인을 건너뜁니다. 호스트 실행을 완전히 차단하려면 승인 보안을 deny로 설정하거나 도구 정책을 통해 exec 도구를 거부하세요.

관련 항목