Configuration
Learn about all available configuration options for the CoPilot plugin.
Control Panel
You can manage configuration settings through the Control Panel by visiting Settings → CoPilot.
Settings
You can define a multi environment aware config in /config/co-pilot.php. Settings defined in the config file override control panel settings.
defaultProvider
The default AI provider used for new conversations. Available values: openai, anthropic, gemini.
return [
'*' => [
'defaultProvider' => 'openai', // default
],
]
providerSettings
Per-provider configuration including API key environment variable and model selection.
return [
'*' => [
'providerSettings' => [
'openai' => [
'apiKeyEnvVar' => '$OPENAI_API_KEY',
'model' => 'gpt-5.4',
],
'anthropic' => [
'apiKeyEnvVar' => '$ANTHROPIC_API_KEY',
'model' => 'claude-sonnet-4-6',
],
'gemini' => [
'apiKeyEnvVar' => '$GEMINI_API_KEY',
'model' => 'gemini-2.5-flash',
],
],
],
]
Only reference API keys as environment variables. Settings are saved in project.yaml which is committed to git. Storing keys directly would leak them.
sectionAccess
Control the agent's access level per section. Maps section UIDs to access levels: blocked, readOnly, readWrite.
return [
'*' => [
'sectionAccess' => [
'section-uid-here' => 'readOnly',
'another-section-uid' => 'blocked',
],
],
]
These permissions take priority over user permissions. Even admin users cannot edit entries in sections that are blocked or read-only. See Permissions for details on how both layers interact.
volumeAccess
Control the agent's access level per asset volume. Same access levels as sectionAccess.
return [
'*' => [
'volumeAccess' => [
'volume-uid-here' => 'readOnly',
],
],
]
categoryGroupAccess
Control the agent's access level per category group. Same access levels as sectionAccess.
return [
'*' => [
'categoryGroupAccess' => [
'category-group-uid-here' => 'readWrite',
],
],
]
blockedElementTypes
List of element type classes the agent cannot interact with. Commerce Orders are blocked by default.
return [
'*' => [
'blockedElementTypes' => [
'craft\commerce\elements\Order', // default
],
],
]
webSearchEnabled
Allow the agent to search the web for information. Check out the provider docs to see if your configured provider has access to web search tools.
return [
'*' => [
'webSearchEnabled' => false, // default
],
]
agentExecutionMode
How the agent executes tool calls. Available values: supervised (requires user approval), autonomous (auto-execute).
return [
'*' => [
'agentExecutionMode' => 'supervised', // default
],
'dev' => [
'agentExecutionMode' => 'autonomous',
],
]
maxAgentIterations
Maximum number of tool-calling loops per message. Valid range: 1–200.
return [
'*' => [
'maxAgentIterations' => 50, // default
],
]
defaultSerializationDepth
Default nesting depth when serializing entries to JSON for the agent. Valid range: 1–10.
return [
'*' => [
'defaultSerializationDepth' => 3, // default
],
]
maxSerializationDepth
Maximum allowed nesting depth for entry serialization. Valid range: 1–10.
return [
'*' => [
'maxSerializationDepth' => 4, // default
],
]
maxContextTokens
Maximum number of tokens in the agent's context window. Valid range: 1,000–1,000,000.
return [
'*' => [
'maxContextTokens' => 200000, // default
],
]
defaultSearchLimit
Default number of results returned by search tools. Valid range: 1–200.
return [
'*' => [
'defaultSearchLimit' => 50, // default
],
]
elementUpdateBehavior
How entry updates are persisted.
provisionalDraft— Saves changes as a provisional draft. The original entry stays unchanged until an editor reviews and applies the draft. Best for production environments where content changes should be reviewed.draft— Creates a new draft for each update. Similar to provisional drafts but creates a separate named draft.directSave— Saves changes directly to the live entry. No draft or review step. Use with caution in production.
return [
'*' => [
'elementUpdateBehavior' => 'provisionalDraft', // default
],
]
elementCreationBehavior
How new entries are created.
draft— Creates new entries as unpublished drafts. An editor must review and publish them manually. Recommended for most setups.directSave— Creates new entries as published and immediately live. Use with caution.disabled— Creates new entries in a disabled state. Useful when entries need to be reviewed and manually enabled before going live.
return [
'*' => [
'elementCreationBehavior' => 'draft', // default
],
]
pluginName
Custom display name for the plugin in the control panel sidebar. Max 50 characters.
return [
'*' => [
'pluginName' => 'CoPilot', // default
],
]
auditLogRetentionDays
Number of days to retain audit log entries. Cleanup runs via Craft's garbage collection. Valid range: 1–365.
return [
'*' => [
'auditLogRetentionDays' => 30, // default
],
]
debug
Enable debug mode for additional logging and diagnostic information.
return [
'*' => [
'debug' => false, // default
],
'dev' => [
'debug' => true,
],
]
Multi-Environment Example
A complete example showing environment-specific configuration:
<?php
// config/co-pilot.php
return [
'*' => [
'defaultProvider' => 'anthropic',
'providerSettings' => [
'anthropic' => [
'apiKeyEnvVar' => '$ANTHROPIC_API_KEY',
'model' => 'claude-sonnet-4-6',
],
'openai' => [
'apiKeyEnvVar' => '$OPENAI_API_KEY',
'model' => 'gpt-5.4',
],
],
'agentExecutionMode' => 'supervised',
'webSearchEnabled' => true,
'elementCreationBehavior' => 'draft',
'elementUpdateBehavior' => 'provisionalDraft',
'auditLogRetentionDays' => 90,
],
'dev' => [
'agentExecutionMode' => 'autonomous',
'debug' => true,
],
'production' => [
'maxAgentIterations' => 30,
],
];