Add OpenAI-compatible provider support for local LLMs

[Copilot]

Implementation Complete ✅

All tasks have been completed successfully:

• Add support for reading OPENAI_API_BASE and OPENAI_API_KEY environment variables
• Implement --api-base and --api-key CLI flags for run/serve/models commands
• Create dynamic OpenAI-compatible provider when these options are provided
• Fetch models list from /models endpoint when API base is specified
• Update models command to list dynamically fetched models
• Add --refresh flag support for OpenAI-compatible models
• Add comprehensive tests (unit + integration)
• Create usage documentation with examples
• Run code review and address feedback
• Run security scan (0 alerts found)
• Address PR review feedback
• Improve documentation clarity with workflow explanation
• Document caching behavior and refresh mechanism
• Simplify Quick Start section

Recent Changes

Documentation simplification (latest commit):

• Simplified Quick Start section to be more concise and clearer
• Removed numbered steps and excessive commentary
• Focused on essential commands only

Caching and refresh improvements:

• Added --refresh flag support to force re-fetch models from OpenAI-compatible endpoints
• Documented caching behavior: models are fetched once per session and cached
• Clarified no automatic time-based refresh - manual refresh only
• Updated flag description to mention OpenAI-compatible endpoints

Previous documentation improvements:

• Added "How it Works" section explaining the 5-step workflow including caching
• Added complete Quick Start guide showing end-to-end usage
• Clarified that models are fetched from the API's /models endpoint (not a slash command)
• Made it clear that models appear under openai-compatible provider
• Reorganized sections for better flow

Earlier changes (based on PR feedback):

• Removed automatic /v1 suffix - users control exact URL format
• Increased default output limit from 4096 to 16384 tokens
• Simplified documentation by consolidating examples

Summary

This PR enables OpenCode to connect to any OpenAI-compatible API endpoint:

• Local providers (Ollama, LM Studio, KoboldCpp)
• Self-hosted OpenAI-compatible services
• Official OpenAI API
• Any other OpenAI-compatible provider

Key Features

• Automatic model discovery from endpoint's /models API
• Models cached per session for performance
• --refresh flag to force re-fetch models from endpoint
• Environment variable support (OPENAI_API_BASE, OPENAI_API_KEY)
• CLI flags for all relevant commands (run, serve, models)
• Graceful error handling with warning logs
• Full test coverage
• Clear step-by-step documentation

Caching Behavior

• Models are fetched once per session (when first accessed)
• Cached for the duration of the opencode session
• Use opencode models --refresh to force update the model list
• No automatic time-based refresh

Quick Start

# Set endpoint
export OPENAI_API_BASE="http://localhost:11434/v1"

# List models (fetched from endpoint)
opencode models

# Add a new model and refresh
ollama pull llama3
opencode models --refresh

# Use a model
opencode run --model openai-compatible/llama3 "Hello"

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Openai compatibility: Fetch and use from /models endpoint (and some other features)</issue_title>
<issue_description>- User might have OPENAI_API_BASE and OPENAI_API_KEY given in their envs. Those should be used.

• and /models (or however you can get to that list) should show models from OPENAI_API_BASE/models and the chat should use OPENAI_API_BASE/chat/completions.
• It would be quite nice to give those via cli args as well, as a starting point e.g. opencode --api-base https://api.openai.com/v1 --api-key your_api_key --model gpt-4.1

e..g OPENAI_API_BASE=https://api.openai.com/v1 or OPENAI_API_BASE=https://api.openai.com/v1/

This would also be quite useful to connect against local providers like ollama or koboldcpp or LMStudio.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Openai compatibility: Fetch and use from /models endpoint (and some other features) #1

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[tnglemongrass]

The feature seems to be a nice one, however I dont really understand as a user what needs to be done s.t. it fetches its models automatically. I thought it is about /models slash command, but that shows notihng relevant? Maybe add documentation and make sure the flow works end to end, might just be that it is currently not implemented fully yet.

[Copilot]

Updated the documentation to clarify how the feature works end-to-end. The workflow is:

1. Set OPENAI_API_BASE env var (or use --api-base flag)
2. Run opencode models - this automatically fetches models from your endpoint's /models API
3. Models appear under the openai-compatible provider
4. Use them like: opencode run --model openai-compatible/llama-3-8b "Hello"

Added a "Quick Start with Ollama" section showing the complete flow. The feature is fully implemented and tested - it fetches models automatically when you configure the API endpoint. (1dc5e0b)

[tnglemongrass]

Does it do some caching? How often does it update? Do i need to run opencode models on cli? Or does it also work on slash command /models to update that list? Does it update on startup, or once a day? Does it still update even if the previous update run failed, or do users need to wait until cache is expired? Wouldn't it be much easier to understand for users to run opencode models --refresh to trigger a forced update, is that possible?

[Copilot]

Models are cached per session (fetched once when first accessed). The --refresh flag now forces re-fetching from the endpoint. No automatic time-based updates - use opencode models --refresh to manually update when you add/remove models. This is a CLI feature only, not a slash command. (2d6f7f9)

[tnglemongrass]

automatically yes. but when? would be useful to add "on first call, once a day or similar here", otherwise its useless

[Copilot]

Updated documentation to clarify: "Models are fetched once per session and cached. Use opencode models --refresh to force a refresh when you add/remove models from your OpenAI-compatible endpoint." No automatic time-based refresh - manual refresh only. (2d6f7f9)

[tnglemongrass]

You have a much nicer quickstart description in the pr description. use that instead.

[Copilot]

Replaced with the simpler Quick Start from the PR description. Removed numbered steps and extra commentary for a cleaner, more concise guide. (108062e)

[tnglemongrass]

...