Model Management (Owner)

Audience

Only workspace admin can access and manage system model configuration. Regular users manage personal models at /workspace/models.

Model Scopes

ResearchX now separates model management into two scopes:

• System / admin models: managed at /workspace/admin/models, primarily for project admins and workspace-wide defaults
• Personal models: managed at /workspace/models, available to signed-in users for their own model list

The chat model picker only shows models the current user can access. When a project or conversation requests a model, the system resolves it against the caller's accessible scope first.

Basic Fields

• Model display name
• Provider
• Model id
• Base url
• API key (optional)

Fields marked as Required must be valid before you can save or test a model. The form shows inline validation messages for missing model IDs, invalid base URLs, invalid JSON configuration, or empty billing price fields when billing is enabled.

Provider Templates

When creating a model, start from a provider template whenever possible. Templates fill in common transport settings, default base URLs, and example model IDs.

Current templates include:

• OpenAI: OpenAI Chat Completions-compatible API
• OpenAI Responses: OpenAI Responses API
• OpenAI Codex (ChatGPT OAuth): Codex / ChatGPT OAuth login
• Custom OpenAI-Compatible: custom OpenAI-compatible services
• Anthropic
• OpenRouter
• Ollama
• Groq
• DeepSeek
• Perplexity
• Moonshot
• Zhipu AI
• SiliconFlow
• Volcengine Ark
• DashScope (OpenAI) / DashScope (Anthropic)
• Mistral
• NVIDIA NIM

Guidance:

• If a provider has a template, choose it first, then edit model id and credentials
• For newer OpenAI models, prefer OpenAI Responses; for Codex OAuth, use OpenAI Codex (ChatGPT OAuth)
• For aggregator services, start from OpenRouter; for DeepSeek's official API, start from DeepSeek

OpenAI Codex OAuth Credential

When you choose OpenAI Codex (ChatGPT OAuth), the model does not use a normal inline API key. It uses the Codex OAuth credential saved in ResearchX. The form shows a Codex OAuth Credential section.

Available actions:

• Log In to Codex: open the Codex authorization link and save the credential after authorization
• Import Local Codex: import an existing Codex login from the current machine or server
• Refresh: refresh the saved Codex token
• Clear: remove the saved Codex credential from ResearchX

Guidance:

• For local deployments, use Import Local Codex first if Codex is already logged in on the machine
• For remote deployments, click Log In to Codex, finish authorization in the browser, then paste the callback URL or code back into the form
• Credentials are saved by model-management scope: admin/system models use the admin model scope, and personal models use the personal model scope
• If the credential is missing or expired, calls through this template fail until you log in again or refresh the token

Context Configuration

Context Window Size

Sets the maximum context tokens the model supports. Leave empty to use the default:

• All model providers: 200k tokens

Custom values are useful when using providers with non-standard limits.

Context Compaction Settings

• Enable Compaction: Toggle automatic context compaction for this model
• Reserve Tokens: Tokens to reserve for the model's response (default: 16384)
• Keep Recent Tokens: Approximate tokens of recent dialogue to preserve uncompressed (default: 20000)
• Preemptive Compaction Threshold: Ratio (0-1) at which to trigger compaction proactively
  • Example: 0.8 triggers compaction when usage exceeds 80% of context window
  • Leave empty to use default value 0.9
  • Recommended: 0.8 - 0.9 for most use cases

When to Configure

• Enable compaction for models with smaller context windows
• Increase reserve tokens for models that generate longer responses
• Set preemptive threshold when users frequently hit context limits

Advanced Configuration

provider_spec (Provider Specification)

provider_spec declares provider information and compatibility characteristics:

• provider_type: Provider type (e.g., openai, anthropic, openai-compatible, etc.)
• supports_developer_role: Whether the model supports the developer role message (defaults to false, using system compatibility role)
• supports_streaming: Whether streaming output is supported
• supports_function_calling: Whether function/tool calling is supported

policy (Invocation Strategy)

policy controls model invocation behavior and retry strategies:

• max_retries: Maximum number of retries
• timeout_ms: Request timeout in milliseconds
• fallback_model: Fallback model ID (automatically switches when the primary model is unavailable)

capabilities (Capability Declarations)

capabilities declares specific features and characteristics supported by the model:

• vision: Whether image input is supported
• json_mode: Whether native JSON output mode is supported
• parallel_tool_calls: Whether parallel tool calls are supported
• max_tokens: Maximum tokens for a single response

thinking (Reasoning Configuration)

For models with provider_type: openai-compatible, you can configure a thinking field to enable extended reasoning capabilities:

• thinking: A configuration object that is injected directly into the API request payload, enabling deep thinking features for models that support them (e.g., ZhipuAI, Qwen)
• thinking_format: The reasoning format, supporting openai, zai, qwen, and other provider-specific formats

Notes:

• Only applies to openai-compatible provider types
• When configured, thinking parameters are automatically injected into every streaming/non-streaming request
• Reasoning is disabled by default for conversation title generation to reduce unnecessary token consumption

Flow

1. Open Model Management from project menu
2. Create or edit a model config
3. Return to chat and select the model before sending prompts

Default Model Selection Behavior

• The project remembers your last selected model
• If no previous selection exists (or it is unavailable), the first available model is selected automatically

Billing Configuration

The model edit form includes a billing section at the bottom, where you can independently enable per-token billing for each model. Configuration includes input price, output price (micro-units per 1k tokens), minimum charge, and billing currency. When billing is enabled, users are automatically charged from their wallet when calling the model.

See Model Billing and Wallets for details.