Exec 도구

워크스페이스에서 셸 명령을 실행합니다. process를 통한 포그라운드 + 백그라운드 실행을 지원합니다. process가 허용되지 않으면 exec는 동기적으로 실행되고 yieldMs/background를 무시합니다. 백그라운드 세션은 에이전트별로 범위가 지정됩니다. process는 동일한 에이전트의 세션만 표시합니다.

매개변수

  • command(필수)
  • workdir(cwd로 기본 설정)
  • 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(문자열): host=node에 대한 노드 ID/이름
  • elevated(bool): elevated 모드 요청(gateway host). elevated가 full로 해결되는 경우에만 security=full이 강제됨

참고:

  • host는 기본적으로 sandbox입니다.
  • 샌드박싱이 꺼져 있으면 elevated가 무시됩니다(exec가 이미 호스트에서 실행됨).
  • gateway/node 승인은 ~/.openclaw/exec-approvals.json으로 제어됩니다.
  • node는 페어링된 노드(컴패니언 앱 또는 헤드리스 노드 호스트)가 필요합니다.
  • 여러 노드를 사용할 수 있는 경우 exec.node 또는 tools.exec.node를 설정하여 하나를 선택하십시오.
  • Windows가 아닌 호스트에서 exec는 설정된 경우 SHELL을 사용합니다. SHELL이 fish인 경우 fish와 호환되지 않는 스크립트를 피하기 위해 PATH의 bash(또는 sh)를 선호하고 둘 다 존재하지 않으면 SHELL로 폴백합니다.
  • 중요: 샌드박싱은 기본적으로 꺼져 있습니다. 샌드박싱이 꺼져 있으면 host=sandbox는 게이트웨이 호스트에서 직접 실행되고(컨테이너 없음) 승인이 필요하지 않습니다. 승인을 요구하려면 host=gateway로 실행하고 exec 승인을 구성하십시오(또는 샌드박싱 활성화).

구성

  • tools.exec.notifyOnExit(기본값: true): true인 경우 백그라운드 exec 세션은 종료 시 시스템 이벤트를 대기열에 추가하고 하트비트를 요청합니다.
  • tools.exec.approvalRunningNoticeMs(기본값: 10000): 승인 게이트 exec가 이보다 오래 실행되면 단일 "running" 알림을 발생시킵니다(0은 비활성화).
  • tools.exec.host(기본값: sandbox)
  • tools.exec.security(샌드박스에 대해 기본값 deny, 설정되지 않은 경우 gateway + node에 대해 allowlist)
  • tools.exec.ask(기본값: on-miss)
  • tools.exec.node(기본값: 설정되지 않음)
  • tools.exec.pathPrepend: exec 실행을 위해 PATH에 앞에 추가할 디렉토리 목록.
  • tools.exec.safeBins: 명시적 허용 목록 항목 없이 실행할 수 있는 stdin 전용 안전 바이너리.

예제:

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

PATH 처리

  • host=gateway: 로그인 셸 PATH를 exec 환경에 병합합니다(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 변수를 통해 프로필 소싱 후 env.PATH를 앞에 추가합니다(셸 보간 없음). tools.exec.pathPrepend도 여기에 적용됩니다.
  • host=node: 전달하는 env 오버라이드만 노드로 전송됩니다. tools.exec.pathPrepend는 exec 호출이 이미 env.PATH를 설정하는 경우에만 적용됩니다. 헤드리스 노드 호스트는 노드 호스트 PATH를 앞에 추가하는 경우에만 PATH를 허용합니다(교체 없음). macOS 노드는 PATH 오버라이드를 완전히 삭제합니다.

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

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 approvals를 참조하십시오.

승인이 필요한 경우 exec 도구는 status: "approval-pending" 및 승인 ID와 함께 즉시 반환됩니다. 승인(또는 거부/시간 초과)되면 Gateway는 시스템 이벤트(Exec finished / Exec denied)를 발생시킵니다. 명령이 tools.exec.approvalRunningNoticeMs 후에도 여전히 실행 중이면 단일 Exec running 알림이 발생합니다.

허용 목록 + safe bin

허용 목록 적용은 해결된 바이너리 경로만 일치합니다(basename 일치 없음). security=allowlist인 경우 셸 명령은 모든 파이프라인 세그먼트가 허용 목록에 있거나 safe bin인 경우에만 자동 허용됩니다. 체이닝(;, &&, ||) 및 리디렉션은 허용 목록 모드에서 거부됩니다.

예제

포그라운드:

{"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의 하위 도구입니다. 명시적으로 활성화하십시오:

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

참고:

  • OpenAI/OpenAI Codex 모델에만 사용 가능합니다.
  • 도구 정책이 여전히 적용됩니다. allow: ["exec"]는 암시적으로 apply_patch를 허용합니다.
  • 구성은 tools.exec.applyPatch 아래에 있습니다.
← 문서로 돌아가기