pocketpaw/docs/getting-started/configuration.mdx

---
title: "Configure PocketPaw: Env Variables, API Keys & Settings"
description: "Complete guide to configuring PocketPaw: environment variables with POCKETPAW_ prefix, JSON config file, API keys, channel tokens, tool profiles, and memory settings."
section: Getting Started
ogType: article
keywords: ["environment variables", "config file", "settings", "api keys", "pocketpaw prefix"]
tags: ["configuration", "settings"]
---

# Configure PocketPaw: Env Variables, API Keys & Settings

PocketPaw uses a layered configuration system built on Pydantic Settings.

## Configuration Sources

Configuration is loaded from these sources (in order of precedence):

1. **Environment variables** — Prefixed with `POCKETPAW_`
2. **Config file** — `~/.pocketpaw/config.json`
3. **Web dashboard** — Settings saved through the UI

## API Key Requirement

<Callout type="warning">
  **Anthropic API key required for Claude SDK backend.** Anthropic's [authentication policy](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) prohibits third-party applications from using OAuth tokens from Free/Pro/Max plans. PocketPaw requires an API key from [console.anthropic.com](https://console.anthropic.com/settings/keys). This does not apply when using Ollama or other local providers.
</Callout>

## Environment Variables

All settings use the `POCKETPAW_` prefix:

```bash
# Core
export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..."    # Required for Claude SDK backend
export POCKETPAW_OPENAI_API_KEY="sk-..."
export POCKETPAW_AGENT_BACKEND="claude_agent_sdk"  # or openai_agents, google_adk, codex_cli, opencode, copilot_sdk

# Claude SDK settings (only when agent_backend=claude_agent_sdk)
export POCKETPAW_CLAUDE_SDK_MODEL=""               # empty = auto (recommended)
export POCKETPAW_CLAUDE_SDK_MAX_TURNS=25           # max tool-use loops per query

# Ollama (local models, no API key needed)
export POCKETPAW_LLM_PROVIDER="ollama"             # auto, anthropic, openai, ollama, openrouter, litellm
export POCKETPAW_OLLAMA_HOST="http://localhost:11434"
export POCKETPAW_OLLAMA_MODEL="qwen2.5:7b"

# OpenRouter (100+ models, pay-per-token)
export POCKETPAW_LLM_PROVIDER="openrouter"
export POCKETPAW_OPENROUTER_API_KEY="sk-or-v1-..."
export POCKETPAW_OPENROUTER_MODEL="anthropic/claude-sonnet-4-6"

# LiteLLM (100+ providers via proxy)
export POCKETPAW_LLM_PROVIDER="litellm"
export POCKETPAW_LITELLM_API_BASE="http://localhost:4000"
export POCKETPAW_LITELLM_API_KEY="sk-..."
export POCKETPAW_LITELLM_MODEL="gpt-4o"

# Web Dashboard
export POCKETPAW_WEB_PORT=8888
export POCKETPAW_WEB_HOST="0.0.0.0"

# Telegram
export POCKETPAW_TELEGRAM_TOKEN="your-bot-token"
export POCKETPAW_ALLOWED_TELEGRAM_IDS="123456,789012"

# Discord
export POCKETPAW_DISCORD_BOT_TOKEN="your-discord-token"
export POCKETPAW_DISCORD_ALLOWED_GUILD_IDS="111,222"
export POCKETPAW_DISCORD_ALLOWED_USER_IDS="333,444"

# Slack
export POCKETPAW_SLACK_BOT_TOKEN="xoxb-..."
export POCKETPAW_SLACK_APP_TOKEN="xapp-..."
export POCKETPAW_SLACK_ALLOWED_CHANNEL_IDS="C01,C02"

# WhatsApp Business
export POCKETPAW_WHATSAPP_ACCESS_TOKEN="your-token"
export POCKETPAW_WHATSAPP_PHONE_NUMBER_ID="123456"
export POCKETPAW_WHATSAPP_VERIFY_TOKEN="your-verify-token"
export POCKETPAW_WHATSAPP_ALLOWED_PHONE_NUMBERS="+1234567890"

# WhatsApp Personal
export POCKETPAW_WHATSAPP_MODE="personal"  # or "business"

# Signal
export POCKETPAW_SIGNAL_API_URL="http://localhost:8080"
export POCKETPAW_SIGNAL_PHONE_NUMBER="+1234567890"

# Matrix
export POCKETPAW_MATRIX_HOMESERVER="https://matrix.org"
export POCKETPAW_MATRIX_USER_ID="@bot:matrix.org"
export POCKETPAW_MATRIX_ACCESS_TOKEN="your-token"

# Microsoft Teams
export POCKETPAW_TEAMS_APP_ID="your-app-id"
export POCKETPAW_TEAMS_APP_PASSWORD="your-password"

# Google Chat
export POCKETPAW_GCHAT_PROJECT_ID="your-project-id"
export POCKETPAW_GCHAT_SERVICE_ACCOUNT_KEY="/path/to/key.json"
```

## Config File

The JSON config file at `~/.pocketpaw/config.json` stores all settings:

```json
{
  "anthropic_api_key": "sk-ant-...",
  "agent_backend": "claude_agent_sdk",
  "claude_sdk_model": "",
  "claude_sdk_max_turns": 25,
  "llm_provider": "auto",
  "ollama_host": "http://localhost:11434",
  "ollama_model": "llama3.2",
  "tool_profile": "coding",
  "tools_allow": [],
  "tools_deny": [],
  "smart_routing_enabled": false,
  "web_search_provider": "tavily",
  "tavily_api_key": "tvly-...",
  "mem0_auto_learn": true,
  "mem0_llm_provider": "ollama",
  "mem0_llm_model": "llama3.2"
}
```

<Callout type="info">
  **`claude_sdk_model`**: Leave empty (default) to let Claude Code auto-select the best model. Only set this if you want to force a specific model.
</Callout>

## Tool Policy Configuration

Control which tools are available via profiles and allow/deny lists:

```bash
# Profile: minimal, coding, or full
export POCKETPAW_TOOL_PROFILE="coding"

# Allow specific tools (comma-separated)
export POCKETPAW_TOOLS_ALLOW="web_search,image_gen"

# Deny specific tools (takes precedence over allow)
export POCKETPAW_TOOLS_DENY="shell,write_file"
```

See [Tool Policy](/tools/tool-policy) for detailed documentation.

## Memory Configuration

```bash
# Mem0 semantic memory
export POCKETPAW_MEM0_AUTO_LEARN=true
export POCKETPAW_MEM0_LLM_PROVIDER="ollama"      # or anthropic, openai
export POCKETPAW_MEM0_LLM_MODEL="llama3.2"
export POCKETPAW_MEM0_EMBEDDER_PROVIDER="ollama"  # or openai
export POCKETPAW_MEM0_EMBEDDER_MODEL="nomic-embed-text"
export POCKETPAW_MEM0_VECTOR_STORE="qdrant"
```

## Google Integration

For Gmail, Calendar, Drive, and Docs:

```bash
export POCKETPAW_GOOGLE_CLIENT_ID="your-client-id"
export POCKETPAW_GOOGLE_CLIENT_SECRET="your-secret"
```

OAuth tokens are stored in `~/.pocketpaw/tokens/`.

## Spotify Integration

```bash
export POCKETPAW_SPOTIFY_CLIENT_ID="your-client-id"
export POCKETPAW_SPOTIFY_CLIENT_SECRET="your-secret"
```

## Data Directory

PocketPaw stores all data in `~/.pocketpaw/`:

```
~/.pocketpaw/
├── config.json          # Configuration file
├── memory/              # Session history and facts
├── identity/
│   └── USER.md          # User profile (auto-created)
├── skills/              # Custom skill definitions
├── tokens/              # OAuth tokens
├── audit.jsonl          # Security audit log
└── mcp.json             # MCP server configuration
```