Skip to content

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, /undo to undo
  • Track usage with opencode stats, upgrade with opencode upgrade, and manage credentials with opencode 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 cd in 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 CodeCodexOpenCode
ModelsClaude familyGPT familyNot tied: over a hundred providers in the models.dev catalog, connect any
PricingClaude subscription or API keyChatGPT subscription or API keyThe tool itself is open source and free; model fees go to the provider you connect (plus an optional OpenCode Go subscription)
Source codeClosed sourceClosed sourceOpen source (github.com/anomalyco/opencode)
FormTerminal / IDE / desktop / webCLI / IDE / desktop / webTerminal / 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 methodHow it works
API keyPaste the key, saved as an account for that vendor
OAuthOpens a browser or uses device-code authorization
CommandRuns the vendor-provided key-fetching command and stores the output as a key
Environment variableReads 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) ​

bash
curl -fsSL https://opencode.ai/v2/install | bash

Option B: Package manager (macOS / Linux) ​

bash
brew install anomalyco/tap/opencode-v2
bash
npm install -g @opencode/cli

The 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:

bash
opencode --version

You should see: the terminal prints a version number.

  • Quick check: opencode --version can 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.

bash
cd /path/to/your/project
opencode

You 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 pointCommandBest for
Minimal interfaceopencode miniPeople who prefer a plain input box
One-off tasks in scripts / CIopencode run "Explain this repository"No interface; output goes straight to the terminal
  • Quick check: I launched opencode in 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:

text
/connect

You 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):

VendorEntries in the catalog (examples)Credential environment variables
DeepSeekDeepSeekDEEPSEEK_API_KEY
Moonshot AI (Kimi)Moonshot AI (China), Kimi For CodingMOONSHOT_API_KEY / KIMI_API_KEY
Zhipu AIZhipu AI, Zhipu AI Coding Plan, Z.AIZHIPU_API_KEY
Alibaba TongyiAlibaba (China), Alibaba Coding PlanDASHSCOPE_API_KEY / ALIBABA_CODING_PLAN_API_KEY
MiniMaxMiniMax (minimax.cn)、MiniMax Token PlanMINIMAX_API_KEY
ByteDance Volcengine ArkVolcengine Ark, Volcengine Ark Coding PlanARK_API_KEY / ARK_CODING_PLAN_API_KEY
SiliconFlowSiliconFlow (China)SILICONFLOW_CN_API_KEY
TencentTencent Coding Plan (China)TENCENT_CODING_PLAN_API_KEY
StepFunStepFun (China)STEPFUN_API_KEY
ModelScopeModelScopeMODELSCOPE_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):

bash
opencode auth login deepseek --method key

You should see: a prompt for an API key; paste it and save it as an account.

After connecting, check:

bash
opencode auth list

You 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:

text
/models

You 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:

text
Explain how authentication works in this project

You 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 /models and 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 doOperation
Reference a fileReview @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 commandsType /; 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.

bash
opencode auth list
opencode stats
opencode stats --cost

You should see: auth list lists saved accounts; stats gives shareable usage statistics, and adding --cost shows a cost breakdown.

Upgrade the version:

bash
opencode upgrade

Two 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 --version prints the version number, and the terminal interface can be launched in the project directory
  • /connect connected to at least one provider, and opencode auth list can see it
  • /models selected 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 /undo to undo
  • opencode stats can 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:

jsonc
{ "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:

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:

OperationHowNotes
Installcurl -fsSL https://opencode.ai/v2/install | bashAlternatives: brew, npm; Windows uses a standalone binary
StartRun opencode in the project directoryMinimal version: opencode mini; for scripts opencode run
Connect a model/connect pick a provider and paste the keycommand-line method: opencode auth login <厂商> --method key
Choose a model/modelsApplies 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, /redoRemoves the last message and the work it did
Check usageopencode stats, opencode stats --costuse 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
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.