OpenClaw Exec 툴 가이드: 워크스페이스에서 쉘 명령어 실행하기

개발하다 보면 터미널과 에디터를 오가며 명령어를 입력하는 게 꽤 번거로울 때가 있죠? 특히 워크스페이스 안에서 여러 작업을 자동화하고 싶을 때 Exec tool이 정말 유용해요. 셸 명령어를 자유롭게 실행하면서도 보안까지 꼼꼼하게 챙길 수 있는 방법을 소개해 드릴게요.

Exec tool

워크스페이스에서 셸 명령어를 실행합니다. process를 통해 포그라운드와 백그라운드 실행을 모두 지원해요. 만약 process가 허용되지 않으면 exec은 동기적으로 실행되며 yieldMs나 background 설정은 무시됩니다. 백그라운드 세션은 에이전트별로 범위가 지정되며, process는 동일한 에이전트의 세션만 볼 수 있습니다.

매개변수

command (필수)
workdir (기본값은 cwd)
env (키/값 오버라이드)
yieldMs (기본값 10000): 설정된 지연 시간 후 자동으로 백그라운드 전환
background (bool): 즉시 백그라운드에서 실행
timeout (초 단위, 기본값 1800): 만료 시 프로세스 종료
pty (bool): 사용 가능한 경우 의사 터미널(pseudo-terminal)에서 실행 (TTY 전용 CLI, 코딩 에이전트, 터미널 UI용)
host (auto | sandbox | gateway | node): 실행 위치
security (deny | allowlist | full): gateway/node에 대한 보안 강제 모드
ask (off | on-miss | always): gateway/node에 대한 승인 프롬프트 설정
node (string): host=node일 때 사용할 노드 ID 또는 이름
elevated (bool): 권한 상승 모드 요청 (gateway 호스트); elevated가 full로 해결될 때만 security=full이 강제됩니다.

참고 사항:

host 기본값은 auto입니다. 세션에 sandbox 런타임이 활성화되어 있으면 sandbox를, 그렇지 않으면 gateway를 사용해요.
elevated를 사용하면 host=gateway가 강제됩니다. 현재 세션이나 프로바이더에서 권한 상승 액세스가 활성화된 경우에만 사용할 수 있어요.
gateway/node 승인은 ~/.openclaw/exec-approvals.json 파일에서 제어합니다.
node를 사용하려면 연결된 노드(컴패니언 앱 또는 헤드리스 노드 호스트)가 필요해요.
사용할 수 있는 노드가 여러 개라면 exec.node나 tools.exec.node를 설정해서 하나를 선택하세요.
exec host=node는 노드에서 셸 명령어를 실행하는 유일한 경로입니다. 기존의 nodes.run 래퍼는 제거되었어요.
Windows가 아닌 호스트에서 exec은 SHELL 환경 변수가 설정되어 있으면 이를 사용합니다. 만약 SHELL이 fish라면, fish와 호환되지 않는 스크립트 문제를 피하기 위해 PATH에서 bash(또는 sh)를 먼저 찾고, 둘 다 없으면 SHELL을 사용해요.
Windows 호스트에서 exec은 PowerShell 7(pwsh)을 먼저 찾고(Program Files, ProgramW6432, PATH 순서), 없으면 Windows PowerShell 5.1을 사용합니다.
호스트 실행(gateway/node) 시 바이너리 하이재킹이나 코드 주입을 방지하기 위해 env.PATH와 로더 오버라이드(LD_*/DYLD_*) 설정은 거부됩니다.
OpenClaw는 실행되는 명령어 환경(PTY 및 sandbox 실행 포함)에 OPENCLAW_SHELL=exec을 설정합니다. 덕분에 셸이나 프로필 규칙에서 exec-tool 컨텍스트를 감지할 수 있어요.
중요: 샌드박싱은 기본적으로 꺼져 있습니다. 샌드박싱이 꺼져 있으면 암시적인 host=auto는 gateway로 연결돼요. 명시적인 host=sandbox 설정은 gateway에서 몰래 실행되는 대신 실패로 처리됩니다. 샌드박싱을 활성화하거나 승인 절차와 함께 host=gateway를 사용하세요.
스크립트 사전 검사(일반적인 Python/Node 셸 구문 오류 확인)는 유효한 workdir 범위 내의 파일만 검사합니다. 스크립트 경로가 workdir 외부로 연결되면 해당 파일에 대한 사전 검사는 건너뜁니다.

설정

tools.exec.notifyOnExit (기본값: true): true일 때, 백그라운드에서 실행 중인 exec 세션이 종료되면 시스템 이벤트를 대기열에 추가하고 하트비트를 요청해요.
tools.exec.approvalRunningNoticeMs (기본값: 10000): 승인이 필요한 exec이 이 시간보다 오래 실행되면 “running” 알림을 한 번 보냅니다 (0은 비활성화).
tools.exec.host (기본값: auto; sandbox 런타임이 활성화되면 sandbox, 아니면 gateway로 연결됨)
tools.exec.security (기본값: sandbox는 deny, 설정되지 않은 경우 gateway + node는 allowlist)
tools.exec.ask (기본값: on-miss)
tools.exec.node (기본값: 설정되지 않음)
tools.exec.strictInlineEval (기본값: false): true일 때, python -c, node -e, ruby -e, perl -e, php -r, lua -e, osascript -e 같은 인라인 인터프리터 평가 형식은 항상 명시적인 승인이 필요합니다. allow-always를 통해 일반적인 인터프리터/스크립트 호출은 유지할 수 있지만, 인라인 평가 형식은 매번 확인을 요청해요.
tools.exec.pathPrepend: exec 실행 시 PATH 앞에 추가할 디렉터리 목록입니다 (gateway + sandbox 전용).
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.PATH 오버라이드는 거부되며 노드 호스트에서 무시돼요. 노드에 추가적인 PATH 항목이 필요하다면 노드 호스트 서비스 환경(systemd/launchd)을 설정하거나 표준 위치에 도구를 설치하세요.

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

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

제어 UI: 노드(Nodes) 탭의 “Exec node binding” 패널에서도 동일한 설정을 할 수 있습니다.

세션 오버라이드 (/exec)

host, security, ask, node에 대한 세션별 기본값을 설정하려면 /exec를 사용하세요. 인자 없이 /exec를 보내면 현재 값을 확인할 수 있습니다.

예시:

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

권한 모델

/exec는 권한이 있는 발신자(채널 화이트리스트/페어링 및 commands.useAccessGroups)에게만 허용됩니다. 이는 세션 상태만 업데이트하며 설정을 저장하지는 않아요. exec을 완전히 비활성화하려면 도구 정책(tools.deny: ["exec"] 또는 에이전트별 설정)을 통해 거부하세요. security=full과 ask=off를 명시적으로 설정하지 않는 한 호스트 승인은 여전히 적용됩니다.

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

샌드박스 에이전트가 gateway나 노드 호스트에서 exec을 실행하기 전에 요청마다 승인을 받도록 설정할 수 있습니다. 정책, 화이트리스트, UI 흐름에 대해서는 Exec approvals를 참고하세요.

승인이 필요한 경우, exec 도구는 즉시 status: "approval-pending"과 승인 ID를 반환합니다. 승인(또는 거부/시간 초과)되면 Gateway에서 시스템 이벤트(Exec finished / Exec denied)를 보냅니다. 명령어가 tools.exec.approvalRunningNoticeMs 이후에도 실행 중이라면 Exec running 알림이 한 번 전송돼요.

화이트리스트 및 안전 바이너리

수동 화이트리스트 강제 적용은 확인된 바이너리 경로만 일치시킵니다 (파일명만으로는 일치하지 않아요). security=allowlist일 때, 모든 파이프라인 세그먼트가 화이트리스트에 있거나 안전 바이너리인 경우에만 셸 명령어가 자동으로 허용됩니다. 화이트리스트 모드에서는 모든 최상위 세그먼트가 화이트리스트(안전 바이너리 포함)를 만족하지 않으면 체이닝(;, &&, ||)과 리다이렉션이 거부됩니다. 리다이렉션은 아직 지원되지 않아요. 지속적인 allow-always 신뢰도 이 규칙을 우회할 수 없습니다. 체이닝된 명령어는 여전히 모든 최상위 세그먼트가 일치해야 해요.

autoAllowSkills는 실행 승인에서 별도로 제공하는 편의 기능입니다. 수동 경로 화이트리스트 항목과는 달라요. 엄격하고 명시적인 신뢰를 원한다면 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 항목을 구성할 수 있습니다. 또한 openclaw security audit과 openclaw doctor는 jq처럼 동작 범위가 넓은 바이너리를 safeBins에 명시적으로 다시 추가할 때도 경고를 보냅니다. 인터프리터를 명시적으로 화이트리스트에 추가했다면, tools.exec.strictInlineEval을 활성화해서 인라인 코드 평가 형식은 매번 새로 승인을 받도록 하세요.

전체 정책 세부 사항과 예시는 Exec approvals 및 Safe bins versus allowlist를 확인해 보세요.

예시

포그라운드 실행:

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

제출 (CR만 전송):

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

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

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

apply_patch

apply_patch는 구조화된 다중 파일 편집을 위한 exec의 하위 도구입니다. OpenAI 및 OpenAI Codex 모델에서는 기본적으로 활성화되어 있어요. 이 기능을 끄거나 특정 모델로 제한하고 싶을 때만 설정을 사용하세요.

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