OpenClaw Field Note Template

中文 | English

Use this template when a durable OpenClaw lesson deserves to be preserved for future operators, other AI systems, or the user.

Title

Use a concrete failure pattern, not a vague category.

Examples:

• OpenClaw Skills Symlink Escape
• OpenClaw Cron Pairing And Operator Scopes
• OpenClaw Provider Endpoint DNS Failures

Template

# <Concrete Issue Title>

[中文](<sibling>.zh.md) | English

## Summary

One short paragraph that says what the problem really was.

## Symptom

- Exact error string, command output, or visible behavior.
- Include a short code block when the literal message matters.

## Trigger Conditions

- What environment or setup made this happen.
- What misleading assumptions made it harder to notice.

## Root Cause

- The actual underlying failure mode.
- Explain why the symptom pointed in the wrong direction if relevant.

## How To Confirm

- The shortest reliable checks.
- Concrete file paths, config keys, or commands.

## Fix

- The minimal fix that actually resolved it.
- Prefer explicit paths, scope names, config fields, or commands.

## Operational Lesson

- What future operators should remember so they do not repeat the mistake.

## Related Pages

- [OpenClaw Field Notes](openclaw-field-notes.md)

Capture Threshold

Write a new field note when most of these are true:

• the issue was reproduced in a real OpenClaw environment
• the root cause was non-obvious
• the fix is likely reusable
• the lesson would otherwise be lost in chat history
• writing it down would save time for another operator

Backfill Rule

If a valuable lesson was discovered in chat but not written at the time, backfill it into wiki/operations/ during the next maintenance pass instead of waiting for the same issue to happen again.