Introduction
Many top AI agents like Claude Code and ChatGPT face three common issues for users:
- High barriers to use — accessing them in China is not straightforward
- Long waiting times — popular platforms have long queues for trial access
- Lack of privacy — code and data are controlled by third parties
OpenCode solves all these problems with three key advantages:
- Open source with 197K+ GitHub stars, ensuring code transparency
- User-friendly desktop version that works directly in China
- Built-in free models that are ready to use
This guide will walk you through installation and basic usage.
Installation
- Visit the official OpenCode download page
- Select the version compatible with your operating system
- Download and install the application
System Requirements:
- For office tasks or small personal projects, a regular home computer or lightweight laptop is sufficient
Getting Started
1. Model Selection
Choosing the right model is critical:
- Free models: Look for models marked with "Free" in the name (e.g., DeepSeek V4 Flash)
- Model details: Hover over a model name to see its capabilities
- Multimodal support: Only the MIMO model supports images, audio, and video in addition to text
2. Work Mode Selection
OpenCode offers two primary work modes:
- Build mode: Default execution mode with full read/write file and command execution capabilities
- Plan mode: Analysis and planning mode that only generates solutions without modifying files or running commands
When to use Plan mode:
- When you have a vague idea and need to clarify your approach
- When extending an existing project
- When you're unsure about the implementation details
3. Adding Work Folders
OpenCode operates around project folders:
- For existing projects: Select your existing project folder
- For new projects: Create a new folder with an English name (e.g.,
test) to avoid potential errors with Chinese paths
Useful Commands
OpenCode provides three essential commands:
@ Command
@[file_path]- Adds specific files or directories from your project folder as context
- Useful for referencing existing code or documentation
/ Command
/[command_name]- Quickly executes built-in or custom commands
- Common operations are available as one-click buttons
Shell Command
![shell_command]- Runs terminal commands directly in the chat window
- Advanced users can leverage this for system-level operations
Free Model Usage Rules
- No fixed free quota: Official documentation doesn't specify a fixed limit
- Quota exhaustion: When your free quota is used up, you'll see a "free usage exceeded" message
- Reset time: The countdown for quota reset varies (approximately 5 hours in some cases, up to 10+ hours in others)
- For heavy use: Consider connecting your own API key for stable access
Configuring Custom Models
To use your own API key:
- Open the model selection window
- Scroll to the bottom and click "View more providers"
- Select your provider from the list
- Enter your API key in the configuration panel
Conclusion
OpenCode provides a powerful, user-friendly alternative to traditional AI coding assistants. With its open-source nature, domestic accessibility, and built-in free models, it's an excellent choice for both beginners and experienced developers. Start with the free models to get familiar with the interface, then explore the advanced features as you become more comfortable.
常见问题
Is OpenCode Desktop really free?
Yes. OpenCode itself is open source under the MIT license, and it bundles free models that work out of the box. There is no fixed free quota documented — when your free usage is exhausted, you'll see a "free usage exceeded" message and the quota resets on a countdown that varies from roughly 5 hours to 10+ hours. If you rely on it for daily heavy work, connecting your own API key gives you stable access.
What's the difference between Build mode and Plan mode?
Build mode is the default execution mode: the agent has full read/write access to files and can run commands. Plan mode is analysis-only — it generates solutions and plans without modifying any files or executing commands. Use Plan mode when you have a vague idea that needs clarifying, when you're extending an existing project, or when you're unsure about implementation details and want to explore before committing changes.
Why does OpenCode bundle DeepSeek V4 Flash?
DeepSeek V4 Flash is one of the built-in free models in OpenCode, so you can start coding immediately without paying or configuring anything. OpenCode is model-agnostic and supports 75+ providers, so the bundled free models are just the starting point — you can also connect Anthropic, OpenAI, Gemini, local Ollama models, or your own API keys from the "View more providers" section of the model selection window.
Can I use my own API key in OpenCode?
Yes. Open the model selection window, scroll to the bottom, and click "View more providers". Pick your provider from the list and enter your API key in the configuration panel. This is the recommended path for heavy production use, since bundled free models may hit quota limits and their reset times vary.