Reference

Configuration

Skawld’s defaults are designed to disappear. Most apps will never set a config value — but when you need to tune retries, caching, or where state lives on disk, here’s the surface.

#Environment variables

Skawld reads only the provider keys at runtime. The other variables below are conventions used by the bundled examples; the Agent constructor never reads them directly.

env

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
SKAWLD_MODEL=gpt-5             # used by examples; ignored by Agent constructor
SKAWLD_CONFIG_DIR=.skawld      # session store + skills + agents

Variable	Read by
ANTHROPIC_API_KEY	`AnthropicProvider` (falls back to the Anthropic SDK’s own lookup).
OPENAI_API_KEY	`OpenAIChatCompletionsProvider`, `OpenAIResponsesProvider`.
SKAWLD_MODEL	Example apps under `examples/`. Not read by the SDK.
SKAWLD_CONFIG_DIR	Example apps. Use the `configDir` Agent option for programmatic control.

#.skawld directory

By default skawld stores per-project state under .skawld/ in the working directory. Override with configDir on Agent.

Path	Purpose
.skawld/sessions.db	SQLite session store. Conversations, messages, tasks.
.skawld/skills/<name>/SKILL.md	Skill definitions loaded lazily on first session.
.skawld/agents/<name>.md	Subagent definitions loaded lazily on first session.

#Runtime knobs

Every behaviour you might want to tune lives on AgentOptions. The headline knobs:

Option	What it controls
maxRetries	Retry budget for retryable provider errors. Default `5`.
maxOutputTokens	Per-turn output cap. Omitted by default; Anthropic falls back to `32768`, OpenAI omits the field on the wire.
maxTurns	Hard cap on turns per run. Unbounded by default. Hitting it yields a turn-limit result rather than throwing.
cacheTtl	Prompt-cache TTL hint (`"5m"` / `"1h"`). Anthropic-only; OpenAI ignores it.
includePartialMessages	Emit token-level `partial_assistant` deltas. Off by default.
cwd	Working directory passed to every tool execution.