Settings Files and Precedence

Qoder CLI CN's behavior can be customized through JSON settings files (settings.json). Configuration is layered: the same setting can be set separately at different layers, then merged into the effective value by a fixed precedence. Understanding this layering and merge rule is the foundation for managing personal preferences and team conventions. This page covers the settings file locations, merge precedence, and common settings. For the complete list of settings and environment variables, see Settings, Environment Variables, and File Paths.

Settings file locations

Qoder CLI CN reads three layers of settings files:

Layer	Path	Description
User	`~/.qoder-cn/settings.json`	Personal preferences, effective for all of the current user's projects.
Project	`<project>/.qoder/settings.json`	Project-shared settings, committed to version control and shared by the team.
Local	`<project>/.qoder/settings.local.json`	Personal in-project overrides, usually not committed to version control.

The config directory defaults to ~/.qoder-cn and can be changed with the QODERCN_CONFIG_DIR environment variable. For the full structure of the .qoder/ directory, see The .qoder Directory.

Merge precedence

When the same setting appears at multiple layers, Qoder CLI CN merges from lowest to highest precedence, with higher precedence overriding lower:

Built-in defaults (schema defaults)
User settings (~/.qoder-cn/settings.json)
Project settings (<project>/.qoder/settings.json)
Local settings (<project>/.qoder/settings.local.json)
Settings passed via the --settings command-line flag (highest precedence)

In other words: local overrides project, project overrides user, and settings explicitly passed on the command line take precedence over all files.

How merging works

Settings use a deep merge, not wholesale replacement:

Objects: merged recursively field by field; only the fields present are overridden, and the rest keep the lower-precedence values.
Scalars (strings, numbers, booleans): higher precedence overrides directly.
Arrays: some settings (such as deny lists and exclusion lists) use "union merge," combining and deduplicating values across layers; other arrays default to override behavior.

So at the project level you only need to write the fields you want to override — no need to copy the entire user configuration.

The effect of folder trust

For security, project and local settings apply only when the current working directory is trusted. If the working directory is not trusted, Qoder CLI CN loads only the user settings and ignores the in-project settings.json and settings.local.json. Folder trust is controlled by security.folderTrust.enabled (on by default).

File format

Settings files are JSON (with // comments supported, see below). The top level is one object; most settings are nested by group, while a few sit directly at the top level (such as outputStyle, language, agent). For example:

{
  "outputStyle": "concise",
  "ui": {
    "theme": "Tokyo Night",
    "autoThemeSwitching": true
  },
  "model": {
    "name": "auto",
    "maxSessionTurns": -1
  },
  "tools": {
    "useRipgrep": true
  }
}

Notes:

Settings files may contain comments (ignored during parsing), handy for documenting team conventions.
Values can reference environment variables, which are resolved and substituted at runtime.
Some settings require restarting Qoder CLI CN to take effect (marked below).

Common settings

Below are the most frequently adjusted settings, organized by group. Items marked "restart required" take effect only after a restart.

Top-level settings

The following settings are written directly at the top level of the file, outside any group:

Setting	Type	Default	Description
`outputStyle`	string	none	Name of the active output style (restart required). The `general.outputStyle` form is also accepted; top level wins. See Output Styles.
`language`	string	none	Preferred language for AI responses (restart required).
`agent`	string	none	Name of the Agent used for the main thread (restart required).

ui (interface)

Setting	Type	Default	Description
`ui.theme`	string	none	Color theme name.
`ui.autoThemeSwitching`	boolean	`true`	Automatically switch between light and dark themes based on the terminal background.
`ui.customThemes`	object	`{}`	Custom theme definitions.
`ui.hideBanner`	boolean	`false`	Hide the startup banner.
`ui.showLineNumbers`	boolean	`true`	Show line numbers in the conversation.
`ui.loadingPhrases`	enum	`off`	What to show while loading: `tips` / `witty` / `all` / `off`.
`ui.accessibility.screenReader`	boolean	`false`	Screen reader mode with plain-text output (restart required).

For more interface and shortcut settings, see Interface and Shortcuts.

model

Setting	Type	Default	Description
`model.name`	string	none	The model used for the conversation.
`model.reasoningEffort`	enum	none	Reasoning effort level: `low` / `medium` / `high`, etc.
`model.maxSessionTurns`	number	`-1`	Maximum turns retained per session; `-1` for unlimited.

tools

Setting	Type	Default	Description
`tools.sandbox`	string/boolean/object	none	Sandboxed execution environment (restart required).
`tools.sandboxAllowedPaths`	string[]	`[]`	Additional paths accessible in the sandbox (restart required).
`tools.sandboxNetworkAccess`	boolean	`false`	Whether the sandbox allows network access (restart required).
`tools.useRipgrep`	boolean	`true`	Use ripgrep for content search.
`tools.shell.inactivityTimeout`	number	`300`	Timeout in seconds for shell commands with no output.
`tools.core`	string[]	none	Built-in tool allowlist — only the listed tools are allowed (restart required).
`tools.exclude`	string[]	none	Tool names excluded from discovery (restart required).

security

Setting	Type	Default	Description
`security.folderTrust.enabled`	boolean	`true`	Whether folder trust is enabled (restart required).
`security.toolSandboxing`	boolean	`false`	Tool-level sandbox isolation (restart required).
`security.disableYoloMode`	boolean	`false`	Disable the `bypass_permissions` (YOLO) permission mode (restart required).
`security.blockGitExtensions`	boolean	`false`	Block installing and loading extensions from Git (restart required).
`security.environmentVariableRedaction.enabled`	boolean	`false`	Redact environment variables that may contain secrets (restart required).

mcp (MCP servers)

Setting	Type	Default	Description
`mcpServers`	object	`{}`	MCP server configuration (restart required). See MCP.
`mcp.allowed`	string[]	none	Allowed MCP server list (restart required).
`mcp.excluded`	string[]	none	Excluded MCP server list (restart required).

statusLine

Setting	Type	Default	Description
`statusLine.type`	string	`command`	Status line type; currently only `command` is supported.
`statusLine.command`	string	`""`	Shell command that produces the status line, receiving session data JSON via stdin.
`statusLine.padding`	number	`0`	Horizontal padding characters for the status line.

Editing settings

There are two ways to modify settings:

In the interactive interface: run /settings to open the settings panel and directly view and adjust common settings.
Edit files manually: open the settings.json at the appropriate layer in an editor and add or modify fields per the tables above.

After changes, items not marked "restart required" usually take effect immediately; those marked "restart required" need Qoder CLI CN to be restarted.

Next steps

See all settings and environment variables: Settings, Environment Variables, and File Paths.
Add custom models through the /model wizard: Custom Models.
Customize the interface and shortcuts: Interface and Shortcuts.
Troubleshoot settings issues: Settings Not Taking Effect.

​Settings file locations

​Merge precedence

​How merging works

​The effect of folder trust

​File format

​Common settings

​Top-level settings

​ui (interface)

​model

​tools

​security

​mcp (MCP servers)

​statusLine

​Editing settings

​Next steps