Upgrading

Upgrading documents version-specific changes in OpenCode Desktop, TUI, SDKs, and provider integrations; each release notes new features, fixes, and compatibility adjustments across layout migration, session features, model routing, and third-party service support. Mixed-version setups and legacy config handling require careful attention: newer OpenCode versions maintain backward compatibility with older configs while removing reliance on legacy configuration on v2 servers.

Desktop v1.18.0 completed the Desktop v2 migration, including upgrade handling for the new layout and first-launch onboarding, with a setting to switch between the new and old layouts during the transition period.[1] Desktop v1.18.12 skips legacy config reads against v2 servers to avoid spurious config loading issues; upgraders running mixed v1/v2 setups should be aware that v2 servers no longer consult legacy config.[2]

As of v1.18.24, V1 reads supported V2 config fields so newer config files remain functional in mixed V1/V2 setups.[3] Unknown top-level config fields are ignored instead of failing config parsing, as of v1.18.16.[4]

Session snapshots and revert controls allow rolling a session back to an earlier message, including reverting file changes, added in v1.17.11.[5] Chronological message ordering stays correct even when imported or legacy message IDs are out of order, fixed in v1.18.15.[6] Revert and fork actions use real message chronology instead of message ID ordering, as of v1.18.15.[6] Full session transcripts can be exported as JSON from the Desktop UI, added in v1.18.15.[6] Session compaction keeps complete recent turns and produces clearer summaries for smaller models, improved in v1.18.17.[7]

Subagents no longer launch nested subagents by default; a configurable subagent_depth limit is available when nesting is needed, as of v1.18.2.[8] A yolo mode to auto-approve permissions was added to the TUI in v1.17.12.[9]

Azure providers can sign in with Microsoft Entra ID through the Azure CLI instead of requiring an API key, as of v1.18.24.[3] Azure Cognitive Services endpoint support for Azure-hosted models was restored in v1.18.4.[10] Azure AI support for GPT-5.6 was added in v1.17.20.[11] Bedrock reasoning responses are no longer cached into unreplayable empty messages, fixed in v1.18.24.[3] Anthropic model IDs with dots (e.g. claude-haiku-4.5) are converted to the dashed slug Anthropic expects when routing through Cloudflare AI Gateway, as of v1.18.23.[12] Non-Workers (third-party) models routed through Cloudflare AI Gateway use the gateway's REST API, fixed in v1.18.23.[12] Native OpenAI and Anthropic passthroughs for Cloudflare AI Gateway models were added in v1.18.19.[13] textVerbosity is no longer sent to OpenAI-compatible providers that do not support it, fixed in v1.18.22.[14] Vertex AI eu and us multi-region Gemini requests are routed through REP endpoints, as of v1.18.21.[15] Deprecated sampling defaults are no longer sent to newer Gemini models, as of v1.18.8.[16] Kimi family models on Anthropic-compatible providers use adaptive thinking controls with summarized reasoning output by default, as of v1.18.4.[10] Reasoning mode is forced for OpenAI-compatible reasoning models so reasoning settings apply reliably on custom deployments, as of v1.17.13.[17] An obsolete Codex workaround that could interfere with OpenAI Luna Responses Lite requests was removed in v1.17.20.[11] Response storage is disabled by default for xAI Responses models, as of v1.17.19.[18] xAI login was simplified to a single device-code flow that works in headless and remote environments, as of v1.18.14.[19] Cerebras max_completion_tokens is preserved without applying an extra output cap, as of v1.18.20.[20] The provider layer retries responses ending with finish_reason: network_error and also handles the variants network-error and network_error, as of v1.18.20.[20] Available Modal models are discovered automatically, as of v1.18.10.[21]

MCP servers reconnect after expired OAuth sessions, including during concurrent requests, and honor configured OAuth callback ports in mcp debug, as of v1.18.8.[16] Compatibility with legacy MCP SDK clients was restored in v1.18.9.[22] Paginated MCP tool catalogs no longer lose tool metadata and output schema validation, fixed in v1.17.14.[23] A code mode MCP adapter for running confined orchestration scripts against connected MCP tools was added in v1.17.14; the execute tool is hidden unless code mode is enabled.[23]

The SDK gained live event subscription streams, active session access, paged durable session history, and session permission request endpoints in v1.17.12.[9] GitHub Copilot model routing honors each model's advertised chat or responses endpoint, fixed in v1.17.14.[23] The host directory path is no longer forwarded to remote workspaces, so prompts resolve from the remote project root instead of the local host path, fixed in v1.18.14.[19] Per-prompt model selection in the composer was added to the Desktop in v1.17.19.[18]

Sources

Search

Upgrading