Where Does OpenHands Store Settings?
The OpenHands settings file and conversation folder in ~/.openhands, shared by the CLI and the desktop GUI server.
Last updated
OpenHands keeps almost everything in one dot directory: ~/.openhands. The settings.json file holds your LLM configuration, and a conversations subfolder holds past session history. Both the CLI and the GUI server use this same directory, so a fix in one place applies everywhere.
Older guides mention a config.toml format from the V0 runtime days. That reference moved to the legacy docs. Current releases configure through settings.json, environment variables, or the Settings page in the web app, and the old TOML layout no longer applies.
Where OpenHands stores this, by platform
%USERPROFILE%\.openhands\settings.json
Same ~/.openhands layout as the other platforms, under your user profile. Edit settings.json with the GUI closed to avoid overwriting your changes. Conversation files sit in the conversations subfolder beside it.
~/.openhands/settings.json
Holds LLM provider and model choices plus integrations and secrets. The first CLI run creates it through an interactive walkthrough. Past sessions accumulate in ~/.openhands/conversations next door.
~/.openhands/settings.json
Identical to macOS. When running the GUI through Docker, this directory is still the source of truth on the host. Legacy config.toml advice from V0 era blog posts does not apply to current versions.
Frequently asked questions
where do I configure my OpenHands model
Open ~/.openhands/settings.json and set your LLM provider and model there before the first run. The CLI walks you through this once and saves the answers to the same file. Both the CLI and the GUI server read this one directory, so there is only one place to fix.
where is my OpenHands conversation history
Look in ~/.openhands/conversations, where past sessions are kept as files you can revisit. Upgrading from a pre 1.0 CLI resets the settings format, so expect to redo the setup walkthrough once after a big version jump.
how do I change OpenHands paths without editing files
Set the documented environment variables for the section you need, such as cache or file store paths. They map onto the old config.toml sections from V0. The GUI Settings page covers the common LLM and integration options without touching files.
Notice an outdated path? Let us know.