# Configuration Reference

This document describes all configuration options for OCLAWMA.

## Table of Contents

- [Environment Variables](#environment-variables)
- [Configuration File](#configuration-file)
- [Provider Configuration](#provider-configuration)
- [Session Settings](#session-settings)
- [Safety Levels](#safety-levels)
- [Context Budget](#context-budget)
- [Skill Configuration](#skill-configuration)

## Environment Variables

### Core Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `OCLAWMA_HOME` | `~/.oclawma` | OCLAWMA home directory |
| `OCLAWMA_CONFIG` | `$OCLAWMA_HOME/config.yaml` | Config file path |
| `OCLAWMA_LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
| `OCLAWMA_CACHE_DIR` | `~/.cache/oclawma` | Cache directory |

### Provider Settings

| Variable | Required | Description |
|----------|----------|-------------|
| `KIMI_API_KEY` | For Kimi provider | API key for Kimi cloud provider |
| `OLLAMA_HOST` | No | Ollama server URL (default: http://localhost:11434) |
| `OLLAMA_MODEL` | No | Default Ollama model (default: qwen2.5:3b) |

### Session Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `OCLAWMA_DEFAULT_PROVIDER` | `ollama` | Default provider (ollama, kimi, auto) |
| `OCLAWMA_DEFAULT_MODEL` | `qwen2.5:3b` | Default model name |
| `OCLAWMA_CONTEXT_LIMIT` | `8192` | Default context token limit |
| `OCLAWMA_SAFETY_LEVEL` | `normal` | Safety level (strict, normal, permissive) |

### Skill Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `OCLAWMA_SKILLS_PATH` | `~/.oclawma/skills` | Path to local skills directory |
| `OCLAWMA_SKILL_CACHE` | `~/.cache/oclawma/skills` | Skill token cache directory |

## Configuration File

OCLAWMA looks for a YAML configuration file at `~/.oclawma/config.yaml`:

```yaml
# ~/.oclawma/config.yaml

# Core settings
log_level: INFO
cache_dir: ~/.cache/oclawma

# Default provider settings
default_provider: auto
default_model: qwen2.5:3b

# Provider-specific settings
providers:
  ollama:
    base_url: http://localhost:11434
    default_model: qwen2.5:3b
    timeout: 30
    
  kimi:
    api_key: ${KIMI_API_KEY}  # Reference env var
    default_model: k2.5
    timeout: 60
    max_retries: 3

# Session settings
session:
  context_limit: 8192
  auto_summarize: true
  summary_threshold: 0.75
  safety_level: normal

# Context budget settings
context_budget:
  warning_threshold: 0.75  # Warn at 75% usage
  critical_threshold: 0.87  # Critical at 87% usage
  strict_mode: false  # Allow over-budget by default

# Tool settings
tools:
  exec:
    timeout: 30
    allowed_commands: []  # Empty = all allowed at safety level
    blocked_commands: ["rm -rf /", "sudo"]
  
  read:
    max_file_size: 1048576  # 1MB
    blocked_patterns: ["*.pem", "*.key"]
  
  write:
    confirm_overwrite: true
    blocked_patterns: ["*.pem", "*.key"]

# Skill settings
skills:
  auto_discover: true
  paths:
    - ~/.oclawma/skills
  preload: []  # Skills to preload
```

## Provider Configuration

### Ollama Provider

```yaml
providers:
  ollama:
    base_url: http://localhost:11434
    default_model: qwen2.5:3b
    timeout: 30
    keep_alive: 300  # Keep model loaded for 5 minutes
```

| Option | Default | Description |
|--------|---------|-------------|
| `base_url` | `http://localhost:11434` | Ollama server URL |
| `default_model` | `qwen2.5:3b` | Default model to use |
| `timeout` | `30` | Request timeout in seconds |
| `keep_alive` | `300` | How long to keep model loaded |

### Kimi Provider

```yaml
providers:
  kimi:
    api_key: ${KIMI_API_KEY}
    default_model: k2.5
    timeout: 60
    max_retries: 3
    retry_delay: 1.0
```

| Option | Default | Description |
|--------|---------|-------------|
| `api_key` | (required) | Kimi API key |
| `default_model` | `k2.5` | Default model (k2.5, k1.5) |
| `timeout` | `60` | Request timeout in seconds |
| `max_retries` | `3` | Number of retries on failure |
| `retry_delay` | `1.0` | Delay between retries in seconds |

### Auto Provider

The auto provider combines local and cloud providers:

```yaml
providers:
  auto:
    primary: ollama
    fallback: kimi
    fallback_threshold: 0.9  # Use fallback at 90% context
    fallback_models:
      - qwen2.5:3b
      - k2.5
```

| Option | Default | Description |
|--------|---------|-------------|
| `primary` | `ollama` | Primary provider |
| `fallback` | `kimi` | Fallback provider |
| `fallback_threshold` | `0.9` | Context usage to trigger fallback |

## Session Settings

```yaml
session:
  context_limit: 8192
  auto_summarize: true
  summary_threshold: 0.75
  max_iterations: 5
  temperature: 0.7
  safety_level: normal
```

| Setting | Default | Description |
|---------|---------|-------------|
| `context_limit` | `8192` | Maximum tokens in context |
| `auto_summarize` | `true` | Auto-summarize when budget high |
| `summary_threshold` | `0.75` | Trigger summarization at this usage |
| `max_iterations` | `5` | Max tool call iterations per message |
| `temperature` | `0.7` | LLM temperature |
| `safety_level` | `normal` | Default safety level |

## Safety Levels

Safety levels control what tools can do:

### Strict

```yaml
session:
  safety_level: strict
```

- No shell command execution
- Read-only file access
- No network access
- Confirm all write operations

### Normal (Default)

```yaml
session:
  safety_level: normal
```

- Allowed: safe shell commands
- Allowed: file read/write
- Blocked: dangerous commands (sudo, rm -rf /)
- Confirm: destructive operations

### Permissive

```yaml
session:
  safety_level: permissive
```

- Allowed: most shell commands
- Allowed: all file operations
- Confirm: only potentially destructive
- Override with `--yes` flag

## Context Budget

Context budget tracks token usage:

```yaml
context_budget:
  warning_threshold: 0.75
  critical_threshold: 0.87
  strict_mode: false
  compression_enabled: true
  compression_ratio: 0.5
```

| Setting | Default | Description |
|---------|---------|-------------|
| `warning_threshold` | `0.75` | Show warning at this usage |
| `critical_threshold` | `0.87` | Critical warning at this usage |
| `strict_mode` | `false` | Enforce hard limit |
| `compression_enabled` | `true` | Allow context compression |
| `compression_ratio` | `0.5` | Target compression ratio |

## Skill Configuration

```yaml
skills:
  auto_discover: true
  paths:
    - ~/.oclawma/skills
    - /usr/share/oclawma/skills
  preload: []
  blocked: []
  
  # Per-skill config
  docker:
    socket: /var/run/docker.sock
    timeout: 30
  
  kubernetes:
    kubeconfig: ~/.kube/config
    context: default
```

## Command-Line Overrides

Most config options can be overridden via CLI:

```bash
# Override provider
oclawma run --provider kimi

# Override model
oclawma run --model llama3.2:latest

# Override context limit
oclawma run --context-limit 16384

# Override safety level
oclawma run --safety-level strict

# Override Ollama URL
oclawma run --base-url http://remote-server:11434
```

## Configuration Precedence

Settings are applied in this order (later overrides earlier):

1. Default values
2. Config file (`~/.oclawma/config.yaml`)
3. Environment variables
4. Command-line arguments

## Example Configurations

### Minimal Config

```yaml
# ~/.oclawma/config.yaml
default_provider: ollama
default_model: qwen2.5:3b
```

### Development Config

```yaml
# ~/.oclawma/config.yaml
log_level: DEBUG
cache_dir: /tmp/oclawma-cache

session:
  safety_level: permissive
  auto_summarize: false

providers:
  ollama:
    base_url: http://localhost:11434
    default_model: codellama:7b
```

### Production Config

```yaml
# ~/.oclawma/config.yaml
log_level: WARNING

session:
  safety_level: strict
  context_limit: 32768

providers:
  auto:
    primary: ollama
    fallback: kimi
    fallback_threshold: 0.85
```
