Global Configuration

Configure AI providers, API keys, models, and global defaults for the Kirby Copilot plugin.

Configure Kirby Copilot globally in your config.php file. This sets default options that apply to all plugin instances, including AI provider settings, generation parameters, and default behavior for view buttons and sections.

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:

config.php

return [
    'johannschopplich.copilot' => [
        'provider' => 'openai', // Choose your primary provider
        'providers' => [
            'openai' => [
                'apiKey' => 'YOUR_API_KEY',
                'model' => 'o4-mini'
            ]
        ]
    ]
];

Kirby Copilot supports four AI providers:

OpenAI (openai) – GPT models (default)
Google (google) – Gemini models
Anthropic (anthropic) – Claude models
Mistral (mistral) – Mistral models

For generating Blocks and Layouts or other structured data, we recommend Google Gemini models. Create a new Google Gemini API key and add it to the configuration along with the AI model such as Gemini 2.5 Flash. Usage is currently free!

OpenAI Configuration

Configure OpenAI GPT models for content generation:

config.php

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

Models with a balanced performance and cost are recommended for structured content generation:

gpt-5
gpt-5-mini
o4-mini

Get an API key by registering for the OpenAI API.

`reasoningEffort` object

GPT-5 and GPT-5 Mini are designed as reasoning models with different underlying architecture. The reasoningEffort parameter allows you to control the depth of reasoning applied during content generation.

Default: medium

config.php

return [
    'johannschopplich.copilot' => [
        'provider' => 'openai',
        'providers' => [
            'openai' => [
                'apiKey' => env('OPENAI_API_KEY'),
                'model' => 'gpt-5-mini',
                // Set provider-specific options
                'options' => [
                    'reasoningEffort' => 'medium' // 'minimal' | 'low' | 'medium' | 'high'
                ]
            ]
        ]
    ]
];

Google Gemini Configuration

Configure Google Gemini models. We recommend them for generating structured data like blocks and layouts:

config.php

return [
    'johannschopplich.copilot' => [
        'provider' => 'google',
        'providers' => [
            'google' => [
                'apiKey' => env('GOOGLE_API_KEY'),
                'model' => 'gemini-2.5-flash' // or 'gemini-2.5-pro'
            ]
        ]
    ]
];

For generating blocks and layouts or other structured data, we recommend Google Gemini models. Create a Google Gemini API key – usage is currently free!

Anthropic Claude Configuration

Configure Anthropic Claude models:

config.php

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

Mistral Configuration

Configure Mistral models with optional custom base URL:

config.php

return [
    'johannschopplich.copilot' => [
        'provider' => 'mistral',
        'providers' => [
            'mistral' => [
                'apiKey' => env('MISTRAL_API_KEY'),
                'model' => 'mistral-large-latest',
                // Optionally, set the base URL of a custom Mistral API instance
                'baseUrl' => 'https://api.mistral.ai'
            ]
        ]
    ]
];

AI Generation Settings

`temperature` Float

Controls the randomness and creativity of generated content. Higher values produce more creative but less predictable results.

GPT-5 is designed as a reasoning model with different underlying architecture. The model itself manages the randomness or creativity in its outputs, making the temperature parameter obsolete. Use reasoningEffort instead.

Default: 0.5Range: 0.0 (deterministic) to 1.0 (highly creative)

config.php

return [
    'johannschopplich.copilot' => [
        'temperature' => 0.8 // More creative
    ]
];

`systemPrompt` String

The systemPrompt is probably the most important configuration option besides the model. It is the structural foundation of the generated content and complements the prompt that is provided by the user (userPrompt property).

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.

config.php

return [
    'johannschopplich.copilot' => [
        'systemPrompt' => 'You are a professional content writer. Create engaging, well-structured content that is SEO-friendly and user-focused.'
    ]
];

Learn more about the system prompt and how to customize it effectively.

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

config.php

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

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 configuration option, see the View Button & Section Configuration page. The following options can be set globally:

systemPrompt – Default system prompt for all generations
userPrompt – Default user prompt
logLevel – Default logging level for debugging

Basic Global Configuration

config.php

return [
    'johannschopplich.copilot' => [
        // AI Provider
        'provider' => 'google',
        'providers' => [
            'google' => [
                'apiKey' => env('GOOGLE_API_KEY'),
                'model' => 'gemini-2.5-flash'
            ]
        ],

        // Generation Settings
        'temperature' => 0.7,

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

Security Considerations

API Key Security
Requests to AI providers are initiated client-side from the Kirby Panel, leaving your API keys exposed in network requests. To mitigate risks we recommend:

Use environment variables for API keys
Create separate API keys for each project/client
Set usage limits on your AI provider accounts
Monitor API usage regularly

config.php

return [
    'johannschopplich.copilot' => [
        'providers' => [
            'openai' => [
                'apiKey' => env('OPENAI_API_KEY'), // Use environment variables
            ]
        ]
    ]
];

Configuration Precedence

Global configuration serves as the foundation, with more specific configurations overriding global defaults:

Global configuration (in config.php)
Section configuration (in blueprint sections) & view button props (in blueprint buttons - Kirby 5+ only)

config.php

return [
    'johannschopplich.copilot' => [
        'logLevel' => 'warn',
        'systemPrompt' => 'Global prompt…'
    ]
];

Blueprint Override

sections:
  copilot:
    type: copilot
    field: content
    logLevel: debug # Overrides global
    # systemPrompt inherited from global

buttons:
  copilot:
    logLevel: debug # Overrides both global

Complete Configuration Example

config.php

return [
    'johannschopplich.copilot' => [
        // Primary AI Provider
        'provider' => 'google',
        'providers' => [
            'google' => [
                'apiKey' => env('GOOGLE_API_KEY'),
                'model' => 'gemini-2.5-flash'
            ],
            'openai' => [
                'apiKey' => env('OPENAI_API_KEY'),
                'model' => 'gpt-5-mini'
            ]
        ],

        // Generation Settings
        'temperature' => 0.6,

        // Global Defaults
        'excludedBlocks' => [
            'contact-form',
            'newsletter-signup',
            'advertisement'
        ]
    ]
];

Installation

Learn how to install and configure the plugin in your Kirby project.

View Button & Section Configuration

Configure Copilot view buttons and sections in your blueprints with fine-grained control over AI generation behavior.