Troubleshooting

Every error we hit, with its exact fix. This page is the real value of the guide.

TL;DR: Validate JSON before every restart. Run openclaw doctor after every config change. The config schema is strict — keys that look valid often aren't. When the AI outputs raw JSON instead of running commands, switch models immediately.

The golden rule

Before anything else, when something breaks:

cat ~/.openclaw/openclaw.json | python3 -m json.tool openclaw doctor

If JSON is invalid: fix before restarting. If doctor finds issues: run openclaw doctor --fix.

Error 1: Double messages in Telegram

Error: Every AI response appears twice in Telegram chat.

Root cause: streaming: "partial" sends both the intermediate and final response to Telegram.

Fix: Change streaming setting in the telegram channel config:

"streaming": "off"

This is one of the first things you hit. The default streaming setting causes every reply to appear twice — once as an intermediate and once as the final. Fix on Day 1.

Error 2: Raw JSON in chat instead of execution

Error: When you ask the AI to run a shell command, it outputs raw JSON like {"tool": "exec", "command": "echo hello", ...} in the chat instead of running the command.

Root cause: Gemini model bug. Gemini doesn't integrate cleanly with OpenClaw's exec pipeline.

Fix: Switch to Claude Sonnet immediately:

"model": { "primary": "anthropic/claude-sonnet-4-6" }

Then restart the gateway. This fixes it instantly. Don't spend days debugging permissions when the real problem is the model.

Error 3: Telegram exec approvals not enabled

Error: ❌ Telegram exec approvals are not enabled for this bot account

Root cause: Telegram exec approvals are a SEPARATE config from the main exec settings. They are not enabled by default.

Fix:

openclaw approvals security set --agent main --level full

This took two days to find. Run it on Day 1 after setting up Telegram.

Error 4: exec denied — allowlist miss with redirections

Error: exec denied: allowlist miss when trying to use > or >> in shell commands.

Root cause: Redirections (>, >>) are permanently unsupported in OpenClaw's allowlist mode, regardless of security settings. This is by design, not a bug.

Fix: Use tee instead:

# BROKEN — never works echo "text" >> file.txt # WORKS — use this instead echo "text" | tee -a file.txt # Overwrite (not append) echo "text" | tee file.txt

Three days of debugging across three AI models to find this one.

Error 5: Unrecognized keys in tools.exec

Error: tools.exec: Unrecognized keys: "allowOperators", "shell", "cwd" (or any of these individually)

Root cause: These keys don't exist in OpenClaw's schema. The documentation may suggest them, but they were never valid.

Fix: Remove them from your config. The valid keys for tools.exec are:

"exec": { "host": "gateway", "security": "full", "ask": "off", "pathPrepend": ["/opt/homebrew/bin", "/usr/local/bin"] }

Do not add allowOperators, shell, cwd, or autoApprove to any tools section.

Error 6: execApprovals invalid in telegram block

Error: channels.telegram.execApprovals: Invalid input or schema validation error mentioning execApprovals

Root cause: execApprovals is not a valid key inside the telegram channel block. It belongs in a separate location (or is set via CLI).

Fix: Remove execApprovals from the telegram channel block entirely. Configure exec approvals via CLI:

openclaw approvals security set --agent main --level full

Error 7: hooks.external not supported

Error: hooks.external: Unrecognized key on gateway startup

Root cause: External hooks are not supported in the current version of OpenClaw. The documentation may reference them, but they don't work.

Fix: Remove the hooks.external block from your config entirely. Use only hooks.internal:

"hooks": { "internal": { "enabled": true, "entries": { "boot-md": { "enabled": true }, "bootstrap-extra-files": { "enabled": true }, "command-logger": { "enabled": true }, "session-memory": { "enabled": true } } } }

Error 8: MEMORY.md duplication causing edit failures

Error: Edit tool throws an error like "the text appears more than once in the file" when trying to update MEMORY.md.

Root cause: Multiple edits over time have created duplicate sections in MEMORY.md.

Fix: Use write to overwrite the file completely rather than patching it:

# From Telegram, tell the AI: "Read MEMORY.md. Deduplicate it — merge any duplicate sections, keeping the most recent/complete version of each. Then write the clean version back to MEMORY.md as a complete overwrite, not an edit."

Do not use the edit tool on heavily-edited MEMORY.md files. Use write to overwrite completely.

Error 9: Config invalid after any change

Error: Gateway fails to start or throws schema errors after editing openclaw.json.

Root cause: JSON syntax error or invalid key introduced during editing.

Fix: Always run this sequence after any config change:

cat ~/.openclaw/openclaw.json | python3 -m json.tool && openclaw gateway restart

If python3 reports a JSON error: find and fix it before restarting. Common mistakes:

Run openclaw doctor --fix after restart to catch schema-level issues.

Config validation checklist

Before restarting the gateway, check:

  1. JSON is valid: cat ~/.openclaw/openclaw.json | python3 -m json.tool
  2. No unrecognised keys (see error 5 above for the common ones)
  3. No execApprovals in the telegram block
  4. No hooks.external block
  5. streaming: "off" in the telegram block
  6. "bash": true in the commands section
  7. Model ID uses the full path: anthropic/claude-sonnet-4-6