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-google-api-key',
                // Model for content generation
                'model' => 'gemini-3.8-flash',
                // Model for writer field inline suggestions
                'completionModel' => 'gemini-3.5-flash-lite'
            ]
        ]
    ]
];

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' => 'your-openai-api-key',
                'model' => 'gpt-5.6-terra'
            ]
        ]
    ]
];

return [
    'johannschopplich.copilot' => [
        'provider' => 'google',
        'providers' => [
            'google' => [
                'apiKey' => 'your-google-api-key',
                'model' => 'gemini-3.8-flash'
            ]
        ]
    ]
];

return [
    'johannschopplich.copilot' => [
        'provider' => 'anthropic',
        'providers' => [
            'anthropic' => [
                'apiKey' => 'your-anthropic-api-key',
                'model' => 'claude-sonnet-5'
            ]
        ]
    ]
];

return [
    'johannschopplich.copilot' => [
        'provider' => 'mistral',
        'providers' => [
            'mistral' => [
                'apiKey' => 'your-mistral-api-key',
                'model' => 'mistral-medium-latest',
                // Optional: custom base URL
                'baseUrl' => 'https://api.mistral.ai/v1'
            ]
        ]
    ]
];

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 model should structure and approach content generation. This can be overridden by view button props or section configuration.

The default prompt formats the response per field type and preserves formatting in a selection – override it only when your project needs different rules.

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. Configure the effort once – it is translated to each provider's native reasoning controls automatically. Models without reasoning support simply ignore the setting.

Default: low
Options: provider-default, none, minimal, low, medium, high, xhigh

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

Use provider-default to let the provider pick its own reasoning depth – equivalent to not sending a reasoning setting at all. Not every model supports every level; providers clamp unsupported values to the nearest supported one.

completion Array | Boolean

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

Default: ['debounce' => 1000]

Set it to false to stop ghost text from appearing on its own. The manual trigger, ,, keeps working:

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:// references 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' => 'your-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 the Panel calls. Defaults to the Responses API (/v1/responses). Set to chat when your endpoint only exposes /v1/chat/completions. PHP runs through OpenAIProvider always use Chat Completions and ignore this option.

Default: responses
Options: chat, responses

return [
    'johannschopplich.copilot' => [
        'provider' => 'openai',
        'providers' => [
            'openai' => [
                'apiKey' => 'your-openai-api-key',
                'baseUrl' => 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat',
                'model' => 'openai/gpt-5.6-terra',
                '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' => 'your-google-ai-studio-api-key',
                'baseUrl' => 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat',
                'model' => 'google-ai-studio/gemini-3.8-flash',
                // Required when the gateway prefix doesn't match the provider
                'completionModel' => 'google-ai-studio/gemini-3.5-flash-lite',
                'api' => 'chat'
            ]
        ]
    ]
];

Limitations

timeout Integer since v3.12.0

Seconds a single request to the provider may take before it counts as failed. Configured per provider alongside apiKey and model. Applies to PHP runs through Client; Panel requests go through the proxy, which bounds them on its own. Anything but a positive integer falls back to the default.

Default: 120

Raise it for long structured-output runs against a slow endpoint, lower it for batch scripts that should fail fast:

return [
    'johannschopplich.copilot' => [
        'provider' => 'google',
        'providers' => [
            'google' => [
                'apiKey' => 'your-google-api-key',
                'model' => 'gemini-3.8-flash',
                'timeout' => 30
            ]
        ]
    ]
];

options Array

A map the Panel passes to the AI SDK as this provider's options with every request, keyed by the option names the SDK defines for that provider. Configured per provider alongside apiKey and model. The PHP Client ignores it; request parameters for PHP runs sit beside it as provider-specific options.

Default: none

Shorter output from every generation, without touching a prompt:

return [
    'johannschopplich.copilot' => [
        'provider' => 'openai',
        'providers' => [
            'openai' => [
                'apiKey' => 'your-openai-api-key',
                'model' => 'gpt-5.6-terra',
                'options' => [
                    'textVerbosity' => 'low'
                ]
            ]
        ]
    ]
];

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 & Field Configuration page. The following properties can be set globally:

systemPrompt String

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

logLevel String

Default logging level for debugging AI generation.

Default: warn
Options: error, warn, info, debug

Basic Global Configuration

return [
    'johannschopplich.copilot' => [
        'provider' => 'google', // Primary provider
        'providers' => [
            'google' => [
                'apiKey' => 'your-google-api-key',
                'model' => 'gemini-3.8-flash'
            ]
        ],

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

Security

All AI provider requests are routed through a server-side proxy. 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 'your-admin-api-key';
                    }

                    return 'your-user-api-key';
                }
            ]
        ]
    ]
];

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.