Connecting an AI model

• Create a connection
• Supported providers
• Authentication
• Options
• Notes

The AI assistant needs one model connection. Only administrators create connections; ordinary users never see keys and do not choose a model.

Create a connection

1. Open Administration → Plugins → Redmine Agent → Configure.
2. In the Models block click New model.
3. Choose a Provider, enter the Model ID and the authentication data.
4. Click Test connection: the plugin sends a minimal request and shows the result and its duration.
5. Save, then select the connection in the Model field of the plugin settings. It becomes the active connection for the whole installation.

Supported providers

OpenAI, Anthropic, Google Gemini, DeepSeek, Mistral, xAI, Perplexity, OpenRouter, Z.ai, Ollama and any OpenAI-compatible endpoint. The API address field is shown only for Ollama and OpenAI-compatible providers; other providers use a fixed address.

Authentication

• API key: stored encrypted (AES-256-GCM) with a key derived from the Redmine secret, and never shown again. Leave the field blank when editing to keep the saved key. Back up the Redmine secret together with the database, otherwise saved keys cannot be decrypted after a restore.
• OAuth / subscription (PRO): sign in with a ChatGPT account (OpenAI Codex) instead of an API key. Use Sign in with device code, or Sign in through browser (PKCE) and paste the full redirect address (it may not load, that is expected). Tokens are stored encrypted and refreshed automatically.

Options

• Thinking: enable reasoning for models that support it; its progress is shown while the AI works.
• Custom instructions: text added to every prompt of this model, for example tone or reply length (up to 10000 characters).
• Maximum attachment size: the total size of attachments that a user may send to the model (default 20 MB).

Notes

• Only one connection is active. If the active connection is deleted, requests fail with "An administrator must select the active connection" until another one is selected.
• The response length is limited to 4096 tokens (not for Codex).
• A request to the provider times out after 120 seconds.
• Requests are processed in the background by Redmine itself, using the queue adapter of the installation.