preserve $include structure after updates? | Friends of the Crustacean 🦞🤝 | Page 1

regal vault Apr 22, 2026, 6:02 AM

#

Hi all,
I've been running OpenClaw with a split config setup using the $include feature — where openclaw.json contains only includes pointing to separate files in config/:
json{
"agents": { "$include": "./config/agents.json" },
"models": { "$include": "./config/models.json" },
"gateway": { "$include": "./config/gateway.json" },
"channels": { "$include": "./config/channels.json" },
"plugins": { "$include": "./config/plugins.json" },
"auth": { "$include": "./config/auth.json" },
"tools": { "$include": "./config/tools.json" },
"bindings": { "$include": "./config/bindings.json" }
}
This works great for keeping config organized and auditable. However, every time openclaw onboard or npm install -g openclaw@latest runs, the tooling overwrites openclaw.json with a flat merged config, destroying the $include structure.
Feature request / bug report: Could the onboard wizard and update routine detect an existing $include structure and write changes back to the appropriate sub-files instead of flattening everything into openclaw.json? Or at minimum, warn that it's about to overwrite a split config?
For now I've written a workaround script that re-splits after each update, but it would be much cleaner if OpenClaw's own tooling respected its own $include feature.

But I'm no programmer, so, do I something wrong? Is it a setting that I missed?

proud zealotBOT Apr 22, 2026, 6:02 AM

#

white bearBOT Apr 22, 2026, 6:02 AM

#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

proud zealotBOT Apr 22, 2026, 6:02 AM

#

buoyant quiverBOT Apr 22, 2026, 6:06 AM

#

Let me verify the docs path and then I’ll answer cleanly.

#

You’re not doing anything wrong.

I checked the current behavior, and this looks like a real limitation, not a missed setting:

$include is supported for reading split config
but config-writing flows do not preserve the include structure
so commands that save config, like openclaw onboard and other config-mutating commands, can flatten everything back into openclaw.json

In plain English, OpenClaw can read your modular config, but when it writes config back, it mostly writes the resolved merged result, not the original file layout.

Docs for $include: https://docs.openclaw.ai/gateway/configuration#split-config-into-multiple-files-include

One small nuance: npm install -g openclaw@latest by itself should not usually be the thing rewriting config. It’s more likely a follow-up command that persists config afterward.

So yes, your request is reasonable. I’d call this a product gap / bug, not user error.

If you want, paste:

#

openclaw --version

but from what you described, I’d file this on GitHub as a feature request/bug with your repro and workaround script:
https://github.com/openclaw/openclaw/issues

Glad that helped! 🎉
If this fixed it, please right-click the solution message → Apps → ✅ Mark Solution.

regal vault Apr 22, 2026, 6:10 AM

#

OpenClaw 2026.4.21 (f788c88), and can you give me the best description and title to put in https://github.com/openclaw/openclaw/issues because I'm no programmer and English is not my first language. Or can I put this here on discord somewhere where it would be picked up?

buoyant quiverBOT Apr 22, 2026, 6:12 AM

#

Yep, 2026.4.21 fits with what I found.

And for this kind of thing, GitHub issues is the right place, not Discord. Discord is easy to miss, but GitHub is where bug reports / feature requests actually get tracked.

I’d suggest this title:

Config-writing commands flatten $include-based config into openclaw.json

And here’s a ready-to-paste issue body:

## Summary

I use OpenClaw with a split config based on `$include`, for example:

```json5
{

#

"agents": { "$include": "./config/agents.json" },
"models": { "$include": "./config/models.json" },
"gateway": { "$include": "./config/gateway.json" },
"channels": { "$include": "./config/channels.json" },
"plugins": { "$include": "./config/plugins.json" },
"auth": { "$include": "./config/auth.json" },
"tools": { "$include": "./config/tools.json" },
"bindings": { "$include": "./config/bindings.json" }
}


This works well for organizing and auditing the configuration.

However, when OpenClaw writes config back to disk, the `$include` structure is not preserved. The root `openclaw.json` gets rewritten as one flat merged config, which destroys the modular layout.

## Version

#


OpenClaw 2026.4.21 (`f788c88`)

## Steps to reproduce

1. Create an `openclaw.json` that uses `$include` entries pointing to separate files.
2. Confirm OpenClaw loads the split config correctly.
3. Run a command that writes config, for example `openclaw onboard`.
4. Check `openclaw.json`.

## Actual behavior

`openclaw.json` is rewritten as a flat merged config, instead of keeping the original `$include` structure.

## Expected behavior

#


One of these behaviors would be much safer:

1. Preserve the existing `$include` structure and write changes back to the appropriate included files, or
2. Detect that the config uses `$include` and warn before flattening / overwriting it.

## Notes

- I currently use a workaround script that re-splits the config after updates.
- I am not sure whether every write path is affected, but `openclaw onboard` is enough to reproduce the problem on my setup.
- If needed, I can provide my workaround script or a minimal repro layout.

Tiny suggestion: I would make the issue about openclaw onboard or config-writing commands, not npm install -g openclaw@latest, unless you are sure install alone rewrites the file. That makes the report more precise.

File it here: https://github.com/openclaw/openclaw/issues

#

Glad that helped! 🎉
If this fixed it, please right-click the solution message → Apps → ✅ Mark Solution.

regal vault Apr 22, 2026, 6:25 AM

#

And file it as a bug report or a Feature request?

buoyant quiverBOT Apr 22, 2026, 6:26 AM

#

I’d file it as a bug report.

Reason: $include is already a supported feature, so flattening the config on write feels like incorrect behavior, not just a missing nice-to-have.

Good framing:

Bug: config-writing commands do not preserve an existing $include layout
Possible fix: preserve the layout, or at least warn before flattening it

So if the GitHub form makes you choose only one, pick Bug report.

regal vault Apr 22, 2026, 8:33 AM

#

I've looked at the bug reporting and there are too many things that I can't answer... is there somewhere/someone else that I can give this to who will be able to file a "bug"-report? Because I've looked at other bug-reports and I see that there will be follow-up questions and I'm not so code-knowledged to explain or help with this.

buoyant quiverBOT Apr 22, 2026, 8:34 AM

#

Yeah, that’s frustrating. You do not need to understand the code to report this.

There isn’t really a better official handoff path on Discord for bugs like this. GitHub issues is still the place. But you can keep it very simple, and for anything you don’t know, just write “unknown” or “not sure”.

You can paste something this short:

## What happened

I use `$include` in `openclaw.json` to split my config into separate files.

When I run `openclaw onboard`, my `openclaw.json` gets rewritten into one flat merged config, and the `$include` structure is lost.

## What I expected

I expected OpenClaw to keep the existing `$include` structure, or at least warn before flattening it.

#


## Version

OpenClaw 2026.4.21 (`f788c88`)

## Steps to reproduce

1. Create an `openclaw.json` that uses `$include` for separate config files.
2. Run `openclaw onboard`.
3. Check `openclaw.json`.

## Notes

I am not a programmer, so I may not be able to answer deep implementation questions.
But I can confirm this behavior on my setup.

#


Example root config:

```json5
{
  "agents": { "$include": "./config/agents.json" },
  "models": { "$include": "./config/models.json" },
  "gateway": { "$include": "./config/gateway.json" },
  "channels": { "$include": "./config/channels.json" },
  "plugins": { "$include": "./config/plugins.json" },
  "auth": { "$include": "./config/auth.json" },
  "tools": { "$include": "./config/tools.json" },
  "bindings": { "$include": "./config/bindings.json" }
}

#

That is enough. Really.

If the form asks things you can’t answer:

logs → not sure
exact cause → unknown
workaround → I use a script to re-split the config afterward

If you want, I can also make you an even more GitHub-form-style version with one-line answers for each field.

regal vault Apr 22, 2026, 8:34 AM

#

Yes please.

buoyant quiverBOT Apr 22, 2026, 8:35 AM

#

Yep, here’s a GitHub-form-style version you can paste and edit a little if needed:

Title
Config-writing commands flatten existing $include-based config into openclaw.json

Body

## Bug description

I use `$include` in `openclaw.json` to split my config into separate files.

This works correctly when OpenClaw reads the config, but when I run a config-writing command like `openclaw onboard`, the root `openclaw.json` is rewritten as one flat merged config and the `$include` structure is lost.

## Expected behavior

I expected OpenClaw to preserve the existing `$include` structure.

#


If preserving it is not possible, I expected at least a warning before rewriting the file.

## Actual behavior

`openclaw.json` is rewritten as a flat merged config, and my split config layout is destroyed.

## Steps to reproduce

1. Create an `openclaw.json` that uses `$include` for separate config files.
2. Run `openclaw onboard`.
3. Check `openclaw.json`.

## Example config

```json5

#

{
"agents": { "$include": "./config/agents.json" },
"models": { "$include": "./config/models.json" },
"gateway": { "$include": "./config/gateway.json" },
"channels": { "$include": "./config/channels.json" },
"plugins": { "$include": "./config/plugins.json" },
"auth": { "$include": "./config/auth.json" },
"tools": { "$include": "./config/tools.json" },
"bindings": { "$include": "./config/bindings.json" }
}


## Version

OpenClaw 2026.4.21 (`f788c88`)

#

## Environment

- OS: unknown / [fill in if you want]
- Install method: global npm install
- Config style: split config using `$include`

## Additional context

- I am not a programmer, so I may not be able to answer deep implementation questions.
- I can confirm the behavior on my setup.
- I currently use a workaround script to split the config again after updates/config writes.
- I am reporting this because `$include` is already a supported feature, so I expected config-writing commands to respect it.

If the form asks extra things, these are safe answers:

#

Regression? Not sure
Logs? Not sure / not applicable
Can you reproduce? Yes
Workaround? Yes, I re-split the config with a script after the file is rewritten

If you want, I can also make a super short version for forms with tiny text boxes.

regal vault Apr 22, 2026, 8:56 AM

#

Thanks, file bug https://github.com/openclaw/openclaw/issues/70087

buoyant quiverBOT Apr 22, 2026, 8:57 AM

#

Nice, that’s exactly the right place. 👍

Thanks for filing it.

If they ask follow-up questions on the issue and the wording is annoying, paste them here and I’ll help you write the replies.

Glad that helped! 🎉
If this solved your question here, please right-click the solution message → Apps → ✅ Mark Solution.

#preserve $include structure after updates?