Configure Providers and models

AI Provider settings belong to the current desktop device. They do not belong to one App and do not travel with source files or Git. Before configuring anything, decide who supplies the model, who pays for it, and whether this device can reach the service.

Choose a model source

Source	Best for	Where to configure it	Request and cost path
Qixin AI	Platform users with a personal or organization wallet	System Settings → AI Settings → Qixin AI	Uses platform models and the selected wallet
Organization models	Members of an organization that distributes private models	An organization administrator configures Portal; a member selects that organization in AI Settings	The member device connects directly; no Qixin wallet charge
Personal BYOK	Users whose current Qixin account has BYOK access	System Settings → AI Settings → Personal AI services	Uses the user's own subscription, API key, or OAuth sign-in

Personal BYOK access controls only the Personal AI services section. It does not control Qixin AI or organization models. If that section is missing, verify the signed-in Qixin account and its BYOK access. Do not bypass the UI by editing local files.

Configure Qixin AI

1. Open System Settings → AI Settings and sign in with Qixin.
2. Select a personal or organization wallet on the Qixin AI card.
3. Select Use this account. If it is already selected, use Reconnect to obtain the current account and organization configuration again.
4. Check Qixin AI models. If the list has not loaded or the platform has just changed its catalog, select Refresh models.
5. Open AI Command Center and explicitly choose the required Qixin AI model.

Theseus restores a still-valid account selection on this device. With no existing choice, it prefers an available organization account and otherwise selects the personal wallet. Switching accounts does not create or clear a conversation. Later Qixin AI requests use the account selected when each message is sent. Check the account icon at the top of AI Command Center before sending.

Qixin AI uses the selected wallet. Manage balances, spending records, and account details in Qixin Portal; AI Settings only selects an account, connects its credential, and loads models. If a model is withdrawn, an existing conversation asks for another explicit selection instead of silently switching.

Use organization models

The organization manages these models centrally. Members cannot edit their Endpoint, authentication mode, or model list on the desktop.

Organization administrator

1. Open Qixin Portal → Organization → the organization → AI providers.
2. Add the OpenAI-compatible Base URL, choose no authentication or an organization shared key, and enter the explicit models that members may use.
3. Save the configuration and ask members to reconnect the organization on the desktop.

Automatic and manual refresh

All enabled, authenticated Providers share a ten-minute catalog lifetime. Opening AI settings, the conversation panel or model picker, or returning focus to the window refreshes expired catalogs. Sending a message checks only the selected Provider. There is no background polling timer.

Refresh all models and each Provider's Refresh models bypass that lifetime. Qixin AI and custom API Providers use their own model endpoints; Codex and built-in subscriptions use Pi's network catalog. Organization models remain restricted to the authorized catalog delivered by Portal; reconnect the organization after its administrator changes that catalog.

An automatic refresh failure shows a stale-list warning and retries on later activity. Manual failures appear on the affected Provider instead of being reported as successful. Refreshing never changes an existing conversation's selected model.

Organization member

1. In System Settings → AI Settings, select the organization account that has private models.
2. Select Use this account. After a configuration change, select Reconnect.
3. Confirm that the required model appears under Organization models.
4. Select it in AI Command Center and start with a read-only test question.

An organization-model request goes directly from the member device to the organization's private Endpoint. The device needs the required DNS, VPN, TLS certificate, and network route; Qixin Portal does not relay the request. Organization models do not use a Qixin wallet.

If the organization uses a shared key, that key is made available to authorized member clients. To revoke access immediately, rotate the key at the organization model service. Removing a member or disabling the Portal configuration may not clear the local configuration until the client reconnects.

Configure personal BYOK

AI Settings shows Personal AI services only when the current Qixin account has personal BYOK access. Enter credentials only in their dedicated fields, never in chat, screenshots, documentation, or Git.

Built-in subscription Provider

1. Under Personal AI services, select Add AI service.
2. Choose the subscription and exact region shown in the UI. For a source that requires an API key, enter the key issued by that subscription in the dedicated field.
3. After adding Kimi For Coding, select Sign in on its Provider row and complete the device-code flow. Codex appears directly in the Personal AI services list and also connects through Sign in.
4. Once connected, click the model count on the row to view available models, then select one in AI Command Center.

The exact regions, Endpoints, and models for sources such as Qwen, Z.AI/GLM, MiniMax, and MiMo come from the installed version. Theseus manages built-in Endpoints, so they cannot be edited as custom OpenAI-compatible Providers. Add the source for the correct region when changing regions.

OpenAI-compatible Provider

1. Under Personal AI services, select Add AI service → OpenAI-compatible.
2. Enter the complete API Base URL and an API key. Expand Advanced to customize the display name.
3. Select Connect to apply the configuration and load models.
4. Click the model count on the row to browse or search models. Click a model to expand its details; select Refresh models at the bottom of the list to update manually.
5. Explicitly select a model in AI Command Center and send a test question that does not change files.

The Base URL must include the service's required version path. For example, with https://example.com/api/v3, model discovery uses https://example.com/api/v3/models. Theseus does not add or rewrite paths such as /v1 or /v3.

Select Manage on the row to edit the connection, sign in again, or sign out. Connection management has no model refresh action. When editing an existing Provider, leaving the API key blank preserves the current key. Automatic model updates do not overwrite unsaved form edits. Saving a Provider or refreshing models does not replace the model selected in the current conversation; verify the selection after returning to AI Command Center.

Automatic and manual refresh

Model lists have a ten-minute freshness window. Opening AI settings or AI Command Center, returning focus to the window, and using a model can trigger an update when the list is stale. Sending a message checks only the selected Provider.

Refresh models updates the corresponding service immediately, regardless of freshness. Qixin AI and custom API Providers use their model endpoints; Codex and built-in subscription sources use their online catalogs. Organization models follow the authorized list supplied by Portal; reconnect the organization after its administrator changes that list.

If an automatic refresh fails, the existing model list remains available without a refresh warning, and later activity retries the update. A failed manual refresh shows the corresponding Provider's error. Refreshing the catalog does not change an existing conversation's model; sending checks whether the selected model is available.

Choose the right model

Task	Prefer
Complex changes across several files, QG, and Objects	Strong reasoning and enough context
Reading an error or making a small repair	Speed and stability
Images, Vision, or visual page-snapshot review	Explicit image-input support
Documentation explanation or short text	A fast model is usually sufficient

The model selector shows only capabilities reported by the current Provider. If a Provider publishes thinking levels, the menu shows only its supported levels. When a model becomes unavailable, access changes, or a Provider disconnects, Theseus does not silently substitute another model.

Understand conversation data

The model source does not change AI Command Center's conversation-retention rules:

• Complete conversation history is stored on the current device.
• New conversations and conversations changed afterward are archived to the Qixin platform, including organization-model and personal-BYOK conversations.
• Deleting a local conversation does not delete its platform archive, and platform archives do not expire automatically.
• Ordinary users, conversation creators, and organization OWNER or ADMIN members cannot read archived content. A global platform administrator can preview, download one file, or perform compliance deletion only under audit controls.
• Do not submit customer private data you are not allowed to upload or raw production data that must remain on site.

Before production use, the organization should confirm data authorization, access, and deletion rules. See Conversations, references, and task status for the full behavior.

What a successful configuration looks like

• AI Settings shows the correct Qixin account, organization model, or personal Provider.
• Clicking a service’s model count lets you search models and inspect reasoning or image capabilities.
• AI Command Center can select the model and complete a read-only test question.
• Switching a Qixin account or refreshing a Provider neither clears the current conversation nor changes its model unexpectedly.

Common issues

Personal AI services is missing

Confirm that the current Qixin account is signed in and has personal BYOK access. This access is independent of organization-model access.

The Provider is saved, but no models appear

Check sign-in or API-key state, correct the connection through Manage, and save. Use Retry on the row after an update failure. One failed Provider does not block healthy Providers.

OpenAI-compatible model refresh fails

Confirm that the Base URL is the complete API root and that <Base URL>/models returns usable models from this device. Do not add or remove /v1 by guesswork. Also check the proxy, TLS, authentication, and returned model IDs.

Organization models do not appear

Select the correct organization account and choose Reconnect. Ask an organization administrator to verify that Portal contains the Endpoint, authentication mode, and an explicit model list.

An organization model is unreachable

Check DNS, VPN, TLS, authentication, and model IDs from the member device. Because the device connects directly, being able to open Portal does not prove that the private Endpoint is reachable.

A Qixin AI request fails

Check Qixin sign-in, the current billing account, wallet balance, and whether the model is still available. Then reconnect the account or refresh models. An organization private model does not depend on the Qixin wallet balance.

Codex reports fetch failed

First verify that the device's system HTTP(S) proxy can reach chatgpt.com, then sign in again or retry. Never paste proxy credentials into chat.

Security boundaries

• Enter API keys, passwords, and device authorization codes only in dedicated credential fields.
• Provider settings apply across the current desktop device. Protect shared devices with controlled system accounts and disk protection.
• An organization shared key reaches authorized member devices. Immediate revocation requires key rotation at the service.
• Do not disable TLS verification or place a production key in documentation to work around a connection failure.
• Repair only the failing Provider configuration; do not delete unrelated healthy Providers.

Next, see Use AI Command Center.

Personal configuration on this device

Interface preferences, the model and effort for new conversations, and personal AI service settings excluding secrets share ~/.qixin/theseus/config.toml, where ~ is your home directory. Settings controls and manual edits use the same file. Saving through the interface reformats TOML and does not preserve comments. Invalid configuration at startup produces an error without resetting the file. Fully quit the application before editing the file manually; changes take effect on the next start.

This version uses the new file directly and does not import previous settings. After upgrading, configure your interface preferences, personal AI services, and new-conversation model again. Saved sign-in credentials and conversation history remain available. Do not put API keys or access tokens in this file.