Installation & Setup Usage Guide Configuration Agents & Tools MCP Servers Session Sharing ACP Integration System Architecture Embedding Guide API Reference Overview Configuration Caching Overview Payments Integration Guide OpenClaw Plugin

Configuration

Settings, config files, and environment variables.

Configuration Priority

otto checks in this order:

Injected config — createEmbeddedApp({...}) (highest)
Environment variables — OPENAI_API_KEY, etc.
Config files — ~/.config/otto/, .otto/
Built-in defaults

Directory Structure

~/.config/otto/           # Global configuration
├── auth.json            # API keys (0600 permissions)
└── config.json          # Global defaults

.otto/                    # Project-specific
├── otto.sqlite           # Local conversation history
├── config.json          # Project configuration
├── agents.json          # Agent customizations
├── agents/              # Custom agent prompts
│   └── <agent-name>/
│       └── agent.md
├── commands/            # Custom command definitions
├── tools/               # Custom tool implementations
└── artifacts/           # Large outputs

Configuration Files

Global Auth

~/.config/otto/auth.json — API keys stored securely (file permissions: 0600):

{
  "openai": {
    "type": "api",
    "key": "sk-..."
  },
  "anthropic": {
    "type": "api",
    "key": "sk-ant-..."
  }
}

Global Config

~/.config/otto/config.json — User-wide defaults:

{
  "defaults": {
    "provider": "anthropic",
    "model": "claude-sonnet-4",
    "agent": "general"
  }
}

Project Config

.otto/config.json — Project-specific overrides:

{
  "defaults": {
    "provider": "openai",
    "model": "gpt-4",
    "agent": "build"
  }
}

Agent Customization

.otto/agents.json:

{
  "build": {
    "tools": ["read", "write", "bash", "git_*"],
    "prompt": ".otto/agents/build/agent.md"
  },
  "test": {
    "tools": ["read", "bash"],
    "appendTools": ["progress_update"]
  }
}

Environment Variables

# Provider API keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_GENERATIVE_AI_API_KEY=...
OPENROUTER_API_KEY=...

# Optional: Default provider/model/agent
OTTO_PROVIDER=openai
OTTO_MODEL=gpt-4
OTTO_AGENT=build

Configuration Scenarios

Mode	Injected	Env Vars	Files	Use Case
CLI	-	-	Yes	Desktop development
CI/CD	-	Yes	-	GitHub Actions, Docker
Embedded	Yes	-	-	VSCode extension, SaaS
Hybrid	Partial	API keys	Defaults	Mix of all