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):

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

API Key Requirement

Warning

Anthropic API key required for Claude SDK backend. Anthropic’s authentication policy prohibits third-party applications from using OAuth tokens from Free/Pro/Max plans. PocketPaw requires an API key from console.anthropic.com. This does not apply when using Ollama or other local providers.

Environment Variables

All settings use the POCKETPAW_ prefix:

# 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:

{
  "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"
}

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.

Tool Policy Configuration

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

# 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 for detailed documentation.

Memory Configuration

# 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:

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

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

Spotify Integration

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

Last updated: April 29, 2026

2 min read

Edit this page

Was this page helpful?