실행 승인

Exec 승인은 샌드박스된 에이전트가 실제 호스트(gateway 또는 node)에서 명령을 실행하도록 허용하기 위한 컴패니언 앱 / 노드 호스트 가드레일입니다. 안전 인터록으로, 정책 + 허용 목록 + (선택 사항) 사용자 승인이 모두 일치할 때만 명령이 허용됩니다. Exec 승인은 도구 정책과 상승 권한 게이트 위에 쌓입니다(full로 설정된 상승 권한은 승인을 건너뜁니다).

deny, allowlist, ask, auto, full, Codex Guardian 매핑, ACPX 하네스 권한에 대한 모드 우선 개요는 권한 모드를 참고하세요.

유효 정책 검사

로컬 범위가 host=node를 요청하면, exec-policy show는 로컬 승인 파일을 진실의 원천인 것처럼 가장하지 않고 런타임에 해당 범위를 노드 관리로 보고합니다.

컴패니언 앱 UI를 사용할 수 없으면, 일반적으로 프롬프트가 표시될 모든 요청은 ask 폴백(기본값: deny)으로 해결됩니다.

적용 위치

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

• Gateway 호스트 → 게이트웨이 머신의 openclaw 프로세스.
• Node 호스트 → 노드 러너(macOS 컴패니언 앱 또는 헤드리스 노드 호스트).

신뢰 모델

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

macOS 분리

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

설정 및 저장소

승인은 실행 호스트의 로컬 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입니다.

예시 스키마:

{  "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",          "commandText": "rg -n TODO",          "lastUsedAt": 1737150000000,          "lastUsedCommand": "rg -n TODO",          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"        }      ]    }  }}

정책 조절 항목

tools.exec.mode

tools.exec.mode는 호스트 exec를 위한 선호되는 정규화 정책 표면입니다. 값은 다음과 같습니다.

• deny - 호스트 exec를 차단합니다.
• allowlist - 묻지 않고 허용 목록에 있는 명령만 실행합니다.
• ask - 허용 목록 정책을 사용하고 누락 시 묻습니다.
• auto - 허용 목록 정책을 사용하고, 결정론적 일치는 직접 실행하며, 승인 누락은 사람 승인 경로로 폴백하기 전에 OpenClaw의 네이티브 자동 리뷰어로 보냅니다.
• full - 승인 프롬프트 없이 호스트 exec를 실행합니다.

레거시 tools.exec.security / tools.exec.ask는 계속 지원되며 더 좁은 세션 또는 에이전트 범위에서 설정된 경우 여전히 우선합니다.

exec.security

exec.ask

askFallback

tools.exec.strictInlineEval

엄격 모드가 잡아내는 예:

• python -c
• node -e, node --eval, node -p
• ruby -e
• perl -e, perl -E
• php -r
• lua -e
• osascript -e

엄격 모드에서는 이러한 명령에 여전히 명시적 승인이 필요하며, allow-always는 새 허용 목록 항목을 자동으로 영구 저장하지 않습니다.

tools.exec.commandHighlighting

이 설정은 security, ask, 허용 목록 일치, 엄격 인라인 평가 동작, 승인 전달, 명령 실행을 변경하지 않습니다. 전역적으로 tools.exec.commandHighlighting 아래에 설정하거나 에이전트별로 agents.list[].tools.exec.commandHighlighting 아래에 설정할 수 있습니다.

YOLO 모드(승인 없음)

호스트 exec가 승인 프롬프트 없이 실행되도록 하려면 두 정책 계층을 모두 열어야 합니다. OpenClaw 구성의 요청된 exec 정책(tools.exec.*) 및 실행 호스트 승인 파일의 호스트 로컬 승인 정책입니다.

OpenClaw는 생략된 askFallback의 기본값을 deny로 둡니다. UI 없는 승인 프롬프트가 허용으로 폴백해야 하는 경우 호스트 askFallback을 명시적으로 full로 설정하세요.

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

더 보수적인 설정을 원하면 OpenClaw exec 정책을 다시 allowlist / on-miss 또는 deny로 강화하세요.

영구 게이트웨이 호스트 "프롬프트 없음" 설정

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"를 포함한 로컬 승인 파일 기본값.

의도적으로 로컬 전용입니다. 게이트웨이 호스트 또는 노드 호스트 승인을 원격으로 변경하려면 openclaw approvals set --gateway 또는 openclaw approvals set --node <id|name|ip>를 사용하세요.

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"로 해석될 때만 exec 승인을 건너뛰는 비상용 바로가기입니다. ask: "always" 같은 더 엄격한 호스트 파일은 여전히 프롬프트를 표시합니다.

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

허용 목록(에이전트별)

허용 목록은 에이전트별입니다. 여러 에이전트가 있으면 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는 실행 파일 토큰(argv[0])을 제외한 파싱된 명령 인수에 대해 정규식을 평가합니다. 직접 작성한 항목의 경우 인수는 단일 공백으로 결합되므로, 정확한 일치가 필요하면 패턴에 앵커를 사용하세요.

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

이 항목은 python3 safe.py를 허용하며, python3 other.py는 허용 목록에 일치하지 않습니다. 같은 바이너리에 대한 경로 전용 항목도 있으면, 일치하지 않는 인수는 여전히 그 경로 전용 항목으로 폴백될 수 있습니다. 목표가 바이너리를 선언된 인수로 제한하는 것이라면 경로 전용 항목을 생략하세요.

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

각 허용 목록 항목은 다음을 지원합니다.

Skill CLI 자동 허용

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

안전한 bin과 승인 전달

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

Control UI 편집

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

대상 선택기는 Gateway(로컬 승인) 또는 Node를 선택합니다. 노드는 system.execApprovals.get/set을 광고해야 합니다(macOS 앱 또는 헤드리스 노드 호스트). 노드가 아직 exec 승인을 광고하지 않으면 해당 로컬 승인 파일을 직접 편집하세요.

CLI: openclaw approvals는 Gateway 또는 노드 편집을 지원합니다. 자세한 내용은 승인 CLI를 참조하세요.

승인 흐름

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

host=node의 경우 승인 요청에는 정규 systemRunPlan 페이로드가 포함됩니다. Gateway는 승인된 system.run 요청을 전달할 때 이 플랜을 권위 있는 command/cwd/session 컨텍스트로 사용합니다.

이는 비동기 승인 지연 시간에 중요합니다.

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

시스템 이벤트

Exec 수명 주기는 시스템 메시지로 표시됩니다.

• Exec running(명령이 실행 중 알림 임계값을 초과하는 경우에만).
• Exec finished.

이 메시지는 노드가 이벤트를 보고한 뒤 에이전트의 세션에 게시됩니다. 거부된 exec 승인은 호스트 명령 자체에 대해 터미널 상태입니다. 명령은 실행되지 않습니다. 원래 세션이 있는 메인 에이전트 비동기 승인에서 OpenClaw는 거부를 해당 세션에 내부 후속 메시지로 다시 게시하여 에이전트가 비동기 명령을 기다리는 것을 중단하고 누락된 결과 복구를 피할 수 있게 합니다. 세션이 없거나 세션을 재개할 수 없으면 OpenClaw는 여전히 운영자 또는 직접 채팅 경로에 간결한 거부를 보고할 수 있습니다. 하위 에이전트 세션의 거부는 하위 에이전트에 다시 게시되지 않습니다. Gateway 호스트 exec 승인은 명령이 완료될 때(그리고 선택적으로 임계값보다 오래 실행될 때) 동일한 수명 주기 이벤트를 내보냅니다. 승인으로 보호되는 exec는 쉽게 상관관계를 파악할 수 있도록 이 메시지에서 승인 id를 runId로 재사용합니다.

거부된 승인 동작

비동기 exec 승인이 거부되면 OpenClaw는 호스트 명령을 터미널 상태로 간주하고 fail-closed로 처리합니다. 메인 에이전트 세션의 경우, 거부는 비동기 명령이 실행되지 않았음을 에이전트에 알리는 내부 세션 후속 메시지로 전달됩니다. 이는 오래된 명령 출력을 노출하지 않으면서 transcript 연속성을 보존합니다. 세션 전달을 사용할 수 없으면 안전한 경로가 있을 때 OpenClaw는 간결한 운영자 또는 직접 채팅 거부로 폴백합니다.

영향

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

관련 항목