# Configuration Guide

Complete guide to configuring planck-claw.

planck-claw is configured programmatically by passing a config object at agent creation time. The config is validated with Zod schemas — invalid values produce clear error messages.

## Configuration Shape

```typescript
{
  providers: { ... },   // OpenRouter credentials
  agents:    { ... },   // Model and behavior settings
  tools:     { ... },   // Tool execution restrictions
}
```

## Provider Configuration

planck-claw uses **OpenRouter** as its sole LLM provider. OpenRouter acts as a gateway, giving you access to models from Anthropic, OpenAI, Google, Meta, DeepSeek, and many others through a single API key.

```json
{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-YOUR_KEY_HERE"
    }
  }
}
```

Get your key: https://openrouter.ai/keys

### Custom Base URL

If you need to point at a proxy or alternative endpoint:

```json
{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-YOUR_KEY_HERE",
      "apiBase": "https://your-proxy.example.com/v1"
    }
  }
}
```

## Agent Configuration

Configure agent behavior and defaults:

```json
{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.7,
      "maxTokens": 4096,
      "systemPrompt": "You are a helpful assistant."
    }
  }
}
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `model` | string | — | OpenRouter model identifier |
| `temperature` | number | 0.7 | Randomness (0.0 = deterministic, 2.0 = very creative) |
| `maxTokens` | number | 4096 | Maximum tokens in response |
| `systemPrompt` | string | — | Custom system prompt |

### Popular Models (via OpenRouter)

- `anthropic/claude-opus-4-5` — Most capable
- `anthropic/claude-sonnet-4-5` — Balanced
- `openai/gpt-4-turbo` — GPT-4 Turbo
- `google/gemini-pro-1.5` — Gemini Pro
- `meta-llama/llama-3.1-405b` — Llama 3.1
- `deepseek/deepseek-chat` — DeepSeek

Full list: [openrouter.ai/models](https://openrouter.ai/models)

## Tools Configuration

Configure tool execution behavior:

```json
{
  "tools": {
    "restrictToWorkspace": false,
    "allowedCommands": ["git", "npm"],
    "deniedCommands": ["rm -rf", "sudo"]
  }
}
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `restrictToWorkspace` | boolean | false | Restrict file operations to the working directory |
| `allowedCommands` | string[] | — | Whitelist of shell commands (when set, only these run) |
| `deniedCommands` | string[] | — | Blacklist of shell commands (always blocked) |

### Security Best Practices

For production use:

```json
{
  "tools": {
    "restrictToWorkspace": true,
    "deniedCommands": [
      "rm -rf",
      "sudo",
      "chmod",
      "chown",
      "mkfs",
      "dd"
    ]
  }
}
```

## Environment Variables

You can supply the API key via environment variable instead of (or in addition to) the config object:

```bash
export OPENROUTER_API_KEY="sk-or-v1-..."
```

Other supported variables:

```bash
export LOG_LEVEL="debug"       # debug, info, warn, error
export NODE_ENV="production"   # production, development
```

Environment variables take precedence over config object values.

## Complete Example

```json
{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-YOUR_KEY_HERE"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.7,
      "maxTokens": 4096,
      "systemPrompt": "You are a helpful AI assistant specialized in software development."
    }
  },
  "tools": {
    "restrictToWorkspace": false,
    "deniedCommands": [
      "rm -rf /",
      "sudo",
      "mkfs"
    ]
  }
}
```

## Validation

Configuration is validated using Zod schemas at startup. Invalid values produce clear error messages describing what's wrong and what's expected.

## Tips

1. **Start simple** — just `providers.openrouter.apiKey` and `agents.defaults.model` is enough to get going
2. **Use environment variables** for API keys in shared/deployed environments
3. **Restrict tools** in production to limit what the agent can execute
4. **Check logs** — Pino logs are available for troubleshooting

## Next Steps

- [Quick Start](QUICKSTART.md) — Get up and running
- [Architecture](ARCHITECTURE.md) — System design and internals