Exec 도구

워크스페이스에서 셸 명령을 실행합니다. process를 통해 포그라운드 및 백그라운드 실행을 지원합니다. process가 비활성화되어 있으면, exec는 동기 방식으로 실행되며 yieldMs/background를 무시합니다. 백그라운드 세션은 에이전트 단위로 격리되어, process는 동일한 에이전트의 세션만 접근할 수 있습니다.

매개변수

command (필수)
workdir (기본값: 현재 작업 디렉터리)
env (키/값 오버라이드)
yieldMs (기본값 10000): 지정 시간 후 자동으로 백그라운드 전환
background (bool): 즉시 백그라운드 실행
timeout (초 단위, 기본값 1800): 시간 초과 시 종료
pty (bool): 가능한 경우 의사 터미널에서 실행 (TTY 전용 CLI, 코딩 에이전트, 터미널 UI용)
host (sandbox | gateway | node): 실행 위치
security (deny | allowlist | full): gateway/node의 보안 적용 모드
ask (off | on-miss | always): gateway/node의 승인 프롬프트
node (string): host=node일 때 노드 ID/이름
elevated (bool): 승격 모드 요청 (게이트웨이 호스트); security=full은 elevated가 full로 해석될 때만 강제 적용

참고사항:

host의 기본값은 sandbox입니다.
샌드박싱이 비활성화되어 있으면 elevated는 무시됩니다 (exec가 이미 호스트에서 실행 중이므로).
gateway/node 승인은 ~/.openclaw/exec-approvals.json으로 제어됩니다.
node를 사용하려면 페어링된 노드(컴패니언 앱 또는 헤드리스 노드 호스트)가 필요합니다.
여러 노드를 사용할 수 있는 경우, exec.node 또는 tools.exec.node를 설정하여 선택하세요.
Windows 외 호스트에서는 SHELL 환경변수가 설정되어 있으면 이를 사용합니다. SHELL이 fish인 경우, fish 비호환 스크립트를 피하기 위해 PATH에서 bash(또는 sh)를 우선 사용하며, 둘 다 없으면 SHELL로 폴백합니다.
Windows 호스트에서는 PowerShell 7(pwsh) 탐색(Program Files, ProgramW6432, PATH 순)을 우선하고, Windows PowerShell 5.1로 폴백합니다.
호스트 실행(gateway/node)에서는 바이너리 하이재킹이나 코드 주입을 방지하기 위해 env.PATH와 로더 오버라이드(LD_*/DYLD_*)를 거부합니다.
OpenClaw는 생성된 명령 환경(PTY 및 샌드박스 실행 포함)에 OPENCLAW_SHELL=exec를 설정하여, 셸/프로파일 규칙이 exec 도구 컨텍스트를 감지할 수 있도록 합니다.
중요: 샌드박싱은 기본적으로 비활성화되어 있습니다. 샌드박싱이 비활성화된 상태에서 host=sandbox가 명시적으로 설정/요청되면, exec는 게이트웨이 호스트에서 조용히 실행하는 대신 실패 처리합니다. 샌드박싱을 활성화하거나 host=gateway를 승인과 함께 사용하세요.
스크립트 사전 검사(흔한 Python/Node 셸 문법 오류 검출)는 유효 workdir 범위 내의 파일만 검사합니다. 스크립트 경로가 workdir 외부로 해석되면 해당 파일의 사전 검사는 건너뜁니다.

설정

tools.exec.notifyOnExit (기본값: true): true이면, 백그라운드 exec 세션이 종료 시 시스템 이벤트를 큐에 넣고 하트비트를 요청합니다.
tools.exec.approvalRunningNoticeMs (기본값: 10000): 승인 게이트 exec가 이 시간보다 오래 실행되면 “실행 중” 알림을 한 번 발행합니다 (0이면 비활성화).
tools.exec.host (기본값: sandbox)
tools.exec.security (기본값: 샌드박스는 deny, 게이트웨이 + 노드가 미설정이면 allowlist)
tools.exec.ask (기본값: on-miss)
tools.exec.node (기본값: 미설정)
tools.exec.pathPrepend: exec 실행 시 PATH 앞에 추가할 디렉터리 목록 (게이트웨이 + 샌드박스 전용).
tools.exec.safeBins: 명시적 허용 목록 항목 없이 실행 가능한 stdin 전용 안전 바이너리. 동작에 대한 자세한 내용은 Safe bins를 참고하세요.
tools.exec.safeBinTrustedDirs: safeBins 경로 검사를 위한 추가 신뢰 디렉터리. PATH 항목은 자동 신뢰되지 않습니다. 기본 내장값은 /bin과 /usr/bin입니다.
tools.exec.safeBinProfiles: 안전 바이너리별 선택적 커스텀 argv 정책 (minPositional, maxPositional, allowedValueFlags, deniedFlags).

예시:

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

PATH 처리

host=gateway: 로그인 셸의 PATH를 exec 환경에 병합합니다. 호스트 실행에서 env.PATH 오버라이드는 거부됩니다. 데몬 자체는 최소한의 PATH로 실행됩니다:
- macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
- Linux: /usr/local/bin, /usr/bin, /bin
host=sandbox: 컨테이너 내에서 sh -lc(로그인 셸)를 실행하므로, /etc/profile이 PATH를 재설정할 수 있습니다. OpenClaw는 프로파일 소싱 후 내부 환경변수를 통해 env.PATH를 앞에 추가합니다(셸 보간 없음). tools.exec.pathPrepend도 여기에 적용됩니다.
host=node: 차단되지 않은 env 오버라이드만 노드로 전송됩니다. 호스트 실행에서 env.PATH 오버라이드는 거부되며 노드 호스트에서도 무시됩니다. 노드에서 추가 PATH 항목이 필요한 경우, 노드 호스트 서비스 환경(systemd/launchd)을 구성하거나 표준 위치에 도구를 설치하세요.

에이전트별 노드 바인딩 (설정에서 에이전트 목록 인덱스 사용):

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

Control UI: Nodes 탭에 동일한 설정을 위한 작은 “Exec node binding” 패널이 있습니다.

세션 오버라이드 (`/exec`)

/exec를 사용하여 host, security, ask, node의 세션별 기본값을 설정할 수 있습니다. 인수 없이 /exec를 전송하면 현재 값을 표시합니다.

예시:

/exec host=gateway security=allowlist ask=on-miss node=mac-1

인가 모델

/exec는 인가된 발신자(채널 허용 목록/페어링 및 commands.useAccessGroups)에 한해 유효합니다. 세션 상태만 업데이트하며 설정을 저장하지 않습니다. exec를 완전히 비활성화하려면 도구 정책으로 차단하세요 (tools.deny: ["exec"] 또는 에이전트별). security=full과 ask=off를 명시적으로 설정하지 않는 한 호스트 승인이 계속 적용됩니다.

Exec 승인 (컴패니언 앱 / 노드 호스트)

샌드박스 에이전트는 exec가 게이트웨이 또는 노드 호스트에서 실행되기 전에 요청별 승인을 요구할 수 있습니다. 정책, 허용 목록, UI 흐름에 대해서는 Exec 승인을 참고하세요.

승인이 필요한 경우, exec 도구는 status: "approval-pending"과 승인 ID를 즉시 반환합니다. 승인(또는 거부/시간 초과) 후 게이트웨이는 시스템 이벤트(Exec finished / Exec denied)를 발행합니다. tools.exec.approvalRunningNoticeMs보다 오래 실행 중인 경우, Exec running 알림이 한 번 발행됩니다.

허용 목록 + 안전 바이너리

수동 허용 목록은 해석된 바이너리 경로만 매칭합니다(이름만으로는 매칭하지 않음). security=allowlist일 때, 셸 명령은 모든 파이프라인 세그먼트가 허용 목록이나 안전 바이너리에 해당하는 경우에만 자동 허용됩니다. 체이닝(;, &&, ||)과 리디렉션은 모든 최상위 세그먼트가 허용 목록을 충족하지 않으면 허용 목록 모드에서 거부됩니다(안전 바이너리 포함). 리디렉션은 지원되지 않습니다.

autoAllowSkills는 exec 승인의 별도 편의 경로입니다. 수동 경로 허용 목록 항목과 동일하지 않습니다. 엄격한 명시적 신뢰가 필요한 경우, autoAllowSkills를 비활성화하세요.

두 컨트롤을 서로 다른 용도로 사용하세요:

tools.exec.safeBins: 소규모 stdin 전용 스트림 필터.
tools.exec.safeBinTrustedDirs: 안전 바이너리 실행 파일 경로를 위한 명시적 추가 신뢰 디렉터리.
tools.exec.safeBinProfiles: 커스텀 안전 바이너리를 위한 명시적 argv 정책.
허용 목록: 실행 파일 경로에 대한 명시적 신뢰.

safeBins를 범용 허용 목록으로 사용하지 마세요. 또한 인터프리터/런타임 바이너리(python3, node, ruby, bash 등)를 추가하지 마세요. 이런 바이너리가 필요하면 명시적 허용 목록 항목을 사용하고 승인 프롬프트를 활성화 상태로 유지하세요. openclaw security audit는 인터프리터/런타임 safeBins 항목에 명시적 프로파일이 없으면 경고하며, openclaw doctor --fix는 누락된 커스텀 safeBinProfiles 항목을 스캐폴딩할 수 있습니다.

전체 정책 세부사항과 예시는 Exec 승인 및 Safe bins 대 허용 목록을 참고하세요.

예시

포그라운드:

{ "tool": "exec", "command": "ls -la" }

백그라운드 + 폴링:

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

키 전송 (tmux 스타일):

{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}

Submit (CR만 전송):

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

붙여넣기 (기본적으로 브래킷):

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

apply_patch (실험적)

apply_patch는 구조화된 다중 파일 편집을 위한 exec의 하위 도구입니다. 명시적으로 활성화하세요:

{
  tools: {
    exec: {
      applyPatch: { enabled: true, workspaceOnly: true, allowModels: ["gpt-5.2"] },
    },
  },
}