OpenCode Usage: An open source agent that connects to any domestic model
The Claude Code and Codex from the previous two lessons are tied to Anthropic's and OpenAI's models and subscriptions respectively; in this 12-minute lesson, we look at the open source camp's OpenCode—the tool itself is open source and free, and models are swappable: domestic providers like DeepSeek, Kimi, Zhipu, and Tongyi are all in the official model catalog, so use whoever's key you have. This OpenCode tutorial focuses on the CLI, its main form—officially positioned as an "open source AI coding agent"—with desktop and web versions mentioned only in passing. (Fact-checked 2026-11-05; the model catalog and commands change with versions, so defer to the official documentation.)
What you'll be able to do after this lesson
- Install OpenCode CLI on macOS / Linux (Windows uses the official standalone binary), and launch it with one command from your project directory
- Connect models with
/connect: domestic providers like DeepSeek, Kimi, Zhipu, and Tongyi are all in the official catalog—paste an API key and go - Pick a model with
/models, assign its first task, and watch it read files, edit code, and run commands on its own - Handy operations:
@to reference files,!to run shell commands directly,/undoto undo - Track usage with
opencode stats, upgrade withopencode upgrade, and manage credentials withopencode auth
Your current predicament
- Claude Code requires a Claude subscription and Codex requires a ChatGPT account; what I have on hand are API keys for DeepSeek / Kimi / Zhipu
- Chatting about code in a web page, copying files back and forth, then pasting your changes back yourself
- Heard that OpenCode is an open source and free AI coding tool, but after installing it you're at a loss: where do the models come from? How do you use the terminal interface?
When to use this approach
When you need:
- An open source coding agent not tied to any model provider—any provider's API key works, and domestic models work out of the box
- To drive a terminal-based agent with your existing domestic model account (pay-as-you-go API or a Coding Plan)
- A tool that is itself open source: source code publicly available at github.com/anomalyco/opencode—modify it if you like
And you don't want to:
- Sign up for an overseas subscription just to use a coding agent
- Shuttle code and error messages back and forth in a web chat box
- Be locked into a single model ecosystem—DeepSeek today, Kimi tomorrow, just swap the key to swap models
🎒 Before you start
- Read the Daily Use Guide and know that this page covers OpenCode (the open source camp) among the four tools
- At least one model account: an API key from a domestic provider (DeepSeek / Kimi / Zhipu, etc.), or a ChatGPT Plus / Pro subscription, or connect to OpenCode Console first to try free models—see the pricing comparison for the cost of each path
- A practice project directory (the kind where you can
cdin and get to work) - 12 minutes of uninterrupted time
💡 The previous two lessons are not prerequisites
This lesson only requires reading the Daily Use Guide. Claude Code Usage and Codex Usage are independent of this lesson, but the mindset of "describe one thing clearly, like delegating a task" carries over.
Core idea
OpenCode's official positioning in one sentence: open source AI coding agent, available in terminal, desktop, and web forms. Its most fundamental difference from the previous two lessons: models are not tied. Claude Code uses Claude models and Codex uses GPT models; OpenCode itself is just an "agent shell," with a model catalog from models.dev—over a hundred domestic and international providers for you to connect. This is exactly what makes it friendliest for users in China: the catalog includes a large number of Chinese providers and domestic plans.
Compare it with the previous two lessons:
| Claude Code | Codex | OpenCode | |
|---|---|---|---|
| Models | Claude family | GPT family | Not tied: over a hundred providers in the models.dev catalog, connect any |
| Pricing | Claude subscription or API key | ChatGPT subscription or API key | The tool itself is open source and free; model fees go to the provider you connect (plus an optional OpenCode Go subscription) |
| Source code | Closed source | Closed source | Open source (github.com/anomalyco/opencode) |
| Form | Terminal / IDE / desktop / web | CLI / IDE / desktop / web | Terminal / desktop / web |
Usage in one sentence: first /connect connect an account, then /models pick a model. There are four ways to hook up credentials:
| Credential method | How it works |
|---|---|
| API key | Paste the key, saved as an account for that vendor |
| OAuth | Opens a browser or uses device-code authorization |
| Command | Runs the vendor-provided key-fetching command and stores the output as a key |
| Environment variable | Reads the variable from the service process, never saved to disk |
The three forms in one sentence: besides the CLI, OpenCode also has a desktop version (download the installer from the official site) and a web version (opencode pair generates a one-time login link, valid for 5 minutes and invalidated after a single use)—we won't expand on these in this lesson; the CLI is the main track.
How to choose and combine Claude Code, Codex? If you want to use a particular vendor's models, pick that vendor's official tool; if you have a key for a domestic model, or don't want to be locked into a single ecosystem, OpenCode is the matching choice. Using them together is entirely feasible—all three have a project instruction file mechanism, and OpenCode treats AGENTS.md as authoritative (the same file works with Codex; from v2.3.1 onward, if there is no AGENTS.md in the directory, it will also read CLAUDE.md; see AGENTS.md and CLAUDE.md for details). For a full comparison of how to choose among the four tools, see Tool Comparison, and for a complete cost table, see Pricing Comparison.
Follow along
Step 1: Install the OpenCode CLI
Why: OpenCode is a command-line tool installed independently; install it first, and everything after depends on it.
Option A: Official install script (recommended, macOS / Linux)
curl -fsSL https://opencode.ai/v2/install | bashOption B: Package manager (macOS / Linux)
brew install anomalyco/tap/opencode-v2npm install -g @opencode/cliThe npm package uses a postinstall script to pick the binary for your platform: pnpm requires an explicit allowance (pnpm add -g --allow-build=@opencode/cli @opencode/cli), and bun needs a trust flag (bun install -g --trust @opencode/cli); there are also yarn, AUR (paru -S opencode-beta), mise, and other channels (mise requires 2026.10.9 or newer; older versions install OpenCode 1).
Windows users: standalone binary or desktop version
The official docs state plainly: "Windows package managers are not supported." Two paths: download the standalone CLI binary from the official site (a zip, split by ARM64 / x64), unzip and use it; or just install the desktop app.
After installation, verify:
opencode --versionYou should see: the terminal prints a version number.
- Quick check:
opencode --versioncan print a version number
Step 2: Launch OpenCode and get to know the terminal interface
Why: OpenCode's primary form is a full-screen terminal interface (TUI); get familiar with it on first launch—all subsequent operations happen here.
cd /path/to/your/project
opencodeYou should see: a full-screen terminal interface with an input box at the bottom. Just type a task description and press Enter to send; use Shift+Enter for a new line (or Ctrl+Enter / Alt+Enter / Ctrl+J).
Don't want full screen? Two more entry points:
| Entry point | Command | Best for |
|---|---|---|
| Minimal interface | opencode mini | People who prefer a plain input box |
| One-off tasks in scripts / CI | opencode run "Explain this repository" | No interface; output goes straight to the terminal |
- Quick check: I launched
opencodein my project directory and can see the input box and type into it
Step 3: The core of this OpenCode tutorial—use /connect to hook up domestic (Chinese) models
Why: OpenCode ships without a model; it only comes "alive" once you connect your account. And domestic (Chinese) models are exactly its strength: the official model catalog (sourced from models.dev) includes a large batch of Chinese vendors and domestic plans—the biggest reason to choose it over the tools from the previous two lessons.
In the session, type:
/connectYou should see: a vendor selection list. Pick a vendor (e.g., DeepSeek) and paste your API key as prompted.
Domestic vendor catalog (excerpt; a single vendor often has multiple entries—international / domestic / plan versions—so make sure you pick the one you actually signed up for):
| Vendor | Entries in the catalog (examples) | Credential environment variables |
|---|---|---|
| DeepSeek | DeepSeek | DEEPSEEK_API_KEY |
| Moonshot AI (Kimi) | Moonshot AI (China), Kimi For Coding | MOONSHOT_API_KEY / KIMI_API_KEY |
| Zhipu AI | Zhipu AI, Zhipu AI Coding Plan, Z.AI | ZHIPU_API_KEY |
| Alibaba Tongyi | Alibaba (China), Alibaba Coding Plan | DASHSCOPE_API_KEY / ALIBABA_CODING_PLAN_API_KEY |
| MiniMax | MiniMax (minimax.cn)、MiniMax Token Plan | MINIMAX_API_KEY |
| ByteDance Volcengine Ark | Volcengine Ark, Volcengine Ark Coding Plan | ARK_API_KEY / ARK_CODING_PLAN_API_KEY |
| SiliconFlow | SiliconFlow (China) | SILICONFLOW_CN_API_KEY |
| Tencent | Tencent Coding Plan (China) | TENCENT_CODING_PLAN_API_KEY |
| StepFun | StepFun (China) | STEPFUN_API_KEY |
| ModelScope | ModelScope | MODELSCOPE_API_KEY |
Taking opencode connecting to deepseek as an example, you can connect even without opening the interface (the vendor ID is simply the name in the catalog):
opencode auth login deepseek --method keyYou should see: a prompt for an API key; paste it and save it as an account.
After connecting, check:
opencode auth listYou should see: a list of connected provider accounts.
💡 Don't have a single key yet? Start with the official free models
After registering on the OpenCode Console (opencode.ai/console) and connecting, a batch of free models will appear in the directory (such as GLM-5.3-Flash Free and DeepSeek V4.1 Flash Free), letting you get the workflow running without spending a cent.
- Small check: I can see the provider I just connected in
opencode auth list
Step 4: /models to pick a model and assign its first task
Why: connecting a provider only means you have "a source of goods"; you still need to tell OpenCode which model to use this time. Once selected, you can assign tasks just like in the previous two lessons.
In the session, type:
/modelsYou should see: a list of models from your connected providers (for example, DeepSeek V4.1 Flash 1017 under the DeepSeek directory); selecting one switches to it, effective only for the current session.
Assign its first task—as in the Codex lesson, start by having it explain this project to you:
Explain how authentication works in this projectYou should see: OpenCode reads the files itself and lists the project structure; when you ask it to modify code, it edits files directly, and when verification is needed, it runs commands locally.
To switch models at any time, use /models (or press Ctrl+X then M; F2 cycles through recently used models).
- Small check: I can see models from my connected provider in
/modelsand have selected one
Step 5: Handy everyday operations—@ to reference files, ! to run commands, /undo as your undo button
Why: whether an agent feels smooth to use comes down to these small actions. All of OpenCode's everyday operations fit in one table:
| What you want to do | Operation |
|---|---|
| Reference a file | Review @src/auth.ts for error handling problems (line numbers allowed @src/auth.ts#20-45) |
| Run a shell command directly | !git status (output stays in the session, so it can see it) |
| List all commands | Type /; Ctrl+P opens the command palette |
| Start a new session | /new or Ctrl+X then N |
| Return to an old session | /sessions |
| Take an "undo pill" | /undo undoes the last message and the work it did; /redo restores it |
| Ask a "doesn't count" small question | /btw why did the test in step 2 fail? (the answer doesn't enter the context) |
You should see: @ pops up a file search list that narrows as you type; ! enters shell mode, and Esc exits without executing.
- Small check: I have referenced a file with
@, run a command with!, and undone once with/undo
Step 6: Manage accounts, usage, and updates
Why: OpenCode follows the principle of "tools are tools, model fees go to the provider"—you should know how many accounts are connected and where the money goes.
opencode auth list
opencode stats
opencode stats --costYou should see: auth list lists saved accounts; stats gives shareable usage statistics, and adding --cost shows a cost breakdown.
Upgrade the version:
opencode upgradeTwo sentences on credential security: API keys and OAuth tokens are stored in a local SQLite database (check the path with opencode debug paths db, usually ~/.local/share/opencode/opencode.db); never modify the database manually—always add or remove accounts via the /connect or opencode auth commands.
- Small check: I can see my usage in
opencode stats
Checkpoint ✅
opencode --versionprints the version number, and the terminal interface can be launched in the project directory/connectconnected to at least one provider, andopencode auth listcan see it/modelsselected a model, assigned its first task, and saw it read and modify files on its own- Knows how to use
@to reference files,!to run commands, and/undoto undo opencode statscan show usage, and I know where credentials are stored and how to manage them
Pitfall warnings
❌ Can't install via package manager on Windows
The official docs are clear: "Windows package managers are not supported." The right approach: download the standalone CLI binary from the official website (unzip the zip), or install the desktop app; don't waste time on winget / scoop.
❌ pnpm / bun blocks scripts when installing the npm package, and it won't run after installation
The npm package relies on a postinstall script to pick the platform binary; pnpm blocks scripts by default and bun doesn't trust them by default. To allow them: pnpm add -g --allow-build=@opencode/cli @opencode/cli, bun install -g --trust @opencode/cli. npm users are unaffected.
❌ After logging in with a ChatGPT plan, the model feels "dumber"
OpenCode by default adds a context limit to models signed in with ChatGPT (GPT-6.1 Sol and newer models 500,000, older models 272,000), aligned with Codex's default value, to prevent plan usage from being consumed too quickly. As of v2.3.1, after signing in with ChatGPT, the model list also includes GPT 6.2 Sol and GPT 6.2 Astra (including fast variants).@@I18N_KEEP_000042@@If you really want to remove this limit, disable this built-in plugin in the configuration:
{ "plugins": ["-opencode.provider.openai-context-caps"] }(The - prefix means only this one built-in plugin is disabled; other plugins are unaffected.)
❌ Wrote the API key in plaintext into a config file and committed it to the repository
Credentials should be saved via /connect or opencode auth login (into the local database), or passed to the service process via environment variables; writing them into opencode.jsonc and committing to git is like leaving your key in the door. Using an environment variable temporarily also works: DEEPSEEK_API_KEY=<你的key> opencode --standalone.
Advanced tips (optional)
Leave a "manual" for your project. Place AGENTS.md in the project root directory, writing down build commands, code conventions, and verification requirements; every OpenCode session will read it first; put the global version at ~/.config/opencode/AGENTS.md. Starting from v2.3.1 (2026-11-18), OpenCode will also read CLAUDE.md: when a directory has no AGENTS.md, it reads that directory's CLAUDE.md; when the global AGENTS.md is missing, it falls back to reading ~/.claude/CLAUDE.md; if you don't want this fallback, set the environment variable OPENCODE_DISABLE_CLAUDE_CODE. When both exist, AGENTS.md takes precedence. See AGENTS.md and CLAUDE.md: Leaving a Project Manual for AI for a detailed guide on how to write them.
Can't see what each step is doing? Starting from v2.3.0 (2026-11-13), subagents run in the background by default and come back to report when finished; the terminal interface's log is also quieter by default (session.verbosity defaults to low, with a series of tool calls collapsed into a single activity line). To see every step, set Verbosity to medium or high in the settings.
Connect local models, fully offline. If you have Ollama installed, ollama serve to start the service and ollama pull qwen3:8b to pull a model; OpenCode automatically discovers models on 127.0.0.1:11434 with no account needed; LM Studio and vLLM also have built-in discovery.
If a provider isn't in the directory, add it yourself. Any OpenAI-compatible API can be connected as a custom provider in opencode.jsonc:
{
"$schema": "https://opencode.ai/config.json",
"providers": {
"acme": {
"name": "Acme",
"env": ["ACME_API_KEY"],
"package": "@opencode/ai/providers/openai-compatible",
"settings": { "baseURL": "https://llm.acme.example/v1" },
"models": { "qwen3-coder": { "name": "Qwen 3 Coder" } }
}
}
}Already have a ChatGPT subscription? Use it directly. /connect select OpenAI and choose Sign in with ChatGPT as the login method — usage counts toward your Plus / Pro plan and models show as no cost.
Want "flat-rate unlimited use"? Check out OpenCode Go. An official bundled subscription for a set of coding models: Go $10/month, Go Plus $40/month, Go Teams $20/member/month; after subscribing in the console, connect /connect like a regular provider. Entirely optional — not subscribing doesn't affect any features.
Run in scripts and CI. opencode run for one-shot tasks without opening the UI: opencode run --model anthropic/claude-sonnet-5-5 "Refactor parseToken"; add --continue to continue from the previous session.
Lesson Summary
✅ The OpenCode tutorial's daily workflow = install the CLI → /connect connect a model (pick any domestic provider) → /models choose a model → assign tasks → @/!//undo handy operations → stats monitor usage.
✅ It's an open-source agent not tied to any model: the core is free and open source, and model fees are paid to the provider you connect; it has the most complete directory of domestic models — DeepSeek, Kimi, Zhipu, Tongyi, MiniMax, Volcengine Ark, SiliconFlow, Tencent, Stepfun, and ModelScope are all included.
✅ Three forms: CLI (this lesson's focus), desktop app, and web (a opencode pair one-time link, valid for 5 minutes).
✅ Four ways to connect credentials (API key / OAuth / command / environment variable); account credentials are stored in a local SQLite database (environment variables are not written to disk), and management only goes through the /connect and opencode auth commands.
✅ The project manual is based on AGENTS.md and shares the same file with Codex, so no rewriting is needed when switching tools; starting from v2.3.1, when there is no AGENTS.md, it falls back to reading CLAUDE.md.
Key operations recap:
| Operation | How | Notes |
|---|---|---|
| Install | curl -fsSL https://opencode.ai/v2/install | bash | Alternatives: brew, npm; Windows uses a standalone binary |
| Start | Run opencode in the project directory | Minimal version: opencode mini; for scripts opencode run |
| Connect a model | /connect pick a provider and paste the key | command-line method: opencode auth login <厂商> --method key |
| Choose a model | /models | Applies only to the current session; F2 cycles through recent models |
| Reference files / run commands | @src/auth.ts / !git status | @ can include #20-45 line numbers |
| Undo | /undo, /redo | Removes the last message and the work it did |
| Check usage | opencode stats, opencode stats --cost | use opencode upgrade to upgrade |
Next Lesson Preview
We've been using the command line so far; the final lesson is for people who never want to touch a terminal: WorkBuddy usage: a desktop AI workstation from Tencent.
You will learn:
- WorkBuddy is: a desktop AI workstation from Tencent, log in by scanning a QR code with WeChat
- How to have AI build websites and mini programs without writing commands
- How credits are calculated and how to choose a plan
- For a full cost table of the four tools, see price comparison