π OpenHands: AI-Driven Development
Add OpenAI o3 model support to verified models and OpenHands provider (#9720)
Xingyao Wangcd32b5508c16
diff --git a/.openhands/microagents/repo.md b/.openhands/microagents/repo.mdindex 0eaa1e80e4..5900382f4c 100644--- a/.openhands/microagents/repo.md+++ b/.openhands/microagents/repo.md@@ -137,3 +137,65 @@ Your specialized knowledge and instructions here...2. Add the setting to the backend:- Add the setting to the `Settings` model in `openhands/storage/data_models/settings.py`- Update any relevant backend code to apply the setting (e.g., in session creation)++### Adding New LLM Models++To add a new LLM model to OpenHands, you need to update multiple files across both frontend and backend:++#### Model Configuration Procedure:++1. **Frontend Model Arrays** (`frontend/src/utils/verified-models.ts`):+ - Add the model to `VERIFIED_MODELS` array (main list of all verified models)+ - Add to provider-specific arrays based on the model's provider:+ - `VERIFIED_OPENAI_MODELS` for OpenAI models+ - `VERIFIED_ANTHROPIC_MODELS` for Anthropic models+ - `VERIFIED_MISTRAL_MODELS` for Mistral models+ - `VERIFIED_OPENHANDS_MODELS` for models available through OpenHands provider++2. **Backend CLI Integration** (`openhands/cli/utils.py`):+ - Add the model to the appropriate `VERIFIED_*_MODELS` arrays+ - This ensures the model appears in CLI model selection++3. **Backend Model List** (`openhands/utils/llm.py`):+ - **CRITICAL**: Add the model to the `openhands_models` list (lines 57-66) if using OpenHands provider+ - This is required for the model to appear in the frontend model selector+ - Format: `'openhands/model-name'` (e.g., `'openhands/o3'`)++4. **Backend LLM Configuration** (`openhands/llm/llm.py`):+ - Add to feature-specific arrays based on model capabilities:+ - `FUNCTION_CALLING_SUPPORTED_MODELS` if the model supports function calling+ - `REASONING_EFFORT_SUPPORTED_MODELS` if the model supports reasoning effort parameters+ - `CACHE_PROMPT_SUPPORTED_MODELS` if the model supports prompt caching+ - `MODELS_WITHOUT_STOP_WORDS` if the model doesn't support stop words++5. **Validation**:+ - Run backend linting: `pre-commit run --config ./dev_config/python/.pre-commit-config.yaml`+ - Run frontend linting: `cd frontend && npm run lint:fix`+ - Run frontend build: `cd frontend && npm run build`++#### Model Verification Arrays:++- **VERIFIED_MODELS**: Main array of all verified models shown in the UI+- **VERIFIED_OPENAI_MODELS**: OpenAI models (LiteLLM doesn't return provider prefix)+- **VERIFIED_ANTHROPIC_MODELS**: Anthropic models (LiteLLM doesn't return provider prefix)+- **VERIFIED_MISTRAL_MODELS**: Mistral models (LiteLLM doesn't return provider prefix)+- **VERIFIED_OPENHANDS_MODELS**: Models available through OpenHands managed provider++#### Model Feature Support Arrays:++- **FUNCTION_CALLING_SUPPORTED_MODELS**: Models that support structured function calling+- **REASONING_EFFORT_SUPPORTED_MODELS**: Models that support reasoning effort parameters (like o1, o3)+- **CACHE_PROMPT_SUPPORTED_MODELS**: Models that support prompt caching for efficiency+- **MODELS_WITHOUT_STOP_WORDS**: Models that don't support stop word parameters++#### Frontend Model Integration:++- Models are automatically available in the model selector UI once added to verified arrays+- The `extractModelAndProvider` utility automatically detects provider from model arrays+- Provider-specific models are grouped and prioritized in the UI selection++#### CLI Model Integration:++- Models appear in CLI provider selection based on the verified arrays+- The `organize_models_and_providers` function groups models by provider+- Default model selection prioritizes verified models for each providerdiff --git a/frontend/src/components/shared/modals/settings/model-selector.tsx b/frontend/src/components/shared/modals/settings/model-selector.tsxindex 4d54733741..cdf0832b47 100644--- a/frontend/src/components/shared/modals/settings/model-selector.tsx+++ b/frontend/src/components/shared/modals/settings/model-selector.tsx@@ -7,7 +7,11 @@ import React from "react";import { useTranslation } from "react-i18next";import { I18nKey } from "#/i18n/declaration";import { mapProvider } from "#/utils/map-provider";-import { VERIFIED_MODELS, VERIFIED_PROVIDERS } from "#/utils/verified-models";+import {+ VERIFIED_MODELS,+ VERIFIED_PROVIDERS,+ VERIFIED_OPENHANDS_MODELS,+} from "#/utils/verified-models";import { extractModelAndProvider } from "#/utils/extract-model-and-provider";interface ModelSelectorProps {@@ -29,6 +33,14 @@ export function ModelSelector({);const [selectedModel, setSelectedModel] = React.useState<string | null>(null);+ // Get the appropriate verified models array based on the selected provider+ const getVerifiedModels = () => {+ if (selectedProvider === "openhands") {+ return VERIFIED_OPENHANDS_MODELS;+ }+ return VERIFIED_MODELS;+ };+React.useEffect(() => {if (currentModel) {// runs when resetting to defaults@@ -151,18 +163,20 @@ export function ModelSelector({}}><AutocompleteSection title={t(I18nKey.MODEL_SELECTOR$VERIFIED)}>- {VERIFIED_MODELS.filter((model) =>- models[selectedProvider || ""]?.models?.includes(model),- ).map((model) => (- <AutocompleteItem key={model}>{model}</AutocompleteItem>- ))}+ {getVerifiedModels()+ .filter((model) =>+ models[selectedProvider || ""]?.models?.includes(model),+ )+ .map((model) => (+ <AutocompleteItem key={model}>{model}</AutocompleteItem>+ ))}</AutocompleteSection>{models[selectedProvider || ""]?.models?.some(- (model) => !VERIFIED_MODELS.includes(model),+ (model) => !getVerifiedModels().includes(model),) ? (<AutocompleteSection title={t(I18nKey.MODEL_SELECTOR$OTHERS)}>{models[selectedProvider || ""]?.models- .filter((model) => !VERIFIED_MODELS.includes(model))+ .filter((model) => !getVerifiedModels().includes(model)).map((model) => (<AutocompleteItemdata-testid={`model-item-${model}`}diff --git a/frontend/src/utils/verified-models.ts b/frontend/src/utils/verified-models.tsindex 16afbe89d8..edc82e6adc 100644--- a/frontend/src/utils/verified-models.ts+++ b/frontend/src/utils/verified-models.ts@@ -8,6 +8,7 @@ export const VERIFIED_PROVIDERS = [export const VERIFIED_MODELS = ["o3-mini-2025-01-31","o3-2025-04-16",+ "o3","o4-mini-2025-04-16","claude-3-5-sonnet-20241022","claude-3-7-sonnet-20250219",@@ -60,6 +61,7 @@ export const VERIFIED_OPENHANDS_MODELS = ["claude-sonnet-4-20250514","claude-opus-4-20250514","gemini-2.5-pro",+ "o3","o4-mini","devstral-small-2507","devstral-medium-2507",diff --git a/openhands/cli/utils.py b/openhands/cli/utils.pyindex 6e7bef4e85..627ecbdb45 100644--- a/openhands/cli/utils.py+++ b/openhands/cli/utils.py@@ -186,6 +186,7 @@ VERIFIED_OPENHANDS_MODELS = ['claude-opus-4-20250514','devstral-small-2507','devstral-medium-2507',+ 'o3','o4-mini','gemini-2.5-pro',]diff --git a/openhands/llm/llm.py b/openhands/llm/llm.pyindex d2026f3233..908ec31574 100644--- a/openhands/llm/llm.py+++ b/openhands/llm/llm.py@@ -172,6 +172,9 @@ class LLM(RetryMixin, DebugMixin):# openai doesn't expose top_k# litellm will handle it a bit differently than the openai-compatible paramskwargs['top_k'] = self.config.top_k+ if self.config.top_p is not None:+ # openai doesn't expose top_p, but litellm does+ kwargs['top_p'] = self.config.top_p# Handle OpenHands provider - rewrite to litellm_proxyif self.config.model.startswith('openhands/'):@@ -190,6 +193,7 @@ class LLM(RetryMixin, DebugMixin):kwargs.pop('temperature') # temperature is not supported for reasoning models+ kwargs.pop('top_p') # reasoning model like o3 doesn't support top_p# Azure issue: https://github.com/All-Hands-AI/OpenHands/issues/6777if self.config.model.startswith('azure'):kwargs['max_tokens'] = self.config.max_output_tokens@@ -211,7 +215,6 @@ class LLM(RetryMixin, DebugMixin):api_version=self.config.api_version,custom_llm_provider=self.config.custom_llm_provider,timeout=self.config.timeout,- top_p=self.config.top_p,drop_params=self.config.drop_params,seed=self.config.seed,**kwargs,diff --git a/openhands/utils/llm.py b/openhands/utils/llm.pyindex 772f63555a..ed7bb0d3ba 100644--- a/openhands/utils/llm.py+++ b/openhands/utils/llm.py@@ -58,6 +58,7 @@ def get_supported_llm_models(config: OpenHandsConfig) -> list[str]:'openhands/claude-sonnet-4-20250514','openhands/claude-opus-4-20250514','openhands/gemini-2.5-pro',+ 'openhands/o3','openhands/o4-mini','openhands/devstral-small-2505','openhands/devstral-small-2507',