Audit history

기준일: 2026-07-26
공식 기준: Audit history

Audit history 문서는 OpenClaw 공식 문서(gateway/audit)를 한국어로 정리한 가이드입니다. Metadata-only audit history for agent runs, tool actions, and opt-in message lifecycles 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Metadata-only audit history for agent runs, tool actions, and opt-in message lifecycles

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

문서 구성

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

• Audit history
• Record families
• Message lifecycle events
• Conversation-kind classification
• Privacy model
• Coverage and proof limits
• Storage, retention, and migration
• Querying
• 관련 문서

상세 내용

Audit history

The Gateway keeps a bounded, metadata-only audit ledger in the shared OpenClaw state database. It answers operational questions such as "which agent ran, when, and how did it end", "which tool actions did a run execute", and, when message auditing is enabled, "did an accepted inbound message reach dispatch" and "did an outbound message reach a terminal delivery state".

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Record families

Run and tool events are recorded whenever auditing is enabled (the default). Message lifecycle events are opt-in and disabled by default.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Family	Actions	Default
Agent runs	agent.run.started, agent.run.finished	on
Tool actions	tool.action.started, tool.action.finished	on
Messages	message.inbound.processed, message.outbound.finished	off

Message lifecycle events

Set audit.messages to choose what is recorded, then restart the Gateway:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• off (default): no message records.
• direct: only messages in direct conversations.
• all: direct, group, and channel messages.
• Inbound rows are written when an accepted message reaches core dispatch,
• Outbound rows are written when shared durable delivery reaches a

Conversation-kind classification

direct mode is a privacy boundary, so a message is classified as a direct conversation only when destination facts prove it: the sending path declared the destination conversation kind, or the delivery session route names exactly the channel and peer being delivered to. Weaker signals, such as policy state or the originating conversation, can classify a message as group (excluding it from direct collection) but can never claim direct. Messages that cannot be proven direct are classified unknown and are not recorded in direct mode. Channels that do not declare chat types may therefore record fewer rows in direct mode than they do in all mode.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Privacy model

Message rows never store raw platform identifiers. Account, conversation, message, and target identifiers, when correlation is available, are exported only as installation-local keyed pseudonyms (hmac-sha256:v1::):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• The HMAC key is generated on first use, is domain-separated per identifier
• Pseudonyms are stable within one installation, so rows about the same
• This is correlation, not anonymization: anyone with read access to the
• If the key material is missing or corrupt while message rows are retained,

Coverage and proof limits

The ledger is best-effort and deliberately bounded. Treat it as evidence of what was recorded, not as proof of what happened:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Absence of a row proves nothing. Pre-admission inbound drops, sends from
• Writes go through a bounded background worker; worker failure or queue
• Crash-ambiguous outbound sends are recorded as unknown rather than

Storage, retention, and migration

Records live in the shared state database (state/openclaw.sqlite) and are written off the delivery hot path. Queries never return records older than 30 days, and the ledger is capped at 100,000 rows; expired rows are pruned during startup, hourly maintenance, and later writes. Retention maintenance keeps running even when collection is disabled.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Querying

kind, status, direction, channel, time bounds, and cursor paging.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• CLI: openclaw audit with filters for agent, session, run,
• Gateway RPC: audit.activity.list (requires operator.read) returns the

관련 문서

주요 항목:

• Audit records CLI
• Configuration reference
• Gateway protocol
• OpenTelemetry

실습 체크리스트

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

관련 링크

• 공식 원문: gateway/audit
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.