실행 승인

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

# 유효 정책 검사

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

동반 앱 UI를 사용할 수 없는 경우, 일반적으로 프롬프트를 표시할 모든 요청은 ask 대체 동작(기본값: deny)으로 해결됩니다.

# 적용 위치

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

• Gateway 호스트 → Gateway 머신의 openclaw 프로세스입니다.
• Node 호스트 → Node 러너(macOS 동반 앱 또는 헤드리스 Node 호스트)입니다.

# 신뢰 모델

• Gateway 인증 호출자는 해당 Gateway의 신뢰된 운영자입니다.
• 페어링된 Node는 신뢰된 운영자 기능을 Node 호스트로 확장합니다.
• Exec 승인은 실수로 인한 실행 위험을 줄이지만, 사용자별 인증 경계는 아닙니다.
• 승인된 Node 호스트 실행은 표준 실행 컨텍스트를 바인딩합니다. 표준 cwd, 정확한 argv, 존재하는 경우 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

# 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는 새 허용 목록 항목을 자동으로 영구 저장하지 않습니다.

# YOLO 모드(승인 없음)

호스트 exec를 승인 프롬프트 없이 실행하려면 두 정책 계층을 모두 열어야 합니다. OpenClaw 구성의 요청된 exec 정책(tools.exec.*)과 ~/.openclaw/exec-approvals.json의 호스트 로컬 승인 정책입니다.

YOLO는 명시적으로 강화하지 않는 한 기본 호스트 동작입니다.

자체 비대화형 권한 모드를 노출하는 CLI 기반 제공자는 이 정책을 따를 수 있습니다. OpenClaw의 요청된 exec 정책이 YOLO이면 Claude CLI는 --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

# 세션 전용 바로 가기

• /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이 있는 항목은 일치하지 않습니다.

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

# Skill CLI 자동 허용

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

# 안전한 bin 및 승인 전달

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

# 제어 UI 편집

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

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

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

# 승인 흐름

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

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

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

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

# 시스템 이벤트

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

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

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

# 거부된 승인 동작

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

# 영향

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

# 관련 항목