openclaw
Version:
Multi-channel AI gateway with extensible messaging integrations
345 lines (270 loc) • 11.9 kB
Markdown
summary: "Agent workspace paths, bootstrap injection, context budgets, image handling, and timezone"
read_when:
- Choosing where an agent reads and writes files
- Tuning bootstrap injection or a context budget
- Adjusting inbound image scaling or the agent timezone
title: "Configuration — agent workspace and bootstrap"
`agents.defaults.*` keys for filesystem scope, bootstrap context injection, the context budget map, inbound image handling, and the agent timezone.
## `agents.defaults.workspace`
Default: `OPENCLAW_WORKSPACE_DIR` when set, otherwise `<state-dir>/workspace`. This is `~/.openclaw/workspace` for the default install and `~/.openclaw-<profile>/workspace` for a named profile. A custom `OPENCLAW_STATE_DIR` keeps the workspace under that state directory.
```json5
{
agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}
```
An explicit `agents.defaults.workspace` value takes precedence over `OPENCLAW_WORKSPACE_DIR`. A sole agent uses this path directly. In a multi-agent fleet, agents without their own `workspace` use an agent-id subdirectory so no implicit owner claims the shared root.
## `agents.defaults.cwd`
Optional working directory for agent reply runs. Use it to run coding tools in an
existing repository while bootstrap files (`AGENTS.md`, `SOUL.md`) and memory stay
in the managed agent workspace.
```json5
{
agents: {
defaults: { workspace: "~/.openclaw/workspace" },
entries: { coder: { cwd: "~/path/to/app", sandbox: { mode: "off" } } },
},
}
```
Session-spawned working directories take precedence, then `agents.entries.*.cwd`,
then `agents.defaults.cwd`. When none is set, tools use the agent workspace.
Paths expand `~` like `workspace`; relative paths resolve against the Gateway
process working directory. A distinct working directory requires an unsandboxed
run; sandboxed runs reject it. When the directories differ, the system prompt
identifies their separate roles so deliverables stay in the working directory.
## `agents.defaults.repoRoot`
Optional repository root shown in the system prompt's Runtime line. If unset, OpenClaw auto-detects by walking upward from the workspace.
```json5
{
agents: { defaults: { repoRoot: "~/path/to/openclaw" } },
}
```
## `agents.defaults.skills`
Optional default skill allowlist for agents that do not set
`agents.entries.*.skills`.
```json5
{
agents: {
ownership: "explicit",
defaults: { skills: ["github", "weather"] },
entries: {
writer: {}, // inherits github, weather
docs: { skills: ["docs-search"] }, // replaces defaults
"locked-down": { skills: [] }, // no skills
},
},
}
```
- Omit `agents.defaults.skills` for unrestricted skills by default.
- Omit `agents.entries.*.skills` to inherit the defaults.
- Set `agents.entries.*.skills: []` for no skills.
- A non-empty `agents.entries.*.skills` list is the final set for that agent; it
does not merge with defaults.
## `agents.defaults.skipBootstrap`
Disables automatic creation of workspace bootstrap files (`AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `BOOTSTRAP.md`), not injection of existing files. For the embedded runtime, use `contextInjection: "never"` to disable injection, unless overridden per agent.
```json5
{
agents: { defaults: { skipBootstrap: true } },
}
```
## `agents.defaults.skipOptionalBootstrapFiles`
Skips creation of selected optional workspace files while still writing required bootstrap files (`AGENTS.md`, `BOOTSTRAP.md`). Valid values: `SOUL.md`, `USER.md`, and `IDENTITY.md` (`HEARTBEAT.md` is accepted but a no-op since heartbeat context moved to cron monitor scratch).
```json5
{
agents: {
defaults: {
skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],
},
},
}
```
## `agents.defaults.contextInjection`
Controls workspace bootstrap-file injection in the embedded runtime. Default: `"always"`. These modes do not control CLI-backed prompt preparation or prevent an agent from reading files with tools.
- `"always"`: use normal workspace bootstrap injection, subject to the run's context mode and file filters.
- `"continuation-skip"`: eligible continuation turns after a recorded full-bootstrap turn skip workspace bootstrap re-injection, reducing prompt size. Heartbeat runs, pending full-bootstrap setup, and post-compaction retries still use normal context resolution.
- `"never"`: disable workspace bootstrap and context-file injection on every turn, including heartbeat and compaction-recovery turns. Use this for embedded agents with specialized bootstrap-free workflows.
```json5
{
agents: { defaults: { contextInjection: "continuation-skip" } },
}
```
Per-agent override: `agents.entries.*.contextInjection`. Omitted values inherit
`agents.defaults.contextInjection`.
## `agents.defaults.bootstrapMaxChars`
Max characters per workspace bootstrap file before truncation. Default: `20000`.
Exception: `USER.md` has a fixed 4,000-character cap; this setting can only
lower it for `USER.md`, never raise it. See [User model](/concepts/user-model).
```json5
{
agents: { defaults: { bootstrapMaxChars: 20000 } },
}
```
Per-agent override: `agents.entries.*.bootstrapMaxChars`. Omitted values inherit
`agents.defaults.bootstrapMaxChars`.
## `agents.defaults.bootstrapTotalMaxChars`
Max total characters injected across all workspace bootstrap files. Default: `60000`.
```json5
{
agents: { defaults: { bootstrapTotalMaxChars: 60000 } },
}
```
Per-agent override: `agents.entries.*.bootstrapTotalMaxChars`. Omitted values
inherit `agents.defaults.bootstrapTotalMaxChars`.
## Per-agent bootstrap profile overrides
Use per-agent bootstrap profile overrides when one agent needs different prompt
injection behavior from the shared defaults. Omitted fields inherit from
`agents.defaults`.
```json5
{
agents: {
defaults: {
contextInjection: "continuation-skip",
bootstrapMaxChars: 20000,
bootstrapTotalMaxChars: 60000,
},
entries: {
"strict-worker": {
contextInjection: "always",
bootstrapMaxChars: 50000,
bootstrapTotalMaxChars: 300000,
},
},
},
}
```
## Bootstrap truncation notice
When bootstrap context is truncated, OpenClaw always injects a concise
agent-visible notice into the system prompt saying some bootstrap files were
truncated and to read the affected files directly. This notice is built in
and not configurable, and it deliberately omits per-file diagnostics: file
names, raw vs injected counts, and limit causes stay in diagnostics such as
context/status reports and logs.
## Context budget ownership map
OpenClaw has multiple high-volume prompt/context budgets, and they are
intentionally split by subsystem instead of all flowing through one generic
knob.
| Budget | Covers |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agents.defaults.bootstrapMaxChars` / `bootstrapTotalMaxChars` | Normal workspace bootstrap injection |
| `agents.defaults.startupContext.*` | One-shot reset/startup model-run prelude, including recent daily `memory/*.md` files. Bare chat `/new` and `/reset` are acknowledged without invoking the model |
| `skills.limits.*` | The compact skills list injected into the system prompt |
| `agents.defaults.contextLimits.*` | Bounded runtime excerpts and injected runtime-owned blocks |
Matching per-agent overrides:
- `agents.entries.*.skillsLimits.maxSkillsPromptChars`
- `agents.entries.*.contextInjection`
- `agents.entries.*.bootstrapMaxChars`
- `agents.entries.*.bootstrapTotalMaxChars`
- `agents.entries.*.contextLimits.*`
### `agents.defaults.startupContext`
Controls the first-turn startup prelude injected on reset/startup model runs.
Bare chat `/new` and `/reset` commands acknowledge the reset without invoking
the model, so they do not load this prelude.
```json5
{
agents: {
defaults: {
startupContext: {
enabled: true,
applyOn: ["new", "reset"],
dailyMemoryDays: 2,
maxFileBytes: 16384,
maxFileChars: 1200,
maxTotalChars: 2800,
},
},
},
}
```
### `agents.defaults.contextLimits`
Shared defaults for bounded runtime context surfaces.
```json5
{
agents: {
defaults: {
contextLimits: {
memoryGetMaxChars: 12000,
postCompactionMaxChars: 1800,
},
},
},
}
```
- `memoryGetMaxChars`: default `memory_get` excerpt cap before truncation
metadata and continuation notice are added.
- When `memory_get` omits `lines`, OpenClaw uses a built-in 120-line window and
then applies `memoryGetMaxChars`.
- Live tool results use a model-context auto cap: `16000` chars below 100K
tokens, `32000` chars at 100K+ tokens, and `64000` chars at 200K+ tokens.
- `postCompactionMaxChars`: AGENTS.md excerpt cap used during post-compaction
refresh injection.
### `agents.entries.*.contextLimits`
Per-agent override for the shared `contextLimits` knobs. Omitted fields inherit
from `agents.defaults.contextLimits`.
```json5
{
agents: {
defaults: {
contextLimits: { memoryGetMaxChars: 12000 },
},
entries: {
"tiny-local": {
contextLimits: {
memoryGetMaxChars: 6000,
},
},
},
},
}
```
### `skills.limits.maxSkillsPromptChars`
Global cap for the compact skills list injected into the system prompt. This
does not affect reading `SKILL.md` files on demand.
```json5
{
skills: { limits: { maxSkillsPromptChars: 18000 } },
}
```
### `agents.entries.*.skillsLimits.maxSkillsPromptChars`
Per-agent override for the skills prompt budget.
```json5
{
agents: {
entries: {
"tiny-local": { skillsLimits: { maxSkillsPromptChars: 6000 } },
},
},
}
```
## `agents.defaults.imageMaxDimensionPx`
Max pixel size for the longest image side in transcript/tool image blocks before provider calls.
Default: `1200`.
Lower values usually reduce vision-token usage and request payload size for screenshot-heavy runs.
Higher values preserve more visual detail.
```json5
{
agents: { defaults: { imageMaxDimensionPx: 1200 } },
}
```
## `agents.defaults.imageQuality`
Image-tool compression/detail preference for images loaded from file paths, URLs, and media references.
Default: `auto`.
OpenClaw adapts the resize ladder to the selected image model. For example, Claude Opus 4.8, OpenAI GPT-6 Astra, Qwen VL, and hosted Llama 4 vision models can use larger images than older/default high-detail vision paths, while multi-image turns are compressed more aggressively in `auto` mode to control token and latency cost.
Values:
- `auto`: adapt to model limits and image count.
- `efficient`: prefer smaller images for lower token and byte usage.
- `balanced`: use the standard middle-ground ladder.
- `high`: preserve more detail for screenshots, diagrams, and document images.
```json5
{
agents: { defaults: { imageQuality: "auto" } },
}
```
## `agents.defaults.userTimezone`
Timezone for message envelopes, queued system events, and the system prompt's local
date context. Falls back to the host timezone.
```json5
{
agents: { defaults: { userTimezone: "America/Chicago" } },
}
```