Diagnostics Flags: 필요한 로그만 골라보기

버그를 잡으려고 로그를 켰는데, 수만 줄의 텍스트가 쏟아져서 정작 필요한 정보를 놓친 적 있으시죠? 전체 로그 레벨을 높이면 시스템이 느려지거나 중요한 메시지를 찾기가 더 힘들어지곤 해요. 특정 부분만 콕 집어서 살펴볼 수 있다면 디버깅이 훨씬 수월해질 거예요.

OpenClaw의 Diagnostics Flags를 사용하면 전체 로그 설정을 건드리지 않고도 원하는 곳의 디버그 로그만 선택적으로 활성화할 수 있어요.

필요한 것

• OpenClaw 설정 파일 수정 권한
• 터미널 및 기본 CLI 도구 (ls, tail, rg 등)

빠른 시작

Diagnostics Flags는 대소문자를 구분하지 않으며, 설정 파일이나 환경 변수를 통해 간편하게 켤 수 있어요.

1. Config 파일로 설정하기

config 파일의 diagnostics 섹션에 원하는 플래그를 추가하세요. 와일드카드(*)를 사용하면 하위 항목을 한꺼번에 잡을 수 있어요.

{
  "diagnostics": {
    "flags": ["telegram.http", "gateway.*"]
  }
}

여러 개의 플래그를 동시에 지정할 수도 있습니다. 설정을 변경한 후에는 Gateway를 다시 시작해야 적용돼요.

2. 환경 변수로 즉시 적용하기

일시적으로 로그를 확인해야 할 때는 환경 변수를 사용하는 게 더 빨라요.

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

모든 플래그를 한 번에 비활성화하려면 값을 0으로 설정하세요.

OPENCLAW_DIAGNOSTICS=0

3. 로그 확인 및 필터링하기

로그는 기본적으로 /tmp/openclaw/openclaw-YYYY-MM-DD.log 경로에 JSONL 형식으로 저장돼요. logging.file을 설정했다면 해당 경로를 확인하면 됩니다.

최신 로그 파일을 찾으려면 이 명령어를 써보세요:

ls -t /tmp/openclaw/openclaw-*.log | head -n 1

실시간으로 특정 에러만 필터링해서 보고 싶다면 tail과 rg를 조합하는 것이 좋습니다:

tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"

문제 해결

• 로그가 출력되지 않아요: logging.level이 warn보다 높게(예: error) 설정되어 있는지 확인해 보세요. Diagnostics 로그는 기본값인 info 레벨 이상에서 정상적으로 작동해요.
• 민감 정보가 노출될까 봐 걱정돼요: 걱정 마세요. logging.redactSensitive 설정에 따른 개인정보 마스킹은 Diagnostics 로그에도 동일하게 적용됩니다.

더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

• /logging: 로그 저장소 및 레벨 설정 상세 보기
• /cli/logs: CLI를 이용한 원격 Gateway 로그 확인법