Configuration

The desktop settings page does not expose maximum steps or temperature. Built-in desktop conversations, including resumed conversations and delegated workers, use unlimited steps and automatic model/provider temperature. Desktop execution ignores saved agent.max_steps and agent.temperature values in both user configuration and project overlays without rewriting those files. CLI execution and explicit automation configuration continue to honor these values; omit them or set them to 0 for unlimited steps and automatic temperature. External engines retain their own execution settings.

Wuu keeps model connections and execution choices in user configuration, while projects can supply additional behavior. Start with wuu init for CLI use or desktop onboarding, then edit only the settings you need. Wuu rejects unknown configuration fields rather than silently ignoring typos.

The built-in agent can use ordinary file tools to edit configuration in Standard or Unconfined mode; Read only permits inspection but refuses edits. Wuu home is part of the normal file scope, so no separate configuration tool is needed. To add a provider or change the default model, edit the user file described below; project-layer restrictions still apply. The desktop uses its existing refresh path for valid model changes, while other settings retain their documented restart requirements.

Prefer environment-variable references for provider credentials. Tool output may redact secret values: use focused edits rather than replacing the whole configuration with a copy of redacted output. Direct file access to Wuu login credential stores remains blocked; see permissions.

If an external edit makes configuration invalid while the desktop is running, Wuu reports the error and retains the last valid model inventory for display. That inventory does not bypass configuration validation for changes or execution. Correct the file to resume automatic refresh; restoring its previous contents also clears the error. Unchanged invalid files do not produce repeated refresh errors.

User configuration and project layers

Normal startup selects the user file at ~/.wuu/config.json, or $WUU_HOME/config.json when set. The legacy ~/.config/wuu/config.json path is a migration and fallback source, not another overlay applied after the current user file.

Wuu then merges project files in this order, with later values taking precedence where allowed:

1. .wuu.json, or wuu.json if the first does not exist.
2. .wuu/settings.json for shared settings.
3. .wuu/settings.local.json for local settings.

Objects merge recursively; arrays and scalar values are replaced. Keep the local settings file out of version control. A missing user configuration does not silently turn a project file into the trusted base; the CLI asks you to initialize one.

Protected user settings

Normal startup removes these fields from every project layer, including settings.local.json, and reports the ignored fields:

Field	Why it stays user-owned
default_provider, providers	Select model services, endpoints, credentials, and connection options
instructions, legacy memory	Control instruction discovery, including user paths
agent.model_roles, agent.model_aliases	Route model work
agent.permission_mode	Set local execution authority
ptc, execution_environments	Select the user-owned tool runtime and execution adapters

Case changes in JSON keys do not bypass the restriction. Other allowed project fields can still affect prompts, tools, hooks, and services, so this filtering does not make an unfamiliar repository safe to execute.

Model and engine configuration

A provider entry names a model connection. For example, this user-configuration fragment uses an OpenAI-compatible Chat endpoint:

{
  "default_provider": "work",
  "providers": {
    "work": {
      "type": "openai-compatible",
      "base_url": "https://api.example.com/v1",
      "api_key_env": "WORK_MODEL_API_KEY",
      "model": "your-model-id"
    }
  },
  "agent": { "permission_mode": "standard" }
}

Replace the endpoint and model with values your service supports, and supply the named environment variable to the process running Wuu. For subscription login, provider types, and desktop setup, see model services.

External engines are separate programs, not provider types. Their machine-local engines configuration controls detection, executable selection, and the default engine. In the desktop, changing a conversation’s model does not necessarily change the workspace default; use settings when you intend to change future sessions.

Built-in agent settings

The desktop has no separate Built-in agent settings tab. Context management, programmatic tool calling and execution environments remain configurable in the user file. Existing values are preserved. These settings do not control external engines. Git commit attribution remains in Settings → General → Git.

Field	Meaning
agent.disable_auto_compact	true disables automatic compaction; omitted or false enables it.
agent.compact_threshold_pct	Compaction trigger as a fraction, for example 0.5 for 50%; 0 or omitted means automatic. Custom values must be greater than 0 and less than 1.
agent.compact_keep_recent_tokens	Recent raw-history token budget retained after compaction; 0 or omitted uses 20,000.
providers.<name>.context_window	Context-window override for the named connection; 0 or omitted uses detected model metadata.
agent.max_context_tokens	Fallback context limit when the model’s limit is unknown; 0 or omitted uses automatic resolution.
ptc.enabled	Programmatic tool calling for the built-in engine; defaults to true.
execution_environments.default, execution_environments.profiles	Default environment for new conversations and named profiles; see execution environments.

Edit only the relevant fields in the existing user file; do not replace its other settings. Finish active work, fully quit Wuu, and restart it to apply all these changes. Valid model changes can refresh automatically, but saving the file does not guarantee every runtime setting is updated immediately. Project layers can override allowed agent fields; provider connections, PTC, and execution environments must be set in user configuration, not project settings. A custom configuration provider may use a different authoritative source instead of this file.

Tool loading

agent.tool_loading defaults to auto. Supported first-party paths use native loading: OpenAI Responses with supported GPT-5.4 or later models (excluding GPT-5.4 nano), Claude models with tool search support (including Haiku 4.5; excluding Opus 4.1 and earlier) on Anthropic, and kimi-k3, kimi-k3.1-pro, or kimi-k3.1-pro-highspeed Chat Completions at https://api.moonshot.ai/v1 or https://api.moonshot.cn/v1. Kimi uses a separate message-level tools protocol; its Responses and Anthropic-compatible endpoints are not enabled by this rule.

Native loading keeps deferred schemas out of the initial model context and loads them through tool_search. The embedded browser is deferred when enabled. Other paths use client: ordinary tool_search results load schemas on demand without requiring a provider-specific protocol. The initial catalog preview is bounded to 8 KiB; tools beyond it remain searchable. Loaded schemas are appended to the direct-tool prefix, so discovery can change provider cache reuse. Ordinary tool calling or a compatible URL alone does not establish native support.

Set agent.tool_loading to client to always use ordinary discovery, flat to intentionally declare every tool, or native to opt into an implemented protocol on a compatible endpoint. Unsupported native paths use client discovery and report the change; this is a configuration-time choice, not an API retry. A model’s providers.<name>.models.<model>.options.native_tool_search can explicitly enable a compatible endpoint in auto mode, or disable native discovery with false while keeping client discovery. Only enable it when the endpoint implements the model’s native protocol; accepting unknown fields is not sufficient.

Instructions and plugin settings

Put shared project rules in AGENTS.md. The core instructions object controls filenames, project-root markers, user directories, and optional legacy instruction discovery. The old top-level memory name is accepted for instruction-discovery migration; it is not the Memory plugin’s settings interface.

Memory, Dream, and other plugins maintain their own product settings and storage. The core’s persistent session working notes are separate from plugin memory. Use each plugin’s settings page rather than copying obsolete memory.dream or delegation flags into the core config.

Worker capacity

agent.max_parallel sets the generic anonymous-worker execution capacity. It defaults to 5; 0 means use that default, and negative values are invalid.

{ "agent": { "max_parallel": 5 } }

Queued workers and workers waiting for children do not occupy normal execution slots. This is an execution-capacity setting, not a request to delegate every task or a limit on all background processes. Subagent behavior belongs to the enabled delegation plugin.

Explicit automation configuration

wuu exec --config /path/to/config.json loads one complete file without normal project overlays. wuu exec --ignore-user-config instead trusts the project’s .wuu.json or wuu.json as the base and applies its two settings layers.

Both choices deliberately accept connections, credential references, instruction paths, hooks, and MCP definitions from those files. Use them only with reviewed configuration. An empty HOME does not grant the same trust implicitly.

Moving user state

Set WUU_HOME before starting Wuu to select a different user-state root. It affects configuration, authentication state, sessions, memory, plugins, and logs, not just the config file. For example, WUU_HOME=/data/wuu selects /data/wuu/config.json. Protect that directory and avoid sharing it in diagnostics.

On Windows, command execution requires Git Bash; WUU_GIT_BASH_PATH can select its executable. Command availability and sandbox support are separate requirements, described in permissions and the command system.