Gateway logging

Gateway logging 문서는 OpenClaw 공식 문서(gateway/logging)를 한국어로 정리한 가이드입니다. Logging surfaces, file logs, WS log styles, and console formatting 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Logging surfaces, file logs, WS log styles, and console formatting

한국어 가이드 범위: gateway/logging 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Logging
File-based logger
Verbose vs. log levels
Console capture
Redaction
Gateway WebSocket logs
WS log style
optimized (only errors/slow)
show all WS traffic (paired)
show all WS traffic (full meta)
Console formatting (subsystem logging)
관련 문서

상세 내용

Logging

For a user-facing overview (CLI + Control UI + config), see /logging.

주요 항목:

Console output - what you see in the terminal / Debug UI.
File logs - JSON lines written by the gateway logger.

agent model: openai/gpt-5.6-sol (thinking=medium, fast=on)

File-based logger

Talk, realtime voice, and managed-room code paths use the shared file logger for bounded lifecycle records intended for operational debugging and OTLP log export. Transcript text, audio payloads, turn ids, call ids, and provider item ids are never copied into the log record.

주요 항목:

Default rolling log files are under /tmp/openclaw/ (one file per day), dated by the gateway host's local timezone. The default profile uses openclaw-YYYY-MM-DD.log; named profiles use openclaw-<profile>-YYYY-MM-DD.log (예를 들어, openclaw-dev-YYYY-MM-DD.log). If that directory is unsafe or unwritable (wrong owner, world-writable, a symlink), OpenClaw falls back to a user-scoped os.tmpdir()/openclaw-<uid> path instead; on Windows it always uses that OS-tmpdir fallback.
Active log files rotate at logging.maxFileBytes (default: 100 MB), keeping up to five numbered archives (.1 through .5) and continuing to write a fresh active file.
Configure the log file path and level via ~/.openclaw/openclaw.json: logging.file, logging.level.
The file format is one JSON object per line.

openclaw logs --follow

Verbose vs. log levels

주요 항목:

File logs are controlled exclusively by logging.level.
--verbose only affects console verbosity (and WS log style) - it does not raise the file log level.
To capture verbose-only details in file logs, set logging.level to debug or trace.
Trace logging also includes diagnostic timing summaries for selected hot paths, such as plugin tool factory preparation. See /tools/plugin#slow-plugin-tool-setup.

Console capture

The CLI captures console.log/info/warn/error/debug/trace, writes them to file logs, and still prints to stdout/stderr.

주요 항목:

logging.consoleLevel (default info)
logging.consoleStyle (pretty | compact | json; defaults to pretty on a TTY, compact otherwise)

Redaction

OpenClaw masks sensitive tokens before log or transcript output leaves the process. This redaction policy applies at console, file-log, OTLP log-record, and session transcript text sinks, so matching secret values are masked before JSONL lines or messages are written to disk.

주요 항목:

Sensitive-value redaction is always enabled.
logging.redactPatterns: array of regex strings (overrides defaults)
Use raw regex strings (auto gi), or /pattern/flags for custom flags.
Matches are masked keeping the first 6 + last 4 chars (values >= 18 chars); shorter values become ***.
Defaults cover common key assignments, CLI flags, JSON fields, bearer headers, PEM blocks, popular vendor token prefixes, and payment credential field names (card number, CVC/CVV, shared payment token, payment credential).

Gateway WebSocket logs

The gateway prints WebSocket protocol logs in two modes:

주요 항목:

Normal mode (no --verbose): only "interesting" RPC results print - errors (ok=false), slow calls (default threshold: >= 50ms), and parse errors.
Verbose mode (--verbose): prints all WS request/response traffic.

WS log style

openclaw gateway supports a per-gateway style switch:

주요 항목:

--ws-log auto (default): normal mode is optimized; verbose mode uses compact output.
--ws-log compact: compact output (paired request/response) when verbose.
--ws-log full: full per-frame output when verbose.
--compact: alias for --ws-log compact.

optimized (only errors/slow)

openclaw gateway

show all WS traffic (paired)

openclaw gateway --verbose --ws-log compact

show all WS traffic (full meta)

openclaw gateway --verbose --ws-log full ```

Console formatting (subsystem logging)

The console formatter is TTY-aware and prints consistent, prefixed lines. Subsystem loggers keep output grouped and scannable:

주요 항목:

Subsystem prefixes on every line (e.g. [gateway], [canvas], [tailscale]).
Subsystem colors (stable per subsystem, hashed from the name) plus level coloring.
Color when output is a TTY or the environment looks like a rich terminal (TERM/COLORTERM/TERM_PROGRAM); respects NO_COLOR and FORCE_COLOR.
Shortened subsystem prefixes: drops a leading gateway/, channels/, or providers/ segment, then keeps at most the last 2 remaining segments (e.g. channels/turn/kernel displays as turn/kernel). Known channel subsystems (telegram, whatsapp, slack, etc.) always collapse to just the channel name.
Sub-loggers by subsystem (auto prefix + structured field { subsystem }).
logRaw() for QR/UX output (no prefix, no formatting).
Console styles: pretty | compact | json.
Console log level is separate from file log level (file keeps full detail when logging.level is debug/trace).
WhatsApp message bodies log at debug (use --verbose to see them).

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/logging
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

agent model: openai/gpt-5.6-sol (thinking=medium, fast=on)

openclaw logs --follow

# optimized (only errors/slow)
openclaw gateway

# show all WS traffic (paired)
openclaw gateway --verbose --ws-log compact

# show all WS traffic (full meta)
openclaw gateway --verbose --ws-log full

Gateway logging

핵심 요약

Logging surfaces, file logs, WS log styles, and console formatting

한국어 가이드 범위: gateway/logging 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Logging
File-based logger
Verbose vs. log levels
Console capture
Redaction
Gateway WebSocket logs
WS log style
optimized (only errors/slow)
show all WS traffic (paired)
show all WS traffic (full meta)
Console formatting (subsystem logging)
관련 문서

상세 내용

Logging

For a user-facing overview (CLI + Control UI + config), see /logging.

주요 항목:

Console output - what you see in the terminal / Debug UI.
File logs - JSON lines written by the gateway logger.

agent model: openai/gpt-5.6-sol (thinking=medium, fast=on)

File-based logger

주요 항목:

Default rolling log files are under /tmp/openclaw/ (one file per day), dated by the gateway host's local timezone. The default profile uses openclaw-YYYY-MM-DD.log; named profiles use openclaw-<profile>-YYYY-MM-DD.log (예를 들어, openclaw-dev-YYYY-MM-DD.log). If that directory is unsafe or unwritable (wrong owner, world-writable, a symlink), OpenClaw falls back to a user-scoped os.tmpdir()/openclaw-<uid> path instead; on Windows it always uses that OS-tmpdir fallback.
Active log files rotate at logging.maxFileBytes (default: 100 MB), keeping up to five numbered archives (.1 through .5) and continuing to write a fresh active file.
Configure the log file path and level via ~/.openclaw/openclaw.json: logging.file, logging.level.
The file format is one JSON object per line.

openclaw logs --follow

Verbose vs. log levels

주요 항목:

File logs are controlled exclusively by logging.level.
--verbose only affects console verbosity (and WS log style) - it does not raise the file log level.
To capture verbose-only details in file logs, set logging.level to debug or trace.
Trace logging also includes diagnostic timing summaries for selected hot paths, such as plugin tool factory preparation. See /tools/plugin#slow-plugin-tool-setup.

Console capture

The CLI captures console.log/info/warn/error/debug/trace, writes them to file logs, and still prints to stdout/stderr.

주요 항목:

logging.consoleLevel (default info)
logging.consoleStyle (pretty | compact | json; defaults to pretty on a TTY, compact otherwise)

Redaction

주요 항목:

Sensitive-value redaction is always enabled.
logging.redactPatterns: array of regex strings (overrides defaults)
Use raw regex strings (auto gi), or /pattern/flags for custom flags.
Matches are masked keeping the first 6 + last 4 chars (values >= 18 chars); shorter values become ***.
Defaults cover common key assignments, CLI flags, JSON fields, bearer headers, PEM blocks, popular vendor token prefixes, and payment credential field names (card number, CVC/CVV, shared payment token, payment credential).

Gateway WebSocket logs

The gateway prints WebSocket protocol logs in two modes:

주요 항목:

Normal mode (no --verbose): only "interesting" RPC results print - errors (ok=false), slow calls (default threshold: >= 50ms), and parse errors.
Verbose mode (--verbose): prints all WS request/response traffic.

WS log style

openclaw gateway supports a per-gateway style switch:

주요 항목:

--ws-log auto (default): normal mode is optimized; verbose mode uses compact output.
--ws-log compact: compact output (paired request/response) when verbose.
--ws-log full: full per-frame output when verbose.
--compact: alias for --ws-log compact.

optimized (only errors/slow)

openclaw gateway

show all WS traffic (paired)

openclaw gateway --verbose --ws-log compact

show all WS traffic (full meta)

openclaw gateway --verbose --ws-log full ```

Console formatting (subsystem logging)

The console formatter is TTY-aware and prints consistent, prefixed lines. Subsystem loggers keep output grouped and scannable:

주요 항목:

Subsystem prefixes on every line (e.g. [gateway], [canvas], [tailscale]).
Subsystem colors (stable per subsystem, hashed from the name) plus level coloring.
Color when output is a TTY or the environment looks like a rich terminal (TERM/COLORTERM/TERM_PROGRAM); respects NO_COLOR and FORCE_COLOR.
Shortened subsystem prefixes: drops a leading gateway/, channels/, or providers/ segment, then keeps at most the last 2 remaining segments (e.g. channels/turn/kernel displays as turn/kernel). Known channel subsystems (telegram, whatsapp, slack, etc.) always collapse to just the channel name.
Sub-loggers by subsystem (auto prefix + structured field { subsystem }).
logRaw() for QR/UX output (no prefix, no formatting).
Console styles: pretty | compact | json.
Console log level is separate from file log level (file keeps full detail when logging.level is debug/trace).
WhatsApp message bodies log at debug (use --verbose to see them).

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/logging
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

agent model: openai/gpt-5.6-sol (thinking=medium, fast=on)

openclaw logs --follow

# optimized (only errors/slow)
openclaw gateway

# show all WS traffic (paired)
openclaw gateway --verbose --ws-log compact

# show all WS traffic (full meta)
openclaw gateway --verbose --ws-log full

Gateway logging

핵심 요약

문서 구성

상세 내용

Logging

File-based logger

Verbose vs. log levels

Console capture

Redaction

Gateway WebSocket logs

WS log style

optimized (only errors/slow)

show all WS traffic (paired)

show all WS traffic (full meta)

Console formatting (subsystem logging)

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Gateway logging

핵심 요약

문서 구성

상세 내용

Logging

File-based logger

Verbose vs. log levels

Console capture

Redaction

Gateway WebSocket logs

WS log style

optimized (only errors/slow)

show all WS traffic (paired)

show all WS traffic (full meta)

Console formatting (subsystem logging)

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드