OpenClaw 2026.4.1의 크론 tools 플래그가 동작하지 않는 현상 - 원인 분석과 우회 방법

배경: 3.31에서 exec가 막혔다

3.31 이전까지 OpenClaw의 크론 잡과 에이전트는 exec(셸 명령 실행)을 자유롭게 쓸 수 있었다. 그런데 3.31 릴리즈에서 보안이 대폭 강화됐다. 3.31 릴리즈 노트에서 exec 관련 변경만 추리면 다음과 같다.

• exec approvals에 shell init-file, 인라인 eval(awk, find, xargs, sed 등) 감지 추가
• 에이전트별 'tools.exec' 기본값이 실제로 적용되도록 수정
• ACP의 dangerous-tool 오버라이드를 semantic approval class로 교체
• sandbox 없이 implicit exec가 host=auto로 변경, sandbox 없으면 fail-closed

좀 복잡한데 결과적으로 'tools.exec.ask' 설정이 'on-miss'(기본값)인 상태에서는 크론 잡이 exec를 쓸 때마다 유저의 승인이 필요해졌다. 대화형 세션이면 그때그때 승인하면 되지만, 크론은 무인 자동 실행이다. 매번 승인 요청이 쌓이고 유저가 응답하지 않으면 잡이 실패한다.

 

4.1의 해결책 : --tools 플래그

4.1 릴리즈에서 이 문제의 해결책이 나왔다.

Cron/tools allowlist: add 'openclaw cron --tools' for per-job tool allowlists. (#58504) Thanks @andyk-ms.

'--tools' 플래그는 크론 잡 단위로 "이 잡은 이 도구만 사용 가능"이라고 선언하는 기능이다.

CLI 사용법:

# 새 잡 추가 시
openclaw cron add --tools exec,read,write ...

# 기존 잡 수정 시
openclaw cron edit <job-id> --tools exec

# 도구 제한 해제
openclaw cron edit <job-id> --clear-tools

'--tools'를 설정하면 두 가지가 동시에 일어난다.

• 지정한 도구만 모델에게 전달된다 (나머지는 아예 보이지 않음)
• promptMode가 'minimal'로 강제 전환된다 - 스킬 카탈로그, 리플라이 태그, 하트비트, 메시징, 문서, 메모리 등이 전부 빠진다.

원래 이 기능은 작은 로컬 모델(1~3B 파라미터)이 전체 도구 스키마(~16K 토큰)에 압도당하는 문제(#58435)를 해결하기 위해 만들어졌다. 입력 토큰이 ~16K에서 ~800으로 줄어든다. 하지만 보안 관점에서도 유용하다 - 날씨 확인 크론에 'exec'을 줄 필요가 없으니까.

 

실제 적용 시도

27개 크론 잡에 한꺼번에 적용하는 스크립트를 (에이전트가) 만들어서 실행했다.

# 예시: exec만 필요한 잡
openclaw cron edit abc123 --tools exec

# exec + browser 둘 다 필요한 잡 (광고 수익 집계, 티스토리 발행 등)
openclaw cron edit def456 --tools exec,browser

 

스크립트 코드를 살짝 봤는데 크론 job id를 바꿔가며 for 루프를 돌리는 로직이다. 굳이 코드 전체를 공유하지는 않는다. 이 걸로 끝날 줄 알았는데 스크립트를 실행하자 27개 전부 에러와 함께 실패했다.

참고로 위 대화에서 EliFromTheBarn이 에이전트, Gary가 나다.

 

에러 내용

unexpected property 'toolsAllow' at /patch/payload

CLI가 'toolsAllow' 필드를 gateway API에 보내는데, gateway 스키마가 이 필드를 모른다. 'additionalProperties: false'로 설정돼 있어서 알 수 없는 필드가 들어오면 거부한다.

 

원인 분석

PR #58504에서 '--tools' CLI 플래그와 런타임 필터링 코드는 추가됐지만, gateway API 스키마에 'toolsAllow' 필드를 등록하는 코드가 4.1 릴리즈에 포함되지 않았다.

https://github.com/openclaw/openclaw/pull/58504

feat(cron): add --tools flag for per-job tool allow-list by andyk-ms · Pull Request #58504 · openclaw/openclaw

후속 수정 커밋(80078b2)이 존재한다.

fix(cron): add toolsAllow to API schema + mergeCronPayload + unknown tool warning

Fixes three issues from #58504 review:
1. cron.update API schema rejects toolsAllow (additionalProperties: false)
2. mergeCronPayload silently drops toolsAllow on cron edit
3. No warning when --tools contains unknown tool names

이 커밋은 main 브랜치에 머지됐지만, 4.1 릴리즈 태그(da64a97) 이후에 들어갔다. 커밋 SHA 'v2026.4.1...80078b2'를 비교하면 ahead 상태다. 정리하자면 아래와 같다.

항목	4.1 포함 여부
'--tools' CLI 플래그	O
런타임 도구 필터링 로직	O
gateway API 스키마 ('toolsAllow')	X
'mergeCronPayload'에서 'toolsAllow' 반영	X
unknown tool name 경고	X

CLI는 있는데 gateway가 안 받는 상태다. 이런 황당한 경우가.. 아무튼 다음 릴리즈(4.2)에서 수정될 예정이다.

 

우회 방법: exec-approvals allowlist

'--tools'를 못 쓰는 동안에도 크론 exec 승인 문제를 해결하는 방법이 있다. 'openclaw approvals allowlist'로 바이너리 단위 승인을 등록하면, 해당 바이너리를 사용하는 명령은 실행 승인 없이 돌아간다.

# (멀티 에이전트 환경이라면) 에이전트별로 사용하는 바이너리를 등록
openclaw approvals allowlist add --gateway --agent main "/opt/homebrew/bin/python3"
openclaw approvals allowlist add --gateway --agent main "/opt/homebrew/bin/node"
openclaw approvals allowlist add --gateway --agent main "/bin/bash"
openclaw approvals allowlist add --gateway --agent main "/usr/bin/curl"

핵심은 '--gateway' 플래그다. 이게 없으면 로컬 파일에만 기록되고 게이트웨이 프로세스에 반영이 안 된다.

'--tools'와의 차이

항목	'--tools' (크론 잡 단위)	allowlist (에이전트 단위)
적용 범위	특정 크론 잡만	해당 에이전트의 모든 실행
도구 제한	지정한 도구만 모델에게 노출	도구 노출은 그대로, 실행 승인만 스킵
토큰 절감	O (promptMode minimal)	X
보안 세분화	O (잡별 제어)	X (에이전트 전체)

'--tools'가 보안/효율 면에서 더 낫지만, 4.1에서 안 되니까 allowlist로 우회하는 수밖에 없다.

주의: 'cd &&' 패턴

우리팀에서 발생한 이슈다. 크론 페이로드에서 'cd /some/path && python3 script.py' 같은 패턴을 쓰면 allowlist 매칭이 실패한다. 'cd'는 shell builtin이라 바이너리 경로가 없기 때문이다. 해결법은 exec 도구의 'workdir' 파라미터를 사용하거나, 스크립트를 절대경로로 직접 호출하는 것이다.

# X 안 됨
cd /path/to/scripts && python3 ingest.py

# O 됨
/opt/homebrew/bin/python3 /path/to/scripts/ingest.py

 

적용 결과

allowlist 우회 방법을 적용한 후, 크론 잡이 승인 없이 정상 실행되고 있다. 아래는 'OpenRouter 잔액 확인'이라는 크론의 실제 실행 결과다.

exec 승인 없이 python3 스크립트가 실행됐고, 결과가 Telegram 채널로 정상 발송됐다.

 

정리

• 3.31에서 exec 보안이 강화되면서 크론 잡의 exec 실행에 매번 승인이 필요해졌다
• 4.1에서 '--tools' 플래그가 추가됐지만, gateway 스키마 누락으로 실제 동작하지 않는다
• 'unexpected property toolsAllow' 에러가 나면 이 버그 때문이다.
• main에 수정 커밋이 머지돼 있으므로 2026.4.2에서 정상 동작할 예정
• 그전까지는 'openclaw approvals allowlist add --gateway'로 우회 가능

 

참고 링크

• PR #58504: feat(cron): add --tools flag for per-job tool allow-list https://github.com/openclaw/openclaw/pull/58504
• Issue #58435: Per-session tool allow-list for cron jobs
  https://github.com/openclaw/openclaw/issues/58435
• 후속 수정 커밋: fix(cron): add toolsAllow to API schema
  https://github.com/andyk-ms/openclaw/commit/80078b28aaa09cce6e257f9c666a3418a011ae64
• 3.31 릴리즈 노트
  https://github.com/openclaw/openclaw/releases/tag/v2026.3.31
• 4.1 릴리즈 노트
  https://github.com/openclaw/openclaw/releases/tag/v2026.4.1

Release openclaw 2026.4.1 · openclaw/openclaw

끝.