# DotCraft Full Configuration Reference

This page collects configuration fields in one place. For first-time setup, read [Project Workspace](../features/workspace.md). For file, shell, sandbox, and network boundaries, read [Security & Sandbox](../features/security.md).

## Basic Configuration

| Field | Description | Default |
|-------|-------------|---------|
| `ProviderId` | Current personal provider id. Empty means no provider is selected | Empty |
| `Model` | Default model name | `gpt-4o-mini` |
| `NetworkTimeoutSeconds` | Global model request timeout in seconds; providers can override it | `600` |
| `Providers` | Personal model provider dictionary, usually stored in `~/.craft/config.json` | Empty |
| `Language` | UI language: `Chinese` / `English` | `Chinese` |
| `MaxToolCallRounds` | Maximum tool-call rounds for the main Agent | `100` |
| `SubagentMaxToolCallRounds` | Maximum tool-call rounds for subagents | `50` |
| `SubagentMaxConcurrency` | Maximum concurrent subagents | `3` |
| `MaxSessionQueueSize` | Maximum queued requests per session; `0` means unlimited | `3` |
| `ConsolidationModel` | Memory consolidation model. Empty uses the main model | Empty |
| `DebugMode` | Prints untruncated tool arguments in the console | `false` |
| `EnabledTools` | Globally enabled tool names. Empty enables all tools | `[]` |

Personal provider example:

```json
{
  "Providers": {
    "anthropic": {
      "DisplayName": "Anthropic",
      "Protocol": "anthropic",
      "ApiKey": "${ANTHROPIC_API_KEY}"
    },
    "openrouter": {
      "DisplayName": "OpenRouter",
      "Protocol": "openai-chat-completions",
      "ApiKey": "${OPENROUTER_API_KEY}",
      "EndPoint": "https://openrouter.ai/api/v1"
    }
  }
}
```

Workspace config only needs the provider and model selection:

```json
{
  "ProviderId": "anthropic",
  "Model": "claude-sonnet-4-5"
}
```

Provider object fields:

| Field | Description | Default |
|-------|-------------|---------|
| `DisplayName` | User-facing provider name; falls back to the provider id when empty | Empty |
| `Protocol` | Provider protocol: `anthropic`, `openai-chat-completions`, or `openai-responses`. Empty values and legacy `openai` are treated as `openai-chat-completions`. | `openai-chat-completions` |
| `ApiKey` | Provider API key; prefer `${ENV_NAME}` environment variable references | Empty |
| `EndPoint` | Provider base URL; empty values use the protocol default endpoint | OpenAI protocols: `https://api.openai.com/v1`; `anthropic`: `https://api.anthropic.com` |
| `NetworkTimeoutSeconds` | Per-provider request timeout, overriding the global `NetworkTimeoutSeconds` | Empty |

DotCraft reads global `~/.craft/config.json` first, then overlays workspace `.craft/config.json`; workspace fields win. String values in config support `$VAR` and `${VAR}` environment variable placeholders. If a variable is not set, the original placeholder is preserved.

## Memory

| Field | Description | Default |
|-------|-------------|---------|
| `Memory.AutoConsolidateEnabled` | Enables automatic long-term memory consolidation | `true` |
| `Memory.ConsolidateEveryNTurns` | Successful turns per thread between long-term memory consolidation attempts | `5` |

## Compaction

| Field | Description | Default |
|-------|-------------|---------|
| `Compaction.AutoCompactEnabled` | Enables threshold-based auto compaction | `true` |
| `Compaction.ReactiveCompactEnabled` | Enables reactive compaction for `prompt_too_long` errors | `true` |
| `Compaction.ContextWindow` | Model context window in tokens. When unset, DotCraft infers it from the current effective model, including per-thread model overrides, using the model context-window catalog; unknown models use `256000` | Model catalog value / `256000` |
| `Compaction.MaxContextWindow` | Upper bound used for inferred model catalog context windows; explicit `Compaction.ContextWindow` values are preserved | `256000` |
| `Compaction.SummaryReserveTokens` | Tokens reserved for summary output | `20000` |
| `Compaction.AutoCompactBufferTokens` | Token buffer below the hard limit that triggers auto compaction | `13000` |
| `Compaction.WarningBufferTokens` | Token buffer before auto threshold that emits warning | `20000` |
| `Compaction.ErrorBufferTokens` | Token buffer before auto threshold that emits error | `10000` |
| `Compaction.ManualCompactBufferTokens` | Token buffer below the hard limit where manual `/compact` remains allowed | `3000` |
| `Compaction.KeepRecentMinTokens` | Minimum recent tail tokens after partial summary | `10000` |
| `Compaction.KeepRecentMinGroups` | Minimum recent API groups after partial summary | `3` |
| `Compaction.KeepRecentMaxTokens` | Maximum recent tail tokens after partial summary | `40000` |
| `Compaction.MicrocompactEnabled` | Enables micro-compaction | `true` |
| `Compaction.MicrocompactTriggerCount` | Compressible tool-result count that triggers micro-compaction | `30` |
| `Compaction.MicrocompactKeepRecent` | Recent tool results kept during micro-compaction | `8` |
| `Compaction.MicrocompactGapMinutes` | Also triggers after this many minutes since last assistant message; `0` disables it | `20` |
| `Compaction.MaxConsecutiveFailures` | Consecutive failures before circuit breaking compaction | `3` |

### Model Context-Window Catalog

DotCraft ships a built-in context-window catalog for common models and uses it when `Compaction.ContextWindow` is not explicitly configured. The lookup uses the current effective model, so a per-thread model override takes precedence over the workspace default. Inferred values are capped by `Compaction.MaxContextWindow`, which defaults to `256000`. You can extend or override the catalog with JSON files:

- Global: `~/.craft/model-context-windows.json`
- Workspace: `.craft/model-context-windows.json`

Workspace mappings take precedence over global mappings; both override the built-in catalog. Model names use longest-prefix matching, so `gpt-4o` can match `gpt-4o-mini`, and `kimi-k2-` can match later variants in the same family. For common OpenAI protocol gateway names like `provider/model-name` and `provider/org/model-name`, DotCraft also tries each suffix after a slash.

```json
{
  "defaultContextWindow": 256000,
  "models": {
    "my-256k-model": 256000,
    "custom-long-context-": 1048576
  }
}
```

## Reasoning

| Field | Description | Default |
|-------|-------------|---------|
| `Reasoning.Enabled` | Requests provider reasoning support | `false` |
| `Reasoning.Effort` | Reasoning depth: `None` / `Low` / `Medium` / `High` / `ExtraHigh` | `Medium` |
| `Reasoning.Output` | Reasoning visibility: `None` / `Summary` / `Full` | `Full` |

For OpenAI protocol providers whose model matches the Deep Thinking adapter catalog, DotCraft automatically enables the thinking/tool-call compatibility layer. The built-in catalog covers `deepseek` and `mimo` models, and also enables the adapter when the `EndPoint` host contains `deepseek`. During tool-call rounds, DotCraft sends the previous assistant message's `reasoning_content` back together with `content` and `tool_calls`, as required by these models' thinking modes.

You can extend the adapter catalog with JSON files:

- Global: `~/.craft/model-thinking-adapters.json`
- Workspace: `.craft/model-thinking-adapters.json`

Workspace adapters take precedence over global adapters; both extend the built-in catalog. Model names use longest-prefix matching and support slash suffixes in forms like `provider/model-name` and `provider/org/model-name`.

```json
{
  "deepThinking": {
    "models": ["deepseek", "mimo", "my-thinking-model-"],
    "endpoints": ["deepseek", "my-thinking-gateway"]
  }
}
```

```json
{
  "ProviderId": "deepseek",
  "Model": "deepseek-reasoner",
  "Providers": {
    "deepseek": {
      "DisplayName": "DeepSeek",
      "Protocol": "openai-chat-completions",
      "ApiKey": "sk-...",
      "EndPoint": "https://api.deepseek.com/v1"
    }
  },
  "Reasoning": {
    "Enabled": true,
    "Effort": "Medium",
    "Output": "Full"
  }
}
```

## PromptCaching

Injects Anthropic prompt cache markers for matching models. OpenAI protocol Claude/LiteLLM routes use OpenAI-compatible request shaping with a single-marker strategy: each request marks only the latest cacheable conversation tail (user, assistant, or tool result), falling back to system only when there is no tail. Native Anthropic routes use the official SDK's content-block cache control and keep the stable system breakpoint plus tail/remembered breakpoints, up to four breakpoints per request. `cache_write_input_tokens > 0` with `cache_read_input_tokens == 0` usually means cache warmup or rewrite; if a request drops from a high `cache_read_input_tokens` value to 0 while system/tools are stable, check the trace prompt-cache diagnostic classification.

| Field | Description | Default |
|-------|-------------|---------|
| `PromptCaching.Enabled` | Inject prompt cache markers for matching models | `true` |
| `PromptCaching.ModelPatterns` | Case-insensitive model name fragments. Empty matches no models | `["claude"]` |
| `PromptCaching.Placement` | Marker placement strategy. Currently only `ConversationTail` is supported | `ConversationTail` |
| `PromptCaching.Ttl` | Anthropic cache TTL. Empty uses the default 5 minutes; `1h` requests the long cache | Empty |

## Entry Points and Services

| Field | Description | Default |
|-------|-------------|---------|
| `Acp.Enabled` | Enables ACP mode | `false` |
| `DashBoard.Enabled` | Enables Dashboard | `false` |
| `DashBoard.Host` | Dashboard listen address | `127.0.0.1` |
| `DashBoard.Port` | Dashboard listen port | `8080` |
| `Gateway.Enabled` | Enables Gateway Host | `false` |

## Automation and Workflows

| Field | Description | Default |
|-------|-------------|---------|
| `Automations.Enabled` | Enables the Automations orchestrator | `true` |
| `Automations.LocalTasksRoot` | Local task root. Empty uses `.craft/tasks/` | Empty |
| `Automations.PollingInterval` | Polling interval | `00:00:30` |
| `Automations.MaxConcurrentTasks` | Maximum concurrent local tasks | `3` |
| `Automations.TurnTimeout` | Single-turn timeout | `00:30:00` |
| `Automations.StallTimeout` | Stall timeout without response | `00:10:00` |
| `Automations.MaxRetries` | Maximum retry count | `3` |
| `Automations.RetryInitialDelay` | Initial retry delay | `00:00:30` |
| `Automations.RetryMaxDelay` | Maximum retry delay | `00:10:00` |
| `Hooks.Enabled` | Enables Hooks | `true` |
| `Hooks.Events` | Hook event configuration list | `[]` |
| `Cron.Enabled` | Enables Cron scheduled tasks | `true` |
| `Heartbeat.Enabled` | Enables heartbeat service | `false` |
| `Heartbeat.IntervalSeconds` | Check interval in seconds | `1800` |
| `Heartbeat.NotifyAdmin` | Sends results to admin in social channels | `true` |

## MCP and LSP

| Field | Description | Default |
|-------|-------------|---------|
| `McpServers` | MCP server configuration map | `{}` |
| `Tools.DeferredLoading.Strategy` | Deferred tool loading strategy: `Off`, `Auto`, `Simulated`, or `Native`. `Auto` uses native client-executed `tool_search` for `openai-responses` and simulated `SearchTools` for chat-completions/Anthropic. If an OpenAI-compatible / LiteLLM / DashScope route does not support native `tool_search`, use the `openai-chat-completions` protocol or set this explicitly to `Simulated`. Legacy `Enabled` is ignored. | `Auto` |
| `Tools.DeferredLoading.AlwaysLoadedTools` | MCP tool names that are always loaded upfront | `[]` |
| `Tools.DeferredLoading.DeferThreshold` | Minimum MCP tool count before MCP tools are deferred | `10` |
| `Tools.DeferredLoading.MaxSearchResults` | Maximum deferred tool search results per query | `5` |
| `LspServers` | LSP server configuration map | `{}` |
| `Tools.Lsp.Enabled` | Enables the built-in LSP tool | `false` |

## SubAgent

For the beginner path and examples, read [SubAgents](../features/subagents.md).

| Field | Description | Default |
|-------|-------------|---------|
| `SubAgent.MaxDepth` | Maximum session-backed SubAgent spawn depth; the first child is depth `1` | `1` |
| `SubAgent.Model` | Model used by DotCraft native SubAgents; empty inherits the current thread's effective main model | Empty |
| `SubAgent.EnableExternalCliSessionResume` | Allows external CLI profiles that support resume to reuse saved external sessions | `false` |
| `SubAgent.DisabledProfiles` | SubAgent profile names hidden and disabled for this workspace | `[]` |
| `SubAgent.Roles` | Workspace-defined SubAgent roles; entries with built-in names override built-in roles | `[]` |

Fields inside each `SubAgent.Roles` entry:

| Field | Description |
|-------|-------------|
| `Name` | Role name, also the value used by `SpawnAgent.agentRole` |
| `Description` | Short role description exposed to the main Agent |
| `ToolAllowList` | Exact tool allow-list; empty means no additional restriction on eligible tools |
| `ToolDenyList` | Exact tool deny-list removed after the tool set is assembled |
| `AgentControlToolAccess` | AgentTools policy: `Disabled` / `Full` / `AllowList` |
| `AllowedAgentControlTools` | AgentTools names allowed when `AgentControlToolAccess` is `AllowList` |
| `PromptProfile` | Native SubAgent prompt profile: `subagent-light` / `full` |
| `Instructions` | Role instructions appended to the SubAgent prompt |
| `Mode` | Optional mode override |
| `Model` | Optional model override |
| `OverrideBasePrompt` | Replaces the base prompt with `Instructions`; by default instructions are appended |

## External Channels

TypeScript external channels such as QQ and WeCom are registered with `ExternalChannels`. Desktop embedded channels are saved with `transport: "subprocess"` and `builtinModule`; independently managed adapters usually use `transport: "websocket"`:

```json
{
  "AppServer": {
    "Mode": "WebSocket",
    "WebSocket": {
      "Host": "127.0.0.1",
      "Port": 9100,
      "Token": ""
    }
  },
  "ExternalChannels": {
    "qq": {
      "enabled": true,
      "transport": "subprocess",
      "builtinModule": "channel-qq"
    },
    "wecom": {
      "enabled": true,
      "transport": "websocket"
    }
  }
}
```

Platform connections, allowlists, and approval timeouts live in adapter-specific files such as `.craft/qq.json` and `.craft/wecom.json`.

## Custom Commands

`CustomCommands` stores reusable prompts or workflows as commands. Command content usually lives under workspace `.craft/commands/` or the corresponding configuration entry, then can be reused from CLI, Desktop, and other entry points.
