AI Service Configuration Preferences

Various service-related connection settings can be configured in Options > Preferences > Plugins > Oxygen AI Positron > AI Service Configuration.

This preferences page is divided into two sections:
  • Connections - This section is for those who want to use an AI service provider of their choice.
  • AI Positron Service - This section is for those who want to use the built-in default service.

Connections

The connections table allows you to configure connections to various AI service providers. Click the New button under the table to configure a new connection or the Edit button to edit an existing connection. You can also use Delete to remove a connection or Move Up/Move Down to move a selected connection.

Adding or editing a connection opens the Add Connection dialog box.

Figure 1. Add Connection Dialog Box

The following three options are always present in the Add Connection dialog box:

Name
Specifies the name of the connection.
Connection ID
Displays the automatically generated ID for the connection.
Connector type
Specifies the connector type. OpenAI Responses, OpenAI Chat Completions, MS Azure AI, Claude, AWS Bedrock, Google Gemini, and xAI Grok are provided as default configuration options. Additional add-ons are also available to enable connections to Google Cloud's Vertex AI platform or a custom AI service.

The Connection details section contains various options that depend on the selected Connector type

Connection details
The remaining options depend on the chosen Connector type. The the details for each type below.

Connector Types:

Open AI
If OpenAI Responses or OpenAI Chat Completions is chosen as the connector type, the Connection details section contains the following settings:
Base URL
The web address of the OpenAI service. By default: https://api.openai.com.
API key
The OpenAI API key necessary to work with the connector.
Note:
This option does not get saved in the Project-level options.
Organization ID
If you belong to multiple organizations, you can specify which organization is used for an API request. Usage from these API requests will count as usage for the specified organization.
Models

The table contains the possible models to be used for the chat view and for actions that do not explicitly specify a model. You can control which models will be available to the end users by selecting/deselecting the checkbox for each particular model in the Show column. The remaining columns show the model's ID, display name, and reasoning level.

The default model is shown in bold in the Display name column. To set a different model as the default, use the Set as default button below the table after clicking on the desired model.

You can also right-click on a model's row in the table to access actions to Set as default, Show in the model list, Hide from the model list, and Select all.

To add a custom model, use the Add button below the table. This opens the Add custom model dialog box.

Figure 2. Add Custom Model Dialog Box
The Add custom model dialog box contains the following fields:
  • Model ID - The ID for the custom model.
  • API model - A drop-down menu for selecting the model ID that is sent to the provider. If empty, the Model ID is sent.
  • Display name - The name of the model as it appears in the UI (e.g. in the model drop-down menu in the footer of the AI Positron view).
  • Reasoning - A drop-down menu for selecting the reasoning level for the custom model.
  • Context window [Optional] - The maximum number of tokens for the model's usable context window per request.
  • Max input tokens [Optional] - The maximum number of input tokens.
  • Max output tokens [Optional] - The maximum number of output tokens.
  • Description - A description of the custom model that will be shown in the UI (e.g. when hovering over the model in the footer of the AI Positron view).
Note:
The token limit fields are only used for the context consumption widget and the auto-compaction feature. Setting small maximum values for the context/input/output fields in the table does not block or reject any request, and does not truncate the input sent or cap the model's response (the output limit comes from the action's own max-tokens, not from the table). The real context limit is still enforced by the provider based on the actual model, so these values never prevent a request from executing.

Once a custom model has been added, it can be modified by using the Edit button, or deleted by using the Delete button.

Enable text moderation
This setting applies moderation (checks whether content complies with OpenAI's usage policies) to both the input text sent to the AI service and the response received from the AI service. It is enabled by default.
Tip:

By default, when executing an action using an OpenAI connector, three requests are made:

Enable speech-to-text
This setting allows for speech-to-prompt transcribing using the AI engine. If enabled, the Start recording prompt using the microphone button should be displayed under the chat box (in the AI Positron view).
Enable streaming
This option controls whether streaming is enabled. When enabled (default), AI-generated answers are delivered in real time as a continuous flow. If disabled, the complete answer is delivered all at once after the processing is finished.
Extra Headers
Extra name/value parameters to set in the headers that are specific for the AI requests.
Tip:
If the service uses Bearer Authentication, you can specify the key in the Key text field. If another authentication method is used, the Key field can be left empty, and the Extra Headers table can be used to set the authentication info on the request header. Note that editor variables can be used in this field and you can set your key in editor variables and specify the value in this table like this: ${env(AI_SERVICE_KEY)} to access pre-set values of environmental variables.
Notes:
  • You can use your own fine-tuned OpenAI models.
  • The OpenAI connectors might work with other AI engines that use the OpenAI APIs (like Grok or Deepseek).
MS Azure AI
If MS Azure AI is chosen as the connector type, the Connection details section contains the following settings:
Base URL

The base URL of your Azure resource. Two types of deployments are supported:

  • Microsoft Azure OpenAI deployments - Provide your Azure OpenAI resource URL found in the Keys & Endpoint section of the Azure portal (for example: https://your-company-name.openai.azure.com). The connector automatically builds the full request URL using this pattern: {base-url}/openai/deployments/{deployment}/chat/completions.
  • Claude (Anthropic) deployments on Azure AI Foundry - Provide the Anthropic base URL for your Azure AI Foundry resource (for example: https://<resource-name>.services.ai.azure.com/anthropic). When the URL contains anthropic, the connector automatically routes requests to the Claude Messages API at {base-url}/v1/messages.
Deployment
The deployment name that was chosen when the model was deployed in Microsoft Azure.
Reasoning effort
The default reasoning effort level to use when executing actions/chat requests (e.g. low, medium, high). Individual actions may override this default value. Leave it empty to use the deployment's built-in default value.
Maximum context window
The maximum number of tokens (input and output combined) for the model's usable context window per request.
API key

The Microsoft Azure OpenAI Service key necessary to work with the connector.

If an API key is not provided, the application will attempt to authenticate with Microsoft Entra ID by using one of the supported identity-based methods.

Enable streaming
This option controls whether streaming is enabled. When enabled (default), AI-generated answers are delivered in real time as a continuous flow. If disabled, the complete answer is delivered all at once after the processing is finished.
Extra Headers
Extra name/value parameters to set in the headers that are specific for the AI requests.
Speech service region
If a speech service is configured in the MS Azure account, you can use this setting to set the region of the server (for example: eastus). As an alternative, you can set a SPEECH_REGION environmental variable. Once the speech service is configured, the Start recording prompt using the microphone button should be displayed under the chat box (in the AI Positron view). This button allows for speech-to-prompt transcribing using the AI engine.
Attention:
This feature is not available when using Claude (Anthropic) deployments on Azure AI Foundry.
Speech service key
If a speech service is configured in the MS Azure account, you can use this setting to set the key to be used with the service. As an alternative, you can set a SPEECH_KEY environmental variable.
Attention:
This feature is not available when using Claude (Anthropic) deployments on Azure AI Foundry.
Note:
You can use your own fine-tuned Microsoft Azure OpenAI models.
Identity-based Authentication for Microsoft Azure:
The MS Azure AI connector supports the following identity-based authentication flows:
OAuth 2.0 Authorization Code Flow (User Sign-in)

This method enables interactive user sign-in via a browser. It is recommended for desktop applications used by individual users with personal or work accounts.

When a user triggers an AI action and is not authenticated, the application displays a dialog box prompting them to sign in using their Microsoft account. Upon successful login, the application retrieves an access token and continues operation.

Required Environment Variables to configure authentication flow:

Variable Description
AZURE_OAUTH_TENANT_ID Microsoft Entra (AAD) Tenant ID.
AZURE_OAUTH_CLIENT_ID Application (client) ID.
AZURE_OAUTH_REDIRECT_URI Redirect URI configured in the Entra app. This must be a localhost URL (for example: http://localhost:8085/callback).
Note:
You must register an application in Microsoft Entra ID that includes the specified redirect URI. The signed-in user or service principal must also be granted an Azure RBAC role on the target Azure resource:
  • Microsoft Azure OpenAI deployments - Assign a role such as Cognitive Services OpenAI User.
  • Claude (Anthropic) deployments on Azure AI Foundry - Assign a role that allows model inference on the Foundry resource, such as Cognitive Services User. In Foundry project-based setups, Azure AI User may also be required depending on how the resource is organized.
Service Principal Authentication

Service principal authentication is ideal for non-interactive scenarios, such as background processes or automation scripts.

Choose one of the options below if you need to authenticate without prompting the user to sign in.

Before you begin, create a service principal and assign a role to it that allows access to the Microsoft Azure OpenAI service (e.g. the Cognitive Services OpenAI User role).

  • Client Secret

    Use this method for simpler setups in trusted environments.

    Be aware that on desktop systems, secrets stored in environment variables or config files are not encrypted by default and may be exposed to other local users or processes.

    Required Environment Variables:

    Variable name Value
    AZURE_CLIENT_ID ID of a Microsoft Entra application.
    AZURE_TENANT_ID ID of the application's Microsoft Entra tenant.
    AZURE_CLIENT_SECRET One of the application's client secrets.

  • Client Certificate

    Use this method in high-security environments where certificate-based authentication is preferred over storing client secrets.

    Be aware that certificate files, like other secrets, must be protected properly—especially on desktop systems where local users may gain access to file contents if not secured appropriately.

    Required Environment Variables:

    Variable name Value
    AZURE_CLIENT_ID ID of a Microsoft Entra application.
    AZURE_TENANT_ID ID of the application's Microsoft Entra tenant.
    AZURE_CLIENT_CERTIFICATE_PATH Path to the PEM or PFX certificate file.
    AZURE_CLIENT_CERTIFICATE_PASSWORD Password for the certificate file (if any).

The connector will automatically detect and use the correct authentication flow based on which environment variables you have configured.

Note:
The application should be restarted after each environment-variable change for the changes to take effect.
Claude

If Claude is chosen as the connector type, the Connection details section contains the following settings:

Base URL
The web address where the connector service is located. By default, it is https://api.anthropic.com/.
API key
The Claude API key necessary to work with the connector.
Models

The table contains the possible models to be used for the chat view and for actions that do not explicitly specify a model. You can control which models will be available to the end users by selecting/deselecting the checkbox for each particular model in the Show column. The remaining columns show the model's ID, display name, and reasoning level.

The default model is shown in bold in the Display name column. To set a different model as the default, use the Set as default button below the table after clicking on the desired model.

You can also right-click on a model's row in the table to access actions to Set as default, Show in the model list, Hide from the model list, and Select all.

To add a custom model, use the Add button below the table. This opens the Add custom model dialog box.

Figure 3. Add Custom Model Dialog Box
The Add custom model dialog box contains the following fields:
  • Model ID - The ID for the custom model.
  • API model - A drop-down menu for selecting the model ID that is sent to the provider. If empty, the Model ID is sent.
  • Display name - The name of the model as it appears in the UI (e.g. in the model drop-down menu in the footer of the AI Positron view).
  • Reasoning - A drop-down menu for selecting the reasoning level for the custom model.
  • Context window [Optional] - The maximum number of tokens for the model's usable context window per request.
  • Max input tokens [Optional] - The maximum number of input tokens.
  • Max output tokens [Optional] - The maximum number of output tokens.
  • Description - A description of the custom model that will be shown in the UI (e.g. when hovering over the model in the footer of the AI Positron view).
Note:
The token limit fields are only used for the context consumption widget and the auto-compaction feature. Setting small maximum values for the context/input/output fields in the table does not block or reject any request, and does not truncate the input sent or cap the model's response (the output limit comes from the action's own max-tokens, not from the table). The real context limit is still enforced by the provider based on the actual model, so these values never prevent a request from executing.

Once a custom model has been added, it can be modified by using the Edit button, or deleted by using the Delete button.

Enable streaming
This option controls whether streaming is enabled. When enabled (default), AI-generated answers are delivered in real time as a continuous flow. If disabled, the complete answer is delivered all at once after the processing is finished.
Extra Headers
Extra name/value parameters to set in the headers that are specific for the AI requests.
AWS Bedrock
If AWS Bedrock is chosen as the connector type, the Connection details section contains the following settings:
AWS Region
The AWS region where the server is hosted (e.g. us-east-1). When you specify a region, the Base URL field is automatically generated based on that selection.
Base URL
The web address where the connector service is located. When specifying the AWS Region, this field is automatically generated. When both the AWS Region and Base URL are specified, AI Positron includes the region in the URL.
Authentication
Selects the authentication method to use when connecting to AWS Bedrock. Two options are available:
  • API Key - Authenticates using a static AWS Bedrock API key.
  • AWS Credentials (Profile / SSO) - Authenticates using AWS CLI v2, which must be installed and available in the system PATH. Credentials are resolved via aws configure export-credentials. This option supports SSO and any other credential type the AWS CLI supports.
Important:
To use the AWS Credentials (Profile / SSO) option, AWS CLI v2 must be installed and available in the system PATH. You can verify this by running aws --version in a terminal.
AWS Bedrock API key
The API key required for authenticating with the API Key method. This field is visible only when API Key is selected as the authentication method. For information about generating the API key, see Amazon Bedrock Documentation: Generate API Keys.
AWS Profile Name
The name of the AWS profile to use for authentication (as defined in ~/.aws/config or ~/.aws/credentials). This field is visible only when AWS Credentials (Profile / SSO) is selected as the authentication method. If left empty, the default AWS credential chain is used (environment variables and the default profile).
Auth Refresh Command
An optional shell command used to refresh an expired SSO session (e.g. aws sso login --profile=ai-writer). This field is visible only when AWS Credentials (Profile / SSO) is selected. If left empty and a profile name is set, the command is auto-composed as aws sso login --profile=<name>. When an SSO session expires, Positron automatically runs this command in the background, which launches a browser-based re-authentication flow.
Default model
The default model to be used for the chat view and for actions that do not explicitly specify a model. For a list of supported models in AWS Bedrock, see Amazon Bedrock Documentation: Supported Foundation Models.
Maximum context window
The maximum number of tokens (input and output combined) for the model's usable context window per request.
Enable streaming
This option controls whether streaming is enabled. When enabled (default), AI-generated answers are delivered in real time as a continuous flow. If disabled, the complete answer is delivered all at once after the processing is finished.
Extra Headers
Extra name/value parameters to set in the headers that are specific for the AI requests.
Google Gemini
If Google Gemini is chosen as the connector type, the Connection details section contains the following settings:
Base URL
The web address where the connector service is located. By default, it is https://generativelanguage.googleapis.com/.
API Key
The API key required for authenticating. It can be generated in Google AI Studio.
Models

The table contains the possible models to be used for the chat view and for actions that do not explicitly specify a model. You can control which models will be available to the end users by selecting/deselecting the checkbox for each particular model in the Show column. The remaining columns show the model's ID, display name, and reasoning level.

The default model is shown in bold in the Display name column. To set a different model as the default, use the Set as default button below the table after clicking on the desired model.

You can also right-click on a model's row in the table to access actions to Set as default, Show in the model list, Hide from the model list, and Select all.

To add a custom model, use the Add button below the table. This opens the Add custom model dialog box.

Figure 4. Add Custom Model Dialog Box
The Add custom model dialog box contains the following fields:
  • Model ID - The ID for the custom model.
  • API model - A drop-down menu for selecting the model ID that is sent to the provider. If empty, the Model ID is sent.
  • Display name - The name of the model as it appears in the UI (e.g. in the model drop-down menu in the footer of the AI Positron view).
  • Reasoning - A drop-down menu for selecting the reasoning level for the custom model.
  • Context window [Optional] - The maximum number of tokens for the model's usable context window per request.
  • Max input tokens [Optional] - The maximum number of input tokens.
  • Max output tokens [Optional] - The maximum number of output tokens.
  • Description - A description of the custom model that will be shown in the UI (e.g. when hovering over the model in the footer of the AI Positron view).
Note:
The token limit fields are only used for the context consumption widget and the auto-compaction feature. Setting small maximum values for the context/input/output fields in the table does not block or reject any request, and does not truncate the input sent or cap the model's response (the output limit comes from the action's own max-tokens, not from the table). The real context limit is still enforced by the provider based on the actual model, so these values never prevent a request from executing.

Once a custom model has been added, it can be modified by using the Edit button, or deleted by using the Delete button.

xAI Grok
If xAI Grok is chosen as the connector type, the Connection details section contains the following settings:
Base URL
The web address where the service is located. By default, it is https://api.x.ai.
API Key
The API key required to authenticate with the xAI Grok service.
Models

The table contains the possible models to be used for the chat view and for actions that do not explicitly specify a model. You can control which models will be available to the end users by selecting/deselecting the checkbox for each particular model in the Show column. The remaining columns show the model's ID, display name, and reasoning level.

The default model is shown in bold in the Display name column. To set a different model as the default, use the Set as default button below the table after clicking on the desired model.

You can also right-click on a model's row in the table to access actions to Set as default, Show in the model list, Hide from the model list, and Select all.

To add a custom model, use the Add button below the table. This opens the Add custom model dialog box.

Figure 5. Add Custom Model Dialog Box
The Add custom model dialog box contains the following fields:
  • Model ID - The ID for the custom model.
  • API model - A drop-down menu for selecting the model ID that is sent to the provider. If empty, the Model ID is sent.
  • Display name - The name of the model as it appears in the UI (e.g. in the model drop-down menu in the footer of the AI Positron view).
  • Reasoning - A drop-down menu for selecting the reasoning level for the custom model.
  • Context window [Optional] - The maximum number of tokens for the model's usable context window per request.
  • Max input tokens [Optional] - The maximum number of input tokens.
  • Max output tokens [Optional] - The maximum number of output tokens.
  • Description - A description of the custom model that will be shown in the UI (e.g. when hovering over the model in the footer of the AI Positron view).
Note:
The token limit fields are only used for the context consumption widget and the auto-compaction feature. Setting small maximum values for the context/input/output fields in the table does not block or reject any request, and does not truncate the input sent or cap the model's response (the output limit comes from the action's own max-tokens, not from the table). The real context limit is still enforced by the provider based on the actual model, so these values never prevent a request from executing.

Once a custom model has been added, it can be modified by using the Edit button, or deleted by using the Delete button.

Custom AI Service
This connector is available by installing the Oxygen AI Positron Custom Connector Add-on. The connector, named Custom AI Service, enables integration with a custom AI service that exposes a REST API, similar to OpenAI's chat-completion API. Unlike the built-in OpenAI Chat Completions connector, this supports the OAuth Client Credentials Flow for authentication and offers more flexibility by letting you set query parameters.
Vertex AI Service
This connector is available by installing the Oxygen AI Positron Vertex AI Connector Add-on. It enables integration with Google Cloud's Vertex AI platform.

AI Positron Service

This section contains the following options for using the default AI Positron Service:

Enable connections to the AI Positron Service
If selected, the AI Positron add-on is allowed to access the AI Positron Service platform. If not selected, the AI Positron add-on is prohibited from connecting and using models from the AI Positron Service platform.
Address
Displays the address of the service connection. Currently, there is only one public platform that provides this service.
Default model
The default model is used for the chat and for actions that do not explicitly specify a model. Each model consumes a certain number of credits per token. The OpenAI GPT-5.4 model is used as the default model for the AI Positron Service.
Note:
To access the list of models, you must be connected to the AI Positron Service.
Tip:
You can use editor variables such as ${env(ENV_NAME)} in all configuration and header parameter values.

Recommended LLMs

The AI-assisted authoring features in the chat interface and the bundled AI actions in AI Positron have been extensively tested with various popular and capable LLMs through both automated and manual testing. Based on our experience, the following LLMs offer strong performance, vision support (ability to process images), large context windows, and reasonable pricing:
  • Claude Sonnet 4.6
  • OpenAI GPT 5.4
  • Gemini 3 Flash

Keep in mind that newer versions of these models (released after this documentation was written) may deliver even better results.

If you choose to use AI Positron with a different LLM, make sure to test it thoroughly to verify that it produces useful results. We also recommend trying the latest available models, as they often include improvements in performance and capabilities.

Debugging AI Connections Using Debug Logs

To see detailed information about each AI request, enable DEBUG level logging for the com.oxygenxml.positron package (see Troubleshooting).

Each request produces a sequence of entries in the log file:

Step 1: The Outgoing Request
--> Sending request to: https://api.anthropic.com/v1/messages;
     Request body: {"model":"claude-3-5-sonnet","system":"**FILTERED: SYSTEM PROMPT**",
       "messages":[{"role":"user","content":"**FILTERED: TEXT CONTENT**"}],
       "tools":[{"function":{"name":"get_file","description":"**FILTERED: DESCRIPTION**"}}],
       "temperature":0.7,"stream":true};
     Headers: {Authorization=Bearer sk-ant**[filtered]**, Content-Type=application/json}

Shows the exact URL called, the full request structure (model, parameters, tools), and the first 6 characters of the API key (enough to confirm which key is active without exposing it).

Message content, system prompts, and image data are replaced with descriptive markers (**FILTERED: ...**) but the JSON structure remains intact. The body can be copied directly into an HTTP client such as Postman to reproduce the request outside the application.

Step 2: The Response
On success:
<-- Received response; Code: 200;
On HTTP error:
<-- Received response; Code: 401;
    Exceptions message is: Incorrect API key provided.
    Response headers:
      x-request-id: req_01XyZ...
      cf-ray: 8abc123...
On network failure (timeout, SSL error, firewall, DNS):
<-- Network failure for request to: https://api.anthropic.com/v1/messages;
    Error: timeout