Do not confuse these two types of providers!

Common error:
CODEBLOCK9

Solution:

1. 1. Check if provider name matches openclaw.json models.providers
2. Verify API key is configured correctly
3. Check auth-profiles.json for agent-specific configuration
4. Restart OpenClaw Gateway after configuration changes

⚠️ IMPORTANT: Never reuse credentials from main agent!

Error recovery:

• - If openclaw agents add fails: Restores from backup and checks syntax
• If auth fails: Verify credentials in auth-profiles.json
• If binding fails: Check channel permissions and network connectivity
• If backup fails: Check write permissions on ~/.openclaw/ directory
• If main agent stops responding: Immediately restore from backup and restart OpenClaw

Common errors and solutions:

Error 1: "No API key found for provider 'provider-name'"

Causes:

• - Provider name doesn't match any configured provider in openclaw.json
• Typo in provider name
• Provider not added to models.providers

Solutions:

1. 1. Check provider name in openclaw.json:

   cat ~/.openclaw/openclaw.json | grep -A 10 "providers"
   

1. 2. Verify provider name spelling (case-sensitive)
2. Add provider to models.providers if needed
3. Restart OpenClaw Gateway after configuration changes

Error 2: "Agent failed before reply"

Causes:

• - Agent configuration is invalid
• Workspace files are missing or corrupted
• Model configuration is incorrect

Solutions:

1. 1. Verify workspace files exist:

   ls -la /path/to/workspace/
   

1. 2. Check agent configuration:

   openclaw agents list
   

1. 3. Test agent loading:

   openclaw agents test <agent-name>
   

1. 4. Check OpenClaw logs:

Error 3: "Missing required parameter: path (path or file_path)"

Causes:

• - Using wrong parameter name in write tool
• Parameter format error in tool call

Solutions:

1. 1. Use correct parameter name: file_path instead of INLINECODE19
2. Verify tool call syntax:

   write:
     file_path: /path/to/file.md
     content: "content here"
   

1. 3. Check tool documentation for correct parameters

Error 4: "Could not find exact text in file"

Causes:

• - Using edit tool with incorrect oldText
• Whitespace differences (spaces vs tabs)
• File already modified by another process

Solutions:

1. 1. Re-read file to get exact content:

   read /path/to/file.md
   

1. 2. Use unique markers for large sections:

   <!-- SECTION_START -->
   [content]
   <!-- SECTION_END -->
   

1. 3. Match whitespace exactly (copy from file read)
2. Use smaller oldText for more precise matching

Phase 2.6 - Verify configuration

Verification steps:

CODEBLOCK18

Success criteria:

• - Agent appears in openclaw agents list output
• All required files exist (IDENTITY.md, SOUL.md, AGENTS.md, USER.md)
• No syntax errors in configuration files
• Agent can be loaded without errors

If verification fails:

1. 1. Check file permissions
2. Validate JSON/YAML syntax in configuration files
3. Review error messages from INLINECODE21
4. Restore from backup if necessary

Error recovery:

• - If agent not in list: Check openclaw.json syntax, re-run Phase 2.5
• If files missing: Re-run Phase 2 with corrected paths
• If load test fails: Check file syntax, verify template content matches OpenClaw specs

Phase 3 - Guardrails checklist

Ensure the generated agent includes:

• - Explicit ask-before-destructive rule.
• Explicit ask-before-outbound-messages rule.
• Stop-on-CLI-usage-error rule.
• Max-iteration / loop breaker guidance.
• Group chat etiquette.
• Sub-agent note: essential rules live in AGENTS.md.

Error recovery:

• - If guardrails are missing: Add them to AGENTS.md or SOUL.md
• If guardrails are too restrictive: Ask user for clarification on desired autonomy level

Phase 4 - Acceptance tests (fast)

Provide 5-10 short scenario prompts to validate behavior, e.g.:

• - "Draft but do not send a message to X; ask me before sending."
• "Summarize current workspace status without revealing secrets."
• "You hit an unknown flag error; show how you recover using --help."
• "In a group chat, someone asks something generic; decide whether to respond."

Error recovery:

• - If agent fails acceptance tests: Review guardrails, adjust autonomy level, verify template content
• If tests are too strict: Adjust test scenarios to match intended behavior

Phase 8 - Automated testing (optional)

Automated test commands:

CODEBLOCK19

Test script example:

CODEBLOCK20

Error recovery:

• - If automated tests fail: Review error messages, check file syntax, verify configuration
• If test script fails: Check script permissions, verify paths are correct

Optional: systemd service configuration

For production deployments, the agent can run as a systemd service:

Service file example:

CODEBLOCK21

Enable and start service:

CODEBLOCK22

Error recovery:

• - If service fails to start: Check journalctl logs, verify file paths, check user permissions
• If service crashes: Check OpenClaw logs, verify agent configuration, restart service
• If service wont enable: Check systemd configuration syntax, verify systemd is running

Workflow: iterate on an existing agent

When improving an existing agent, ask:

1) What are the top 3 failure modes you have seen? (loops, overreach, verbosity, etc.)
2) What autonomy changes do you want?
3) Any new safety boundaries?
4) Any changes to heartbeat behavior?

Then propose targeted diffs to:

• - SOUL.md (persona/tone/boundaries)
• INLINECODE24 (operating rules + memory + delegation)
• INLINECODE25 (small checklist)

Keep changes minimal and surgical.

Error recovery:

• - If diff application fails: Check file permissions, verify file exists, retry with backup
• If changes break agent behavior: Restore from git or backup, review changes
• If user rejects changes: Ask for clarification, propose alternative modifications