Openclaw logs every agent action to local JSONL files by default, but local logs fail three of the five SOC 2 Common Criteria related to monitoring. The common findings: deletable session transcripts, missing centralized collection, and zero alerting on privilege escalation. These are gaps that should be closed at deployment time, not discovered during a pre-audit readiness review.
This guide covers the full audit logging stack for Openclaw: enabling structured logging, shipping logs to your SIEM, configuring retention policies, mapping controls to SOC 2 and ISO 27001, and setting up alerts that catch sensitive operations before your auditor does.
What Openclaw Logs by Default
Before adding compliance layers, understand what Openclaw already captures. Three log sources exist out of the box:
Session transcripts at ~/.openclaw/agents/<agentId>/sessions/*.jsonl record every conversation turn, tool invocation, and agent response. Each line is a JSON object with a timestamp, role, content, and tool call metadata. These are the most valuable audit artifacts because they capture the full chain of agent reasoning and action.
Gateway logs at /tmp/openclaw/openclaw-YYYY-MM-DD.log capture HTTP requests, authentication events, and gateway-level errors. By default, these are plain text with timestamps but not structured JSON.
Cron execution logs at ~/.openclaw/agents/<agentId>/cron/runs/ record scheduled task outputs. Each run produces a separate file with the task name, execution time, and output.
The problem is not that Openclaw lacks logging. The problem is that all three sources write to the local filesystem, which means anyone with shell access can modify or delete them. For personal use, that is fine. For a compliance audit, it is disqualifying.
Enabling Structured JSON Logging
The first step toward compliance-grade logging is switching from plain text to structured JSON output. Structured logs are parseable by every SIEM platform and make field-level queries possible.
Configure the logging section in your Openclaw agent config (~/.openclaw/agents/<agentId>/agent/config.json5):
{
logging: {
format: "json", // structured JSON instead of plain text
level: "info", // info captures actions; debug is too noisy for audit
file: "/var/log/openclaw/openclaw.log", // move out of /tmp for persistence
redactSensitive: "tools", // redact sensitive data from tool outputs
redactPatterns: [
"sk-[a-zA-Z0-9]{20,}", // OpenAI API keys
"sk-ant-[a-zA-Z0-9]{20,}",// Anthropic API keys
"ghp_[a-zA-Z0-9]{36}", // GitHub personal access tokens
"xoxb-[a-zA-Z0-9-]+" // Slack bot tokens
]
}
}
Moving the log file out of /tmp matters. On most Linux distributions, /tmp is cleared on reboot via tmpfiles.d, which means your gateway logs vanish after every restart. Point the log path to /var/log/openclaw/ and create the directory with restricted permissions:
sudo mkdir -p /var/log/openclaw
sudo chown 1000:1000 /var/log/openclaw
sudo chmod 750 /var/log/openclaw
The redactPatterns array accepts regex strings that scrub matching values from log output before they hit disk. This prevents API keys and tokens from appearing in your audit trail, which is a SOC 2 CC6.1 requirement for credential protection in log data.
Running the Security Audit
Openclaw ships a built-in security audit command that checks eight categories of configuration risk:
openclaw security audit
The audit examines inbound access policies, tool blast radius, exec approval drift, network exposure, browser control, local disk hygiene, plugin allowlists, and policy drift. For a compliance context, run the deep mode with JSON output so you can store the results:
openclaw security audit --deep --json > /var/log/openclaw/audit-$(date +%F).json
Schedule this as a weekly cron job. Auditors want evidence of recurring security assessments, not a one-time scan from the week before their visit. The --json flag produces machine-readable output that feeds directly into your SIEM or a dashboard like openclaw-mission-control.
Piping results into a Grafana dashboard makes the delta between weekly scans visible, which is more useful than the absolute findings because it shows configuration drift over time.
SIEM Integration
Local logs satisfy nobody’s compliance requirements. You need centralized, tamper-evident collection in a system your operations team already monitors. Here are working configs for the two most common stacks.
ELK Stack with Filebeat
Install Filebeat on the Openclaw host and create /etc/filebeat/inputs.d/openclaw.yml:
- type: log
enabled: true
paths:
- /var/log/openclaw/openclaw.log
- /home/*/.openclaw/agents/*/sessions/*.jsonl
json.keys_under_root: true
json.add_error_key: true
fields:
source: openclaw
environment: production
fields_under_root: true
processors:
- add_host_metadata: ~
- add_cloud_metadata: ~
Point Filebeat’s output to your Elasticsearch cluster:
output.elasticsearch:
hosts: ["https://elasticsearch.internal:9200"]
index: "openclaw-audit-%{+yyyy.MM.dd}"
username: "${ES_USER}"
password: "${ES_PASS}"
ssl.certificate_authorities: ["/etc/filebeat/ca.crt"]
Create an Index Lifecycle Management (ILM) policy in Elasticsearch that enforces your retention window. For SOC 2, one year is the practical minimum. ISO 27001 Annex A.8.17 does not prescribe a specific duration but requires documented retention aligned with your information security policy:
{
"policy": {
"phases": {
"hot": { "actions": { "rollover": { "max_size": "50gb", "max_age": "7d" } } },
"warm": { "min_age": "7d", "actions": { "shrink": { "number_of_shards": 1 } } },
"cold": { "min_age": "90d", "actions": { "freeze": {} } },
"delete": { "min_age": "365d", "actions": { "delete": {} } }
}
}
}
Splunk with Universal Forwarder
Install the Splunk Universal Forwarder and add a monitor stanza to inputs.conf:
[monitor:///var/log/openclaw/openclaw.log]
sourcetype = _json
index = openclaw_audit
disabled = false
[monitor:///home/*/.openclaw/agents/*/sessions/*.jsonl]
sourcetype = _json
index = openclaw_audit
disabled = false
Set the retention policy in indexes.conf on your Splunk indexer:
[openclaw_audit]
frozenTimePeriodInSecs = 31536000
maxTotalDataSizeMB = 500000
That is 365 days of retention and a 500 GB cap. Adjust both based on your log volume. A single active Openclaw agent typically generates 50-100 MB of logs per day, which means one agent produces roughly 18-36 GB per year.
Log Rotation
If you run Openclaw on bare metal or with systemd (not Docker), you need to manage log rotation yourself. Docker users already have the JSON log driver rotation configured in their docker-compose.yml.
Create /etc/logrotate.d/openclaw:
/var/log/openclaw/*.log {
daily
rotate 90
compress
delaycompress
missingok
notifempty
create 0640 openclaw openclaw
postrotate
systemctl reload openclaw-gateway 2>/dev/null || true
endscript
}
This rotates daily, keeps 90 compressed copies (about three months of local history), and sends a reload signal so Openclaw reopens its log file handle. The three-month local window gives you enough buffer for incident response while your SIEM handles long-term retention.
For session JSONL files, implement a separate cleanup cron that archives and removes files older than your retention threshold:
# Archive sessions older than 90 days, then delete originals
find ~/.openclaw/agents/*/sessions/ -name "*.jsonl" -mtime +90 \
-exec gzip {} \;
find ~/.openclaw/agents/*/sessions/ -name "*.jsonl.gz" -mtime +365 \
-delete
Compliance Control Mapping
Having logs is necessary but not sufficient. Auditors want to see that your logging configuration maps to specific controls. Here is how Openclaw audit logging aligns with the frameworks most enterprise teams face.
SOC 2 Trust Services Criteria
| Control | Requirement | Openclaw Implementation |
|---|---|---|
| CC6.1 | Logical access security | Gateway auth mode, RBAC roles, session token validation |
| CC6.2 | Credentials and secrets management | redactSensitive: "tools", custom redactPatterns for API keys |
| CC7.1 | Detection of unauthorized changes | openclaw security audit --deep weekly scans, config drift monitoring |
| CC7.2 | Monitoring of system components | SIEM integration with Filebeat/Splunk forwarder, real-time log collection |
| CC7.3 | Evaluation of detected events | Alerting rules on authentication failures, exec approvals, file writes |
ISO 27001:2022 Annex A
| Control | Requirement | Openclaw Implementation |
|---|---|---|
| A.8.15 | Logging | Structured JSON logging, session transcripts, gateway logs |
| A.8.16 | Monitoring activities | SIEM dashboards, anomaly alerting, weekly security audit scans |
| A.8.17 | Clock synchronization | NTP on host; Openclaw inherits host clock for all timestamps |
| A.5.23 | Information security for cloud services | VPC isolation, encrypted transit (TLS 1.3), egress proxy routing |
This mapping is not exhaustive. Your auditor will want to see these controls documented in your ISMS (Information Security Management System) with evidence of implementation, not just a table in a blog post. But the table gives you a starting checklist for what to configure before the audit engagement begins.
Alerting on Sensitive Operations
Logs without alerting are a post-mortem tool. For compliance monitoring, you need real-time detection of events that indicate risk.
Set up alerts for these patterns in your SIEM:
Authentication anomalies:
source=openclaw event_type=auth AND (status=failed OR status=denied)
| stats count by user, src_ip, span=5m
| where count > 5
Exec approval grants (someone approving shell command execution):
source=openclaw event_type=tool_call AND tool_name="exec"
| stats count by agent_id, user, span=1h
File system writes outside workspace:
source=openclaw event_type=tool_call AND tool_name="file_write"
| where NOT match(path, "^/home/.*/\.openclaw/workspace/")
Configuration changes:
source=openclaw event_type=config_change
| table _time, user, setting, old_value, new_value
Route these alerts to your on-call channel (PagerDuty, Slack, email). The authentication alert catches brute-force attempts against the gateway. The exec alert catches unauthorized shell access through the agent. The file write alert catches data exfiltration attempts. The config change alert catches privilege escalation.
The exec approval alert tends to generate the most actionable findings. Teams often approve broad shell execution policies during development and forget to tighten them before production. A single alert on the first production exec call can catch a policy oversight before an auditor does.
Retention Policies
Different regulations mandate different retention periods. Here is a practical reference:
| Framework | Minimum Retention | Recommended |
|---|---|---|
| SOC 2 | 1 year | 1 year |
| ISO 27001 | Defined by your ISMS | 1-3 years |
| HIPAA | 6 years | 6 years |
| GDPR | Minimum necessary | 1 year (with data minimization) |
| PCI DSS | 1 year (3 months immediately accessible) | 1 year |
| Internal policy | Per your risk assessment | 1-3 years |
Implement retention at two levels: local rotation (logrotate or cron) handles the short-term buffer, and your SIEM ILM policy handles long-term archival and deletion. Never rely on local retention alone for compliance. A disk failure or compromised host can destroy your entire audit trail.
For teams subject to HIPAA, note that Openclaw session transcripts may contain PHI if your agent processes patient data. Encrypt the JSONL files at rest (AES-256 via LUKS or dm-crypt) and ensure your SIEM transit uses TLS 1.3. The enterprise deployment guide covers the encryption setup in detail.
Frequently Asked Questions
Does Openclaw audit logging meet SOC 2 requirements out of the box?
No. Default Openclaw logging writes to local files that can be modified or deleted by anyone with shell access. SOC 2 CC7.2 requires centralized monitoring of system components, which means you need external log collection via a SIEM. Follow the Filebeat or Splunk forwarder setup in this guide to close that gap.
How do I ship Openclaw logs to Splunk or ELK?
Install Filebeat (for ELK) or the Splunk Universal Forwarder on your Openclaw host. Point them at /var/log/openclaw/openclaw.log and the session JSONL directories. Both configs are provided above with index naming, retention policies, and TLS settings.
What format are Openclaw audit logs stored in?
Session transcripts use JSONL (one JSON object per line) with fields for timestamp, role, content, tool call name, tool call arguments, and response. Gateway logs default to plain text but can be switched to structured JSON by setting logging.format: "json" in the agent config.
How long should I retain Openclaw audit logs?
SOC 2 and PCI DSS require one year minimum. HIPAA requires six years. ISO 27001 defers to your documented retention policy. One year is a reasonable baseline for most teams, with three months of immediately accessible hot storage and the remainder in cold/archived tiers.
Can I prevent agents from tampering with their own logs?
Write session transcripts and gateway logs to a directory owned by a different user than the Openclaw process. Ship logs to an external SIEM in near-real-time so that even if local files are deleted, the centralized copy is intact. For stronger guarantees, use write-once storage (S3 Object Lock, WORM-enabled NAS) as the SIEM backend.
What is the openclaw security audit command?
openclaw security audit runs a built-in assessment across eight categories: inbound access, tool blast radius, exec approval drift, network exposure, browser control, disk hygiene, plugin allowlists, and policy drift. Add --deep for thorough scanning, --json for machine-readable output, and --fix to auto-remediate common issues.
How much log storage does a single Openclaw agent generate?
A moderately active agent typically generates 50-100 MB of logs per day across session transcripts and gateway logs combined. That works out to 18-36 GB per year per agent. Plan your SIEM capacity accordingly and set ILM policies to tier older data into cheaper storage.
Key Takeaways
- Move Openclaw logs out of
/tmpto/var/log/openclaw/immediately. Default log paths do not survive reboots on most Linux distributions. - Ship logs to an external SIEM (ELK or Splunk) before your audit, not during it. Local-only logging fails SOC 2 CC7.2 and ISO 27001 A.8.15 requirements.
- Enable
redactSensitive: "tools"and add customredactPatternsfor your API keys. Credentials appearing in audit logs is a finding in every framework. - Schedule weekly
openclaw security audit --deep --jsonscans and store the results. Recurring evidence of security assessments is what auditors look for. - Set up alerting on exec approvals, authentication failures, and file writes outside the workspace. Logs without alerts are only useful for post-incident forensics.
If your team needs help mapping Openclaw deployments to your specific compliance framework or preparing for an upcoming audit, SFAI Labs offers compliance consulting for AI agent infrastructure.
SFAI Labs
