OpenClaw 업그레이드나 설정 변경 직후 Telegram/Slack에서는 대화가 되는데 exec·read·write·browser를 쓸 수 없거나, Agent가 도구 호출 텍스트만 출력하고 실행하지 않는 경우, 본 글은 다음을 정리합니다. ①세 가지 증상군에서 어느 층을 먼저 볼지; ② tools.profile 4값 대조와 tools.deny/agent 오버라이드 확인 순서; ③6단계 재현 가능 런북과 검증 사다리. Gateway 무응답·모델 오류 글과 보완 관계이며, 그 글은 채널·모델, 본 글은 도구 allowlist 계약을 다룹니다.
tools.profile이 messaging/minimal에 머무름: 업그레이드나 마법사 기본값으로 도구 면이 좁아져 「대화는 매끄러운데 exec만 not found」가 됩니다.tools.deny 오설정: 컴플라이언스용으로 exec/browser를 임시 deny했으나 변경 티켓 종료 후에도 규칙이 남습니다.agents.list[].tools.profile이 전역을 덮어씀: 전역은 고쳤다고 생각해도 실제 agent는 더 좁은 profile을 상속합니다.OpenClaw 도구 면은 「설치하면 전부 사용」이 아니라 전역 profile → deny 목록 → agent급 오버라이드 3층이 겹쳐 유효 집합이 정해집니다. 2026년 상류 문서는 tools.profile을 기준 allowlist로 정의합니다. minimal은 세션 상태류만, messaging은 채널·session 중심, coding은 파일시스템·런타임·web·sessions·memory 등 엔지니어링용, full은 profile 층에서 추가 제한하지 않습니다. 많은 팀이 업그레이드 후 처음 밟는 것은 Gateway 장애가 아니라 계약이 「묵시적 전 허용」에서 「명시적 허용」으로 조여진 것이며, 변경 티켓에 「restart·최소 프로브」가 없는 경우입니다. on-call이 채팅에서 같은 프롬프트를 반복해 릴리스 창을 통째로 잃습니다.
Gateway를 절전하는 개인 노트북에서 돌리면 「설정은 바꿨는데 launchd/컨테이너가 reload되지 않음」이라는 겉보기 실패가 겹칩니다. 권위 Gateway를 상시 전원·전용·티켓으로 추적 가능한 원격 Mac에 두고 SSH 로컬 포워딩으로 Control UI에 접근하면 「설정 변경 면」과 「터미널 잡음 면」을 분리할 수 있습니다. 아래 검증 사다리는 Gateway 측에서 수락할 것을 강조합니다. CLI가 success만 출력한 것으로는 부족합니다.
| 보이는 증상 | 우선 의심 층 | 첫 조치(실행 가능) |
|---|---|---|
| 응답은 있는데 exec/read가 tool not found | tools.profile이 좁거나 agent 오버라이드 |
유효 profile보내기; 필요 시 openclaw config set tools.profile coding; gateway restart |
| 특정 도구만 항상 불가, 나머지는 정상 | tools.deny |
deny 규칙 전문 검색; 공식 tools 문서와 대조해 오 deny 제거 |
| 특정 agent만 동작 안 함 | agents.list[].tools.profile |
해당 agent profile을 전역과 맞춤; 「A를 고치고 B로 검증」 회피 |
| 메시지에 JSON 형태 tool call 텍스트 | 모델 tool-calling 능력 | function calling을 안정 처리하는 모델로 전환; 병렬 도구 수를 줄여 A/B |
| 채널이 완전 무응답 | 채널/Token/모델 라우팅 | Gateway 무응답 전용 글로 이동; 본 글 절차는 보류 |
tools.profile 4값 대조: coding과 full 선택실무에서는 대부분의 자동화·개발 Agent는 coding이 적절합니다. 파일 읽기/쓰기, 셸, web fetch, session, memory 등을 포함하고 full보다 보안 검토가 쉽습니다. full은 profile 층에서 더 자르지 않을 필요가 있고, 감사·최소 노출 체계가 갖춰진 경우에만 검토하십시오. messaging은 순수 전달·고객 지원용, minimal은 상태만 필요하고 파일시스템을 건드리지 않을 때입니다. Agents/Skills/memory_search 튜닝과 함께 볼 때는 「도구 면」과 「컨텍스트 상한」을 같은 변경 티켓에 넣으십시오. 그렇지 않으면 memory는 검색되지만 read가 profile에 막히는 반쪽 설정이 됩니다.
메커니즘상 Gateway는 세션 시작 시 설정에서 유효 도구 등록표를 해석해 모델에 tool-calling을 넘깁니다. 등록표에 exec가 없으면 모델이 호출하려 해도 런타임에서 거부되거나, 약한 모델은 의도를 텍스트로 출력합니다. 커뮤니티의 「업그레이드 후 갑자기 채팅만」 글 대부분은 결국 profile이나 deny에 도달하지만, 분기 순서는 여전히 무응답을 먼저 제외한 뒤 본 글로 들어가는 것이 시간을 절약합니다.
| profile 값 | 전형적으로 가능한 능력(개요) | 적합 시나리오 |
|---|---|---|
| minimal | session_status 등 경량 상태 |
읽기 모니터링만. 파일·shell 미접촉 |
| messaging | 채널·session 관리류 도구 | 전달·고객 지원만. 코드·파일 작업 없음 |
| coding | filesystem, runtime, web, sessions, memory, media 등 | 개발 자동화·스크립트·저장소 작업(권장 기본값) |
| full | profile 층에서 추가 잘라내기 없음 | 감사·최소 노출이 갖춰진 프로덕션 예외 |
참고: tools.profile 변경 후에는 Gateway 재시작이 필수입니다(로컬 daemon, Docker compose, 원격 launchd 유닛). openclaw doctor만으로는 실행 중 프로세스가 새 allowlist를 읽었다고 보장할 수 없습니다. Docker 경로는 프로덕션 런북의 reload 순서를 따르십시오.
tools.deny·agent 오버라이드: 3층 확인 순서on-call이 층을 오가지 않도록 다음 순서를 고정하는 것을 권합니다. ①가동 중 Gateway가 보고하는 유효 profile(또는 동등 export) 확인 → ② tools.deny 확인 → ③ 대상 agent의 agents.list[].tools.profile → ④마지막에 전역 config 변경. 직전에 릴리스 채널 업그레이드를 했다면 변경 티켓에 「기본 profile 마이그레이션 포함 여부」를 먼저 확인하십시오. 이미지 롤백이 필요하면 불량 릴리스 롤백을 사용하고 profile 시행착오를 무한히 반복하지 마십시오.
멀티 agent에서는 「전역은 coding인데 프로덕션 bot은 구 항목의 messaging」 사고가 흔합니다. 티켓에 검증한 agent 이름과 트리거한 채널을 필수로 넣고, CLI 직접 대화와 Telegram/Slack 각각에서 최소 프로브를 실행하십시오. 라우팅이 다를 수 있습니다. 보안팀 임시 deny에는 만료 시각·담당자를 기록하십시오. 3개월 뒤 browser 금지 이유를 아무도 기억하지 못해 처음부터 다시 조사하게 됩니다.
openclaw --version, 현재 tools.profile, agent 목록 요약, 실패 대화의 request id(있으면)를 저장합니다.coding. 변경 전 티켓에 이유와 롤백 값을 적습니다.openclaw gateway restart; Docker는 docker compose restart 등으로 권위 Gateway는 하나로 맞춥니다.openclaw doctor → openclaw gateway status → 비파괴 최소 프로브(읽기 전용 read 또는 작은 exec echo) → 채널 연결 시 channels status --probe.# 증거·정렬(필드는 환경에 맞게 조정) openclaw --version openclaw config get tools.profile 2>/dev/null || true # 흔한 복구 경로(변경 전 설정 백업) openclaw config set tools.profile coding openclaw gateway restart openclaw doctor openclaw gateway status # 최소 프로브: Control UI 또는 CLI에서 읽기 전용 read / 무해 exec 1회
tools.profile/deny/agent 오버라이드인 비율. 2주 연속 40% 초과면 업그레이드 체크리스트에 profile 수락이 빠진 것입니다.이 지표는 「채팅 가능」과 「도구 실행 가능」을 관측 가능한 이벤트로 나누기 위함입니다. 6개 리전 노드에서 빌드와 Agent를 동시에 돌릴 때는 디스크·CPU 피크를 피한 변경 창을 쓰십시오. 그렇지 않으면 프로브 실패가 profile 문제로 보입니다.
FinOps 관점에서는 「OpenClaw 시험」용 단기 대여를 했는데 profile 기본값 때문에 마지막 날까지 도구 면을 몰라 헛비용이 납니다. POC 1일차에 목표 profile, 빈 deny, agent 오버라이드 정책을 수락 목록에 넣고 POC 확장 KPI 매트릭스의 「첫날 그린 빌드/그린 Gateway」와 나란히 두십시오. Agent를 채팅 장난감만으로 수락하지 않는 것이 중요합니다.
채팅에서 프롬프트만 바꾸거나 restart 없이 설정을 반복하는 대안은 가끔 맞아도 감사할 수 없고, 두 번째 머신에서 재현할 수 없으며, 보안팀에 「그때 Agent가 무엇을 할 수 있었는지」 설명하기 어렵습니다. 반대로 상시 전원·전용·변경을 티켓화할 수 있는 원격 Mac의 Gateway에 문서화된 profile 기본값과 검증 사다리를 두면 MTTR은 「밤새 프롬프트 시도」에서 「10분 내 재현 가능」으로 줄이기 쉽습니다.
노트북에서 최신을 쫓아도 절전으로 인한 Gateway 유사 정지, 덮개 닫은 뒤 reload 미반영, 팀별 구두 profile 등 숨은 비용을 감수해야 합니다. 7×24·감사 가능·CI 변경 리듬과 맞춘 OpenClaw 프로덕션 Agent에는 MACCOME Mac mini(M4/M4 Pro)와 6개 리전 탄력 대여가 개인 기기 전원 정책과 싸우는 것보다 총소유비용이 낮은 경우가 많습니다. 공개 티어는 다지역·대여 가이드를 보고 SSH 포워딩 런북으로 토폴로지를 이으십시오.
자주 묻는 질문
업그레이드 후 tools.profile을 반드시 full로 바꿔야 합니까?
필수는 아닙니다. coding으로 대부분의 엔지니어링 자동화를 커버합니다. full은 감사와 함께 검토하십시오. 변경 후 restart와 최소 프로브가 필수입니다. 프로덕션 전용 호스트 계획은 대여 가격과 고객 센터를 참고하십시오.
본 글과 「Gateway 무응답」 글이 겹치지 않습니까?
무응답 전용 글은 채널·모델·핸드셰이크를 다룹니다. 본 글은 allowlist 3층만 다룹니다. 완전 무응답이면 전용 글을 먼저 보십시오. tool not found만이면 본 글 런북을 따르십시오.
profile을 바꿔도 tool call 텍스트만 나오면?
먼저 function calling을 안정 처리하는 모델로 A/B 하십시오. 특정 채널만이면 채널 전용 글을 확인합니다. 반쪽 업그레이드가 아님이 확인된 뒤 버전 롤백을 검토하십시오.