Global Configuration

AI Provider Configuration

Kirby Copilot supports multiple AI providers. You must configure at least one provider with valid credentials for the plugin to function.

Basic Provider Setup

All provider configurations are nested under the johannschopplich.copilot key:

return [
    'johannschopplich.copilot' => [
        'provider' => 'google', // Choose your primary provider
        'providers' => [
            'google' => [
                'apiKey' => 'YOUR_API_KEY',
                // Model for content generation
                'model' => 'gemini-3.1-pro-preview',
                // Model for writer field inline suggestions
                'completionModel' => 'gemini-3-flash-preview'
            ]
        ]
    ]
];

Each provider supports two model configurations:

• model: Used for content generation (text, blocks, layouts).
• completionModel: Used for inline suggestions in writer fields (should be fast and lightweight).

Provider Examples

return [
    'johannschopplich.copilot' => [
        'provider' => 'openai',
        'providers' => [
            'openai' => [
                'apiKey' => env('OPENAI_API_KEY'),
                'model' => 'gpt-5.4-mini'
            ]
        ]
    ]
];

return [
    'johannschopplich.copilot' => [
        'provider' => 'google',
        'providers' => [
            'google' => [
                'apiKey' => env('GOOGLE_API_KEY'),
                'model' => 'gemini-3.1-pro-preview'
            ]
        ]
    ]
];

return [
    'johannschopplich.copilot' => [
        'provider' => 'anthropic',
        'providers' => [
            'anthropic' => [
                'apiKey' => env('ANTHROPIC_API_KEY'),
                'model' => 'claude-sonnet-4-6'
            ]
        ]
    ]
];

return [
    'johannschopplich.copilot' => [
        'provider' => 'mistral',
        'providers' => [
            'mistral' => [
                'apiKey' => env('MISTRAL_API_KEY'),
                'model' => 'mistral-small-latest',
                // Optional: custom base URL
                'baseUrl' => 'https://api.mistral.ai'
            ]
        ]
    ]
];

Default Models

If you do not specify a model or completionModel, Kirby Copilot uses sensible defaults for each provider:

AI Generation Settings

systemPrompt String

Global system prompt that defines how the AI should structure and approach content generation. This can be overridden by view button props or section configuration.

Kirby Copilot ships with a well-crafted default system prompt that handles response formatting for different field types (text, markdown, rich-text) and preserves formatting when working with selected text. In most cases, the default works out of the box and customization is not necessary.

excludedBlocks Array

Specify block types to exclude from structured data generation in blocks and layout fields. This is useful for custom block types for which AI generation is not desired.

Default: [] (no blocks excluded)

return [
    'johannschopplich.copilot' => [
        'excludedBlocks' => ['custom-form', 'widget', 'advertisement'],
    ]
];

reasoningEffort String

Controls the depth of reasoning applied during content generation. This property works with all reasoning-capable models across providers (GPT-5, Gemini 3, Claude 4).

Default: low
Options: none, low, medium, high

return [
    'johannschopplich.copilot' => [
        'reasoningEffort' => 'medium'
    ]
];

completion Array | Boolean

Controls inline suggestions in writer fields. Inline suggestions are enabled by default for all writer fields.

Default: ['debounce' => 1000]

To disable inline suggestions globally:

return [
    'johannschopplich.copilot' => [
        'completion' => false
    ]
];

To customize the debounce timing (minimum 500ms):

return [
    'johannschopplich.copilot' => [
        'completion' => [
            'debounce' => 1500 // Wait 1.5 seconds after typing stops
        ]
    ]
];

promptTemplates Array

Define prompt templates that appear for all Panel users. Config-defined templates are read-only and displayed alongside user-created templates.

Default: [] (uses built-in defaults)

return [
    'johannschopplich.copilot' => [
        'promptTemplates' => [
            [
                'label' => 'Apply House Style',
                'prompt' => 'Format the text according to our editorial style: artist names in bold, album titles in italics, use curly quotation marks.'
            ],
            [
                'label' => 'Add Spotify Links',
                'prompt' => 'Find all album titles in the text and wrap them in Markdown links to their Spotify pages.'
            ]
        ]
    ]
];

return [
    'johannschopplich.copilot' => [
        'promptTemplates' => [
            [
                'label' => [
                    'en' => 'Apply House Style',
                    'de' => 'Redaktionsstil anwenden'
                ],
                'prompt' => [
                    'en' => 'Format the text according to our editorial style: artist names in bold, album titles in italics, use curly quotation marks.',
                    'de' => 'Formatiere den Text nach unserem Redaktionsstil: Künstlernamen fett, Albumtitel kursiv, typografische Anführungszeichen verwenden.'
                ]
            ]
        ]
    ]
];

skills Array since v3.7.0

Define reusable prompt instructions – tone, style, or house rules – that editors invoke via @skill:// mentions in the prompt editor.

Default: []

return [
    'johannschopplich.copilot' => [
        'skills' => [
            [
                'id' => 'brand-voice',
                'label' => 'Brand Voice',
                'instructions' => 'Write in a warm, conversational tone. Avoid corporate jargon. Prefer short sentences.'
            ]
        ]
    ]
];

return [
    'johannschopplich.copilot' => [
        'skills' => [
            [
                'id' => 'brand-voice',
                'label' => [
                    'en' => 'Brand Voice',
                    'de' => 'Markenstimme'
                ],
                'instructions' => [
                    'en' => 'Write in a warm, conversational tone. Avoid corporate jargon. Prefer short sentences.',
                    'de' => 'Schreibe in einem warmen, gesprächigen Ton. Vermeide Fachjargon. Bevorzuge kurze Sätze.'
                ]
            ]
        ]
    ]
];

baseUrl String

Custom base URL for the AI provider API. This property is configured per provider alongside apiKey and model. Useful when using proxy services, custom API endpoints, or self-hosted AI services like llama.cpp.

Default: Provider-specific default URL

return [
    'johannschopplich.copilot' => [
        'provider' => 'openai',
        'providers' => [
            'openai' => [
                'apiKey' => env('OPENAI_API_KEY'),
                'model' => 'llama-3.2-3b-instruct',
                'baseUrl' => 'https://llama.example.com/v1'
            ]
        ]
    ]
];

api String since v3.6.0

Selects the OpenAI API variant. Defaults to the Responses API (/v1/responses). Set to chat when your endpoint only exposes /v1/chat/completions.

Default: responses
Options: chat, responses

return [
    'johannschopplich.copilot' => [
        'provider' => 'openai',
        'providers' => [
            'openai' => [
                'apiKey' => env('OPENAI_API_KEY'),
                'baseUrl' => 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat',
                'model' => 'openai/gpt-5.4',
                'api' => 'chat'
            ]
        ]
    ]
];

Compatibility

Not listed? Check your gateway's docs for /v1/responses support – if absent, set api: 'chat'.

Routing Multiple Providers Through One Gateway

Cloudflare AI Gateway's Unified API (…/compat) routes many providers through the OpenAI SDK shape using {provider}/{model} model IDs. This lets you access Gemini, Claude, OpenAI, and more through a single endpoint – handy for unified observability, caching, and rate limiting across providers.

Because /compat is Chat Completions only, api: 'chat' is required.

return [
    'johannschopplich.copilot' => [
        'provider' => 'openai',
        'providers' => [
            'openai' => [
                'apiKey' => env('GOOGLE_AI_STUDIO_API_KEY'),
                'baseUrl' => 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat',
                'model' => 'google-ai-studio/gemini-2.5-flash',
                // Required when the gateway prefix doesn't match the provider
                'completionModel' => 'google-ai-studio/gemini-2.5-flash-lite',
                'api' => 'chat'
            ]
        ]
    ]
];

Limitations

Global Defaults

You can set global defaults that apply to both view buttons and sections. These can be overridden in individual blueprints.

Available Global Defaults

For detailed descriptions of each property, see the View Button & Section Configuration page. The following properties can be set globally:

systemPrompt String

Default system prompt that controls how the AI structures and formats generated content across all view buttons and fields.

userPrompt String

Default user prompt that appears when generation dialogs open.

logLevel String

Default logging level for debugging AI generation. Options: error, warn, info, debug.

Basic Global Configuration

return [
    'johannschopplich.copilot' => [
        'provider' => 'google', // Primary provider
        'providers' => [
            'google' => [
                'apiKey' => env('GOOGLE_API_KEY'),
                'model' => 'gemini-3.1-pro-preview'
            ]
        ],

        // Global Defaults
        'logLevel' => 'info',
        'excludedBlocks' => ['custom-form']
    ]
];

Security

All AI provider requests are routed through a server-side proxy since v3. API keys are never exposed in browser network requests and stay hidden from Panel users. No additional configuration required – the proxy is enabled automatically.

Dynamic API Keys since v3.1.0

For advanced use cases, you can provide a closure that resolves the API key dynamically at runtime. The closure receives the Kirby instance as its first argument, allowing user-specific or context-dependent API keys.

return [
    'johannschopplich.copilot' => [
        'providers' => [
            'openai' => [
                'apiKey' => function (\Kirby\Cms\App $kirby) {
                    // Example: Return different keys based on user role
                    $user = $kirby->user();

                    if ($user?->role()->name() === 'admin') {
                        return env('OPENAI_API_KEY_ADMIN');
                    }

                    return env('OPENAI_API_KEY_USER');
                }
            ]
        ]
    ]
];

This is useful for scenarios like:

• Different API keys or rate limits per user role.
• Fetching keys from external services or databases.
• Multi-tenant setups with client-specific credentials.