TL;DR: The OpenClaw message
unsupported schema node. use raw mode.comes from the Control UI’s form view, not from the gateway. The form reached a setting it has no control for, but the setting itself is fine, so switch the editor to Raw and edit it as text; on OpenClaw 2026.9.4 the form also lists, by path, every setting it can only edit as text.
Contents
- The Error
- What Unsupported Schema Node Actually Means
- The Whole Family of Raw-Mode Messages
- What to Watch For
- The Fix
- When This Most Often Happens
- Related Messages Elsewhere
- Key Takeaways
- Frequently Asked Questions
The Error
On OpenClaw 2026.9.4 the Control UI shows this exact text beside a setting in form view:
Unsupported schema node. Use Raw mode.
Searches often quote it in lowercase as unsupported schema node. use raw mode., which is the same message. It belongs to a small family of form-view messages, all of which mean the form cannot draw a control and all of which are fixed the same way.
What Unsupported Schema Node Actually Means
OpenClaw’s Control UI edits config in two modes: Form, which draws an input for each setting from the config schema, and Raw, which shows the file as JSON or JSON5 text.
Form view can only draw a control when the schema describes a shape it knows: a string, a number, a true or false switch, a choice from a list, or an object with named fields. When the schema describes something else, such as a union of several shapes, a list whose items are not defined, or a block the gateway passes through untouched, the form has nothing to draw.
The form works out which settings those are before it renders. Any setting on that list that is actually present in your config gets this message in place of an input.
This does not mean the setting is invalid. The gateway validates and loads your config exactly the same way whichever view you edit it in. The message describes the editor, not your config.
The Whole Family of Raw-Mode Messages
These are the related messages in the 2026.9.4 Control UI, and what each one is telling you:
| Message | What triggered it |
|---|---|
Unsupported schema node. Use Raw mode. | A setting the form flagged in advance as one it cannot render. |
Unsupported type: {type}. Use Raw mode. | A field whose declared type is not one the form draws. When the schema declares no type, the name is blank, which is why people search unsupported type: . use raw mode. |
Unsupported array schema. Use Raw mode. | A list that does not define what its items look like. |
Unsupported schema. Use Raw. | A whole section that is not a plain object with named properties. |
Schema unavailable. Use Raw. | The form has no schema to draw from yet. |
Form view can't safely edit some fields | The heading above a list of every setting the form cannot edit, for example 2 settings in this config can only be edited as text: followed by their paths. |
Structured value (SecretRef) - use Raw mode to edit | A secret configured as a reference to an environment variable, file or secret store rather than a plain string. |
Raw mode unavailable for this snapshot | The tooltip on a greyed-out Raw toggle. The page has no config loaded to show, so reload it. |
What to Watch For
On 2026.9.4 the form does not save only the fields it drew. A form save writes back the whole config object it loaded, and the page names the settings it cannot edit so you know where they are. The practical risk is narrower than the message makes it sound: you cannot change those settings from the form.
Two habits still pay off:
- Edit anything the form flags in Raw, and make the whole change there rather than splitting one edit across both views.
- Keep
~/.openclaw/under version control or back it up before config edits, so any change, from any editor, can be compared and rolled back. Auditing OpenClaw deployments for configuration drift like this is part of what we do in an AI Tools Audit.
The Fix
Switch to raw JSON mode before saving.
At the top of the Control UI config editor there is a Form and Raw toggle. Choose Raw, whose tooltip reads “Edit raw JSON/JSON5 config”, and the editor shows the config as text.
Edit the flagged setting there and save. Secrets appear as __OPENCLAW_REDACTED__ in Raw; leave that placeholder alone for any secret you are not changing, and the gateway keeps the real value.
If Raw is greyed out with “Raw mode unavailable for this snapshot”, the page has not loaded a config snapshot yet. Reload the config page and try again. If you are reading config over the API instead and raw comes back null, that is a separate gateway decision, explained in OpenClaw config.get raw null.
For teams sharing one gateway, agree that any setting the form flags is only ever edited in Raw. That keeps one person’s quick form edit from colliding with another’s hand-written block.
When This Most Often Happens
Specific situations where you will see this warning:
Custom agent overrides. Per-agent configuration keys that are not in the global schema show as unsupported. The form editor was designed for the global schema; agent-level overrides are extension keys.
After upgrading OpenClaw. A new version may add config keys the form editor does not yet have form fields for. Run openclaw doctor --fix first to handle any migrations, then expect to see “unsupported schema node” on any newly-introduced advanced keys.
After importing config from another deployment. If you copy a config from a system with a different OpenClaw version or with custom extensions, the importing system may flag many keys as unsupported.
On tools.deny entries. Granular tool restrictions (specific tool name allow/deny lists) commonly trigger the warning depending on the version.
Custom model providers. Adding a custom model provider configuration with specific authentication patterns or non-standard fields will typically trigger the warning.
Custom channel bindings. Per-channel routing rules that go beyond the basic Telegram/Discord setup commonly use keys the form editor does not render.
If your OpenClaw deployment has any of the above, expect the warning. Always edit in raw mode.
Why these particular keys, and not others. The three places this clusters in practice are channel config (especially multiple Telegram entries, which the Control UI cannot render as form fields, which can also surface as Unsupported type: {type}. Use Raw mode.), the apiKey field under models.providers (defined as a schema union rather than a plain string, and the form renderer has no way to draw a union), and passthrough blocks like ulimits that the gateway forwards to the container runtime with no form definition at all.
The pattern behind all three: the form editor can only draw a field whose schema describes exactly one shape. Give it a union, a variable-length list of objects, or a passthrough block, and it has nothing to render. That is why the message says unsupported rather than invalid: it describes the editor, not your config.
So the practical rule: if you are editing channels, providers, or anything you added yourself, go straight to Raw. Check the “can only be edited as text” list at the top of the form first; it names every setting in your config that the form cannot touch.
For teams running OpenClaw across multiple agents and environments, config edits from several people and several editors add up fast. We audit OpenClaw deployments for configuration drift of exactly this kind. See our AI Security & Deployment service for managed-service options, or book a discovery call for a one-time configuration audit.
Related Messages Elsewhere
- If you are calling the gateway’s
config.getmethod andrawisnull, that is not the form editor. See OpenClaw config.get raw null. - If the config fails to load at all, with a message about an unrecognized key, see config validation failed: unrecognized key.
Key Takeaways
Unsupported schema node. Use Raw mode.comes from the Control UI’s form view, not from the gateway, and it does not mean your config is invalid.- The form cannot draw a control for that setting, so edit it in Raw.
- It is one of a family: unsupported type, unsupported array schema, unsupported schema, schema unavailable and structured SecretRef values all have the same fix.
- On OpenClaw 2026.9.4 the form lists every setting it can only edit as text, by path, under “Form view can’t safely edit some fields”.
- A greyed-out Raw toggle (“Raw mode unavailable for this snapshot”) means the page has no config loaded yet; reload it.
doctor --fixdoes not change this, because nothing is broken.
For the broader OpenClaw error catalog, the Complete Troubleshooting Guide has the full list, and the Complete Reference and Silent Failures guide covers the related openclaw doctor --fix workflow.
Need someone to audit your OpenClaw deployment?
If your agents are behaving in ways your config “should” prevent, the cause is often a setting nobody can see from the editor they use. We audit OpenClaw deployments for configuration drift and other production-debugging issues.
Two ways to get help:
- AI Tools Audit: structured 2-3 week review of your stack including OpenClaw configuration audit. Independent, Canadian, no vendor referral fees.
- AI Security & Deployment: managed-service option with ongoing monitoring and configuration hardening.
Or book a discovery call to scope a one-time audit.
Soli Deo Gloria
Frequently Asked Questions
What does 'unsupported schema node. use raw mode.' mean in OpenClaw?
It means the Control UI's form view reached a config setting it has no form control for, so it shows this message in place of an input. The setting is not invalid and the gateway reads it normally. Switch the editor to Raw and edit that setting as JSON or JSON5 text.
Is 'unsupported schema node' an error or a warning?
It is neither a gateway error nor a validation failure. It is the form editor saying it cannot draw a control for that one setting. Your config still loads and your agents still run. The only thing blocked is editing that setting through the form.
How do I switch OpenClaw to raw mode?
In the Control UI config page, use the Form and Raw toggle at the top of the editor and choose Raw, which opens the config as JSON or JSON5 text. Edit the setting there and save. If the Raw option is greyed out with the tooltip 'Raw mode unavailable for this snapshot', the page has no config snapshot loaded yet, so reload it first.
What is the difference between 'unsupported schema node' and 'unsupported type', 'unsupported array schema' or 'unsupported schema'?
They are four different reasons the form cannot draw something. Unsupported schema node is a setting the form has flagged as one it cannot render. Unsupported type is a field whose declared type is not one the form knows how to draw, which is why the type name is sometimes blank. Unsupported array schema is a list with no definition of what its items look like. Unsupported schema means a whole section is not a plain object with named properties. All four have the same fix, which is to edit in Raw.
What does 'Form view can't safely edit some fields' mean?
It is the heading the Control UI shows above the list of settings in your config that the form cannot edit. In OpenClaw 2026.9.4 it names them, for example '2 settings in this config can only be edited as text' followed by their paths. It tells you exactly which settings to change in Raw, and it does not mean anything is wrong with them.
Will openclaw doctor --fix resolve this?
No. The message comes from the Control UI's form editor, not from the gateway, so there is nothing for doctor to repair. Doctor handles config migrations and gateway health. For a setting the form cannot draw, Raw mode is the fix.
Why does a stored secret say 'use Raw mode to edit'?
When a secret is configured as a structured value (a SecretRef that points at an environment variable, a file or a secret store) rather than a plain string, the form cannot edit it and shows 'Structured value (SecretRef) - use Raw mode to edit'. Plain string secrets are never sent to the browser at all, so the form asks you to enter a new value to replace one rather than showing the old one.
Stop Googling OpenClaw errors.
Your agents message ours on Telegram. Production-tested OpenClaw fixes. $99/mo.