clawft

Configuration

Complete configuration reference for clawft including file location, all config keys with types and defaults, and environment variables.

Config File Location

The runtime resolves configuration through a three-step discovery chain, stopping at the first match:

PrioritySourceNotes
1CLAWFT_CONFIG environment variableAbsolute path to a JSON file
2~/.clawft/config.jsonRecommended location
3~/.nanobot/config.jsonLegacy fallback for migration

If no file is found, all values use compiled-in defaults (equivalent to {}).

Inspect the resolved configuration:

weft config show              # full config as JSON
weft config section agents    # single section
weft config section gateway

Config File Format

The configuration file accepts both snake_case and camelCase keys. Keys are normalized to snake_case internally. Unknown fields are silently ignored for forward compatibility.

Root Structure

{
  "agents": { },
  "providers": { },
  "channels": { },
  "gateway": { },
  "routing": { },
  "tools": { },
  "delegation": { },
  "voice": { }
}

agents.defaults

Default settings applied to every agent instance.

FieldTypeDefaultDescription
modelstring"anthropic/claude-opus-4-5"LLM model using provider/model syntax
workspacestring"~/.nanobot/workspace"Working directory for file tools. Tilde expanded at runtime.
max_tokensinteger8192Maximum tokens in a single LLM response
temperaturefloat0.7Sampling temperature (0.0 = deterministic, 1.0 = creative)
max_tool_iterationsinteger20Maximum tool-use rounds per message turn
memory_windowinteger50Number of recent messages included in context
{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20,
      "memory_window": 50
    }
  }
}

providers

Credentials and endpoint overrides for LLM providers. API keys should be set via environment variables rather than hardcoded in configuration files.

Each provider entry has the same shape:

FieldTypeDefaultDescription
api_keystring""API key (prefer env vars instead)
api_basestring or nullnullBase URL override for proxies or self-hosted endpoints
extra_headersobject{}Additional HTTP headers sent with every request

Built-in Provider Routing

ProviderPrefixAPI Key Env VarBase URL
OpenAIopenai/OPENAI_API_KEYhttps://api.openai.com/v1
Anthropicanthropic/ANTHROPIC_API_KEYhttps://api.anthropic.com/v1
Groqgroq/GROQ_API_KEYhttps://api.groq.com/openai/v1
DeepSeekdeepseek/DEEPSEEK_API_KEYhttps://api.deepseek.com/v1
Mistralmistral/MISTRAL_API_KEYhttps://api.mistral.ai/v1
Togethertogether/TOGETHER_API_KEYhttps://api.together.xyz/v1
OpenRouteropenrouter/OPENROUTER_API_KEYhttps://openrouter.ai/api/v1
Geminigemini/GOOGLE_GEMINI_API_KEYhttps://generativelanguage.googleapis.com/v1beta/openai
xAIxai/XAI_API_KEYhttps://api.x.ai/v1

gateway

HTTP server and heartbeat settings.

FieldTypeDefaultDescription
hoststring"0.0.0.0"Bind address
portinteger18790Listen port
heartbeat_interval_minutesinteger0Minutes between heartbeat messages. 0 disables.
heartbeat_promptstring"heartbeat"Prompt text sent on each heartbeat tick

channels

Each channel has an enabled boolean that defaults to false. Only enabled channels are started at runtime.

channels.telegram

FieldTypeDefaultDescription
enabledbooleanfalseEnable Telegram
tokenstring""Bot token from @BotFather
token_envstring/nullnullEnv var holding the token (used when token is empty)
allow_fromstring[][]Allowed user IDs. Empty = allow all.
proxystring/nullnullHTTP/SOCKS5 proxy URL

channels.slack

FieldTypeDefaultDescription
enabledbooleanfalseEnable Slack
bot_tokenstring""Bot User OAuth Token (xoxb-...)
app_tokenstring""App-level token for Socket Mode (xapp-...)
modestring"socket"Connection mode
group_policystring"mention"Group policy: "mention", "open", "allowlist"
group_allow_fromstring[][]Channel IDs for allowlist policy
dm.enabledbooleantrueAccept direct messages
dm.policystring"open"DM policy: "open" or "allowlist"
dm.allow_fromstring[][]User IDs for allowlist DM policy

channels.discord

FieldTypeDefaultDescription
enabledbooleanfalseEnable Discord
tokenstring""Bot token from Developer Portal
allow_fromstring[][]Allowed user IDs. Empty = allow all.
gateway_urlstring"wss://gateway.discord.gg/?v=10&encoding=json"Gateway URL
intentsinteger37377Gateway intents bitmask

routing

Controls model selection, cost management, and per-user permissions. When omitted, defaults to mode = "static" (single model from agents.defaults.model).

FieldTypeDefaultDescription
modestring"static""static" or "tiered"
tiersarray[]Model tier definitions
selection_strategystringnull"preference_order", "round_robin", "lowest_cost", "random"
fallback_modelstringnullFallback model when all tiers exhausted

routing.tiers

Each tier groups models at a similar cost/capability level:

FieldTypeDescription
namestringTier name (e.g., "free", "standard", "premium")
modelsstring[]Models in preference order ("provider/model")
complexity_range[float, float]Complexity range (0.0-1.0)
cost_per_1k_tokensfloatApproximate cost per 1K tokens in USD
max_context_tokensintegerMaximum context window size

routing.permissions

Per-user and per-channel permission levels:

{
  "routing": {
    "permissions": {
      "users": {
        "user_id_123": { "level": 2 }
      },
      "channels": {
        "cli": { "level": 2 },
        "discord": { "level": 1 }
      }
    }
  }
}

routing.cost_budgets

FieldTypeDefaultDescription
global_daily_limit_usdfloat50.0Daily spend limit
global_monthly_limit_usdfloat500.0Monthly spend limit
tracking_persistencebooleantruePersist cost tracking across restarts

routing.rate_limiting

FieldTypeDefaultDescription
window_secondsinteger60Rate limit window
strategystring"sliding_window"Rate limiting strategy
global_rate_limit_rpminteger0Global rate limit (0 = unlimited)

tools

FieldTypeDefaultDescription
restrict_to_workspacebooleanfalseSandbox all file tools to workspace

tools.web.search

FieldTypeDefaultDescription
api_keystring""Search provider API key
max_resultsinteger5Maximum search results

tools.exec

FieldTypeDefaultDescription
timeoutinteger60Command execution timeout in seconds

tools.commandPolicy

FieldTypeDefaultDescription
modestring"allowlist""allowlist" or "denylist"
allowliststring[][]Permitted basenames (empty = 17 built-in defaults)
denyliststring[][]Blocked patterns for denylist mode

tools.urlPolicy

FieldTypeDefaultDescription
enabledbooleantrueWhether URL safety checks are active
allowPrivatebooleanfalseAllow requests to private IP ranges
allowedDomainsstring[][]Domains that bypass all safety checks
blockedDomainsstring[][]Domains that are always blocked

tools.mcp_servers

External MCP server configurations. Each entry specifies a command (stdio) or URL (HTTP):

{
  "tools": {
    "mcp_servers": {
      "my_server": {
        "command": "npx",
        "args": ["-y", "my-mcp-server"],
        "internal_only": false
      }
    }
  }
}
FieldTypeDefaultDescription
commandstring""Command to spawn (stdio transport)
argsstring[][]Command arguments
envobject{}Environment variables for the child process
urlstring""URL endpoint (HTTP transport)
internal_onlybooleantrueWhen true, tools are not registered in the ToolRegistry

voice

FieldTypeDefaultDescription
enabledbooleanfalseEnable voice features globally

voice.tts

FieldTypeDefaultDescription
providerstring"browser""browser", "openai", or "elevenlabs"
modelstringvariesTTS model
voicestringvariesVoice ID
speedfloat1.0Speed multiplier (0.25 - 4.0)

voice.stt

FieldTypeDefaultDescription
enabledbooleantrueEnable speech-to-text
languagestring""Language code. Empty = auto-detect.

voice.vad

FieldTypeDefaultDescription
thresholdfloat0.5VAD activation threshold (0.0 - 1.0)
silence_timeout_msinteger1500Silence duration before speech end

voice.wake

FieldTypeDefaultDescription
enabledbooleanfalseEnable wake word detection
phrasestring"hey weft"Wake word phrase

Environment Variables

Key environment variables used by clawft:

VariablePurpose
CLAWFT_CONFIGOverride config file path
RUST_LOGOverride log level (e.g., debug, info, clawft_llm=debug)
OPENAI_API_KEYOpenAI API key
ANTHROPIC_API_KEYAnthropic API key
GROQ_API_KEYGroq API key
DEEPSEEK_API_KEYDeepSeek API key
MISTRAL_API_KEYMistral API key
TOGETHER_API_KEYTogether API key
OPENROUTER_API_KEYOpenRouter API key
GOOGLE_GEMINI_API_KEYGoogle Gemini API key
XAI_API_KEYxAI API key
ELEVENLABS_API_KEYElevenLabs TTS API key

CLI Reference

Complete command-line reference for the weft binary, covering all subcommands, flags, and examples.

Browser Mode

Run clawft in the browser via WebAssembly, including build instructions, API reference, and deployment.

On this page

Config File LocationConfig File FormatRoot Structureagents.defaultsprovidersBuilt-in Provider Routinggatewaychannelschannels.telegramchannels.slackchannels.discordroutingrouting.tiersrouting.permissionsrouting.cost_budgetsrouting.rate_limitingtoolstools.web.searchtools.exectools.commandPolicytools.urlPolicytools.mcp_serversvoicevoice.ttsvoice.sttvoice.vadvoice.wakeEnvironment Variables