실행 승인 - OpenClaw

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

유효 정책은 tools.exec.*와 승인 기본값 중 더 엄격한 쪽입니다. 승인 필드가 생략되면 tools.exec 값이 사용됩니다. 호스트 실행은 해당 머신의 로컬 승인 상태도 사용합니다. ~/.openclaw/exec-approvals.json의 호스트 로컬 ask: "always"는 세션 또는 구성 기본값이 ask: "on-miss"를 요청하더라도 계속 프롬프트를 표시합니다.

유효 정책 검사

명령	표시 내용
`openclaw approvals get` / `--gateway` / `--node <id\|name\|ip>`	요청된 정책, 호스트 정책 소스, 유효 결과.
`openclaw exec-policy show`	로컬 머신 병합 보기.
`openclaw exec-policy set` / `preset`	로컬 요청 정책을 로컬 호스트 승인 파일과 한 단계에서 동기화합니다.

로컬 범위가 host=node를 요청하면, exec-policy show는 로컬 승인 파일이 신뢰 원본인 것처럼 가장하는 대신 런타임에 해당 범위를 Node 관리로 보고합니다. 컴패니언 앱 UI를 사용할 수 없는 경우, 일반적으로 프롬프트가 표시될 모든 요청은 ask fallback으로 해결됩니다(기본값: deny).

네이티브 채팅 승인 클라이언트는 대기 중인 승인 메시지에 채널별 편의 기능을 시드할 수 있습니다. 예를 들어 Matrix는 반응 바로가기(✅ 한 번 허용, ❌ 거부, ♾️ 항상 허용)를 시드하면서도 메시지 안의 /approve ... 명령을 대체 수단으로 남겨 둡니다.

적용 위치

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

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

신뢰 모델

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

macOS 분리

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

설정 및 저장소

승인은 실행 호스트의 로컬 JSON 파일에 저장됩니다.

~/.openclaw/exec-approvals.json

예시 스키마:

{
  "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"
        }
      ]
    }
  }
}

정책 조정 옵션

`exec.security`

security

"deny" | "allowlist" | "full"

deny - 모든 호스트 실행 요청을 차단합니다.
allowlist - 허용 목록에 있는 명령만 허용합니다.
full - 모든 것을 허용합니다(권한 상승과 동일).

`exec.ask`

ask

"off" | "on-miss" | "always"

off - 프롬프트를 표시하지 않습니다.
on-miss - 허용 목록이 일치하지 않을 때만 프롬프트를 표시합니다.
always - 모든 명령에서 프롬프트를 표시합니다. 유효 ask 모드가 always이면 allow-always의 지속 신뢰가 프롬프트를 억제하지 않습니다.

`askFallback`

askFallback

"deny" | "allowlist" | "full"

프롬프트가 필요하지만 연결 가능한 UI가 없을 때의 해결 방식입니다.

deny - 차단합니다.
allowlist - 허용 목록이 일치하는 경우에만 허용합니다.
full - 허용합니다.

`tools.exec.strictInlineEval`

strictInlineEval

boolean

true이면 OpenClaw는 인터프리터 바이너리 자체가 허용 목록에 있더라도 인라인 코드 평가 형식을 승인 전용으로 처리합니다. 하나의 안정적인 파일 피연산자에 깔끔하게 매핑되지 않는 인터프리터 로더를 위한 심층 방어입니다.

엄격 모드가 포착하는 예:

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`

commandHighlighting

boolean

기본값:"false"

Exec 승인 프롬프트의 표시 방식만 제어합니다. 활성화하면 OpenClaw가 파서에서 파생된 명령 범위를 첨부할 수 있어 Web 승인 프롬프트가 명령 토큰을 강조 표시할 수 있습니다. 명령 텍스트 강조 표시를 활성화하려면 true로 설정합니다.

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

YOLO 모드(승인 없음)

호스트 실행이 승인 프롬프트 없이 실행되게 하려면 두 정책 계층을 모두 열어야 합니다. OpenClaw 구성의 요청된 실행 정책(tools.exec.*)과 ~/.openclaw/exec-approvals.json의 호스트 로컬 승인 정책입니다. YOLO는 명시적으로 강화하지 않는 한 기본 호스트 동작입니다.

계층	YOLO 설정
`tools.exec.security`	`gateway`/`node`에서 `full`
`tools.exec.ask`	`off`
호스트 `askFallback`	`full`

중요한 차이점:

tools.exec.host=auto는 실행이 어디에서 실행되는지 선택합니다. 사용 가능한 경우 샌드박스, 그렇지 않으면 Gateway입니다.
YOLO는 호스트 실행이 어떻게 승인되는지 선택합니다. security=full과 ask=off입니다.
YOLO 모드에서 OpenClaw는 구성된 호스트 실행 정책 위에 별도의 휴리스틱 명령 난독화 승인 게이트나 스크립트 사전 실행 거부 계층을 추가하지 않습니다.
auto는 샌드박스된 세션에서 Gateway 라우팅을 자유롭게 재정의하도록 만들지 않습니다. 호출별 host=node 요청은 auto에서 허용됩니다. host=gateway는 활성 샌드박스 런타임이 없을 때만 auto에서 허용됩니다. 안정적인 비자동 기본값을 원하면 tools.exec.host를 설정하거나 /exec host=...를 명시적으로 사용하세요.

자체 비대화형 권한 모드를 노출하는 CLI 기반 공급자는 이 정책을 따를 수 있습니다. Claude CLI는 OpenClaw의 요청된 실행 정책이 YOLO일 때 --permission-mode bypassPermissions를 추가합니다. agents.defaults.cliBackends.claude-cli.args / resumeArgs 아래의 명시적 Claude 인수로 해당 백엔드 동작을 재정의하세요. 예: --permission-mode default, acceptEdits, bypassPermissions. 더 보수적인 설정을 원하면 어느 한 계층을 다시 allowlist / on-miss 또는 deny로 강화하세요.

지속적인 Gateway 호스트 “프롬프트 없음” 설정

요청된 구성 정책 설정

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw 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.
로컬 ~/.openclaw/exec-approvals.json 기본값.

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

Node 호스트

Node 호스트의 경우, 대신 해당 Node에 같은 승인 파일을 적용합니다.

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

로컬 전용 제한 사항:

openclaw exec-policy는 Node 승인을 동기화하지 않습니다.
openclaw exec-policy set --host node는 거부됩니다.
Node 실행 승인은 런타임에 Node에서 가져오므로, Node 대상 업데이트는 openclaw approvals --node ...를 사용해야 합니다.

세션 전용 바로가기

/exec security=full ask=off는 현재 세션만 변경합니다.
/elevated full은 해당 세션의 Exec 승인도 건너뛰는 비상용 바로가기입니다.

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

허용 목록(에이전트별)

허용 목록은 에이전트별입니다. 여러 에이전트가 있으면 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이 있는 항목은 일치하지 않습니다. 각 허용 목록 항목은 다음을 지원합니다.

필드	의미
`pattern`	확인된 바이너리 경로 glob 또는 단순 명령 이름 glob
`argPattern`	선택적 argv 정규식; 생략된 항목은 경로 전용입니다
`id`	UI 식별에 사용되는 안정적인 UUID
`source`	`allow-always` 같은 항목 출처
`commandText`	승인 흐름이 항목을 생성할 때 캡처된 명령 텍스트
`lastUsedAt`	마지막 사용 타임스탬프
`lastUsedCommand`	마지막으로 일치한 명령
`lastResolvedPath`	마지막으로 확인된 바이너리 경로

Skills CLI 자동 허용

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

이는 수동 경로 허용 목록 항목과 별개의 암시적 편의 허용 목록입니다.
Gateway와 Node가 동일한 신뢰 경계 안에 있는 신뢰할 수 있는 운영자 환경을 위한 것입니다.
엄격한 명시적 신뢰가 필요하면 autoAllowSkills: false를 유지하고 수동 경로 허용 목록 항목만 사용하세요.

안전한 bin 및 승인 전달

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

Control UI 편집

기본값, 에이전트별 재정의, 허용 목록을 편집하려면 Control UI → Nodes → Exec approvals 카드를 사용하세요. 범위(Defaults 또는 에이전트)를 선택하고, 정책을 조정하고, 허용 목록 패턴을 추가/제거한 다음 Save를 누르세요. UI는 패턴별 마지막 사용 메타데이터를 표시하므로 목록을 깔끔하게 유지할 수 있습니다. 대상 선택기는 Gateway(로컬 승인) 또는 Node를 선택합니다. Node는 system.execApprovals.get/set(macOS 앱 또는 헤드리스 Node 호스트)을 광고해야 합니다. Node가 아직 exec 승인을 광고하지 않는 경우 로컬 ~/.openclaw/exec-approvals.json을 직접 편집하세요. CLI: openclaw approvals는 Gateway 또는 Node 편집을 지원합니다. 자세한 내용은 승인 CLI를 참조하세요.

승인 흐름

프롬프트가 필요하면 Gateway는 exec.approval.requested를 운영자 클라이언트에 브로드캐스트합니다. Control UI와 macOS 앱은 exec.approval.resolve를 통해 이를 해결하고, 그러면 Gateway가 승인된 요청을 Node 호스트로 전달합니다. host=node의 경우 승인 요청에는 표준 systemRunPlan 페이로드가 포함됩니다. Gateway는 승인된 system.run 요청을 전달할 때 해당 계획을 권한 있는 command/cwd/session 컨텍스트로 사용합니다. 이는 비동기 승인 지연 시간에 중요합니다.

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

시스템 이벤트

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

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

이 메시지는 Node가 이벤트를 보고한 뒤 에이전트 세션에 게시됩니다. Gateway 호스트 exec 승인은 명령이 완료될 때(그리고 선택적으로 임계값보다 오래 실행될 때) 동일한 수명 주기 이벤트를 내보냅니다. 승인 게이트가 있는 exec는 쉽게 상호 연관할 수 있도록 이 메시지에서 승인 id를 runId로 재사용합니다.

거부된 승인 동작

비동기 exec 승인이 거부되면 OpenClaw는 에이전트가 세션에서 동일한 명령을 이전에 실행한 출력을 재사용하지 못하게 합니다. 거부 사유는 사용할 수 있는 명령 출력이 없다는 명시적 안내와 함께 전달되며, 이를 통해 에이전트가 새 출력이 있다고 주장하거나 이전에 성공한 실행의 오래된 결과로 거부된 명령을 반복하는 일을 막습니다.

영향

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

Exec approvals - advanced

안전한 bin, 인터프리터 바인딩, 채팅으로의 승인 전달.

Exec tool

셸 명령 실행 도구.

Elevated mode

승인도 건너뛰는 비상 경로.

Sandboxing

Sandbox 모드와 워크스페이스 접근.

Security

보안 모델과 강화.

Sandbox vs tool policy vs elevated

각 제어를 언제 사용해야 하는지.

Skills

Skill 기반 자동 허용 동작.

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Documentation Index

​유효 정책 검사

​적용 위치

​신뢰 모델

​macOS 분리

​설정 및 저장소

​정책 조정 옵션

​exec.security

​exec.ask

​askFallback

​tools.exec.strictInlineEval

​tools.exec.commandHighlighting

​YOLO 모드(승인 없음)

​지속적인 Gateway 호스트 “프롬프트 없음” 설정

​로컬 바로가기

​Node 호스트

​세션 전용 바로가기

​허용 목록(에이전트별)

​argPattern으로 인수 제한

​Skills CLI 자동 허용

​안전한 bin 및 승인 전달

​Control UI 편집

​승인 흐름

​시스템 이벤트

​거부된 승인 동작

​영향

​관련 항목

Exec approvals - advanced

Exec tool

Elevated mode

Sandboxing

Security

Sandbox vs tool policy vs elevated

Skills

유효 정책 검사

적용 위치

신뢰 모델

macOS 분리

설정 및 저장소

정책 조정 옵션

`exec.security`

`exec.ask`

`askFallback`

`tools.exec.strictInlineEval`

`tools.exec.commandHighlighting`

YOLO 모드(승인 없음)

지속적인 Gateway 호스트 “프롬프트 없음” 설정

로컬 바로가기

Node 호스트

세션 전용 바로가기

허용 목록(에이전트별)

argPattern으로 인수 제한

Skills CLI 자동 허용

안전한 bin 및 승인 전달

Control UI 편집

승인 흐름

시스템 이벤트

거부된 승인 동작

영향

관련 항목