Official documentation verification date:2026-07-27 Basis:https://opencode.ai/docs/zen/、https://opencode.ai/docs/、https://opencode.ai/docs/providers/、https://opencode.ai/docs/models/、https://opencode.ai/docs/troubleshooting/
⚠️ Read this first: why this pack is a must-do
Installing OpenCode does not mean it works。
OpenCode is just the "driver's seat"; it doesn't think on its own. You must first connect a "brain" (a model) to it, and only then will it reply, build files for you, and operate NotebookLM.
If you followed #00 Environment Setup and installed it, but when you open OpenCode you find:
- Typing does nothing
- A message like
No providers configuredpops up - No model name is visible in the bottom-right corner
That doesn't mean you installed it wrong; it means you haven't done this pack yet.
📌 Recommended order:#00 Environment Setup → #01 Connect a Model (this pack) → all other quick-start packs Without a connected model, none of the later packs will run.
What will this quick-start pack do for you?
- Sign up for OpenCode Zen(OpenCode's official model portal)
- Get a set of API key(that's the key)
- Insert the key into OpenCode (teaches both thedesktop versionand the CLI terminal versionmethods)
- Choose a free model
- Do a test where itreally takes action(ask it to create a
test.txt), to confirm the whole pipeline works
How it works (understand in 30 seconds)
你 → OpenCode（駕駛座） → OpenCode Zen（模型總機） → 實際的 AI 模型
↑
用 API key 認人
OpenCode Zen is OpenCode's officially curated model list. The official documentation's exact words are: this is a "list of tested and verified models".
Its advantages are:One key connects to multiple models, including a batch ofcurrently freemodels. Teachers don't have to apply for accounts with OpenAI, Google, and Anthropic one by one.
💡 Zen isoptional, not mandatory. The official documentation explicitly says "completely optional". You can also connect your own other providers, but for teachers with zero programming background, Zen is the shortest path.
Prerequisites
- Completed #00 Environment Setup（
opencode --versionhas a version number) - The computer has an internet connection
- Have an email account that can receive mail (for registration)
- An empty folder, to be used for testing in a moment (for example
Documents\opencode-test）
Desktop version or CLI? Both paths are covered, choose one and go through it
| Desktop App | CLI (terminal) | |
|---|---|---|
| Appearance | A normal window program, clickable with a mouse | A text interface with white text on a black background |
| Workshop setting | ✅ Recommended to use this one, everyone can understand it when projected | Use for advanced or remote troubleshooting |
| How to connect the key | Click around in the settings screen and paste | Enter /connect instruction |
| Relationship between the two | What runs in the background of the desktop version is actually the same OpenCode server | — |
🔑 Step 1 (register and get a key) is exactly the same for both paths, and both require doing it. After finishing, jump to Step 2A (desktop version) or Step 2B (CLI)。
Haven't installed the desktop version yet? (CLI users can skip)
#00 Environment setupOnly the CLI is installed. The desktop version must be installed separately:
- Windows (main path): open https://opencode.ai/download, download the Windows installer, and double-click to install
- macOS: from the same download page, get
.dmg; or use Homebrewbrew install --cask opencode-desktop - Linux: from the same download page, get
.debor.rpm
Please have OpenCode (or yourself) execute the following steps in order
This file can be pasted in its entirety to an AI agent to have it guide you through it. Places marked with the 🖐️ icon areoperations that must be done manually(you need to log in, click on web pages), and the agent will stop and wait for you.
Step 1: Register for OpenCode Zen and get an API key
🖐️ This step is done entirely in the browser.
1-1. Open the login page
URL (the entry point specified by the official documentation):
https://opencode.ai/auth
This URL will automatically redirect to OpenCode's login screen (
auth.opencode.ai）。It is normal to see the URL change; you are not being phished.
1-2. Log in / register
Use your Email (or the login method provided on the screen) to create an account and log in.
1-3. Create an API key
After logging in, you will enter the Console (admin backend). Find the section related to API Keys and create a new key.
The button text on the screen may be
Create API KeyorAdd API Key, and it may also be hidden underSettings. The official documentation does not explain the backend UI field by field; go by what you see on the screen. As long as you find the "create key" button, you are on the right track.
1-4. Copy and keep it safe
⚠️ The API key is usually shown in full only once. Copy it immediately after creation.
Storage recommendations (for teachers)：
- First paste it into Notepad as a temporary placeholder, and confirmthe entire string is on the same line, with no extra whitespace before or after, and not split by automatic line wrapping
- ❌ Do not paste it into shared Google Docs, class groups, or presentation notes
- ❌ Do not put it into a folder that will later be uploaded to GitHub
- ✅ If you really need to save it later, store it in your own password manager
1-5. About "billing information"
The official documentation's process wording is: log in → add billing information → copy the API key.
In practice, handle it like this:
- First try to create the API key directly
- If the backend does not let you create it and explicitly requires payment information first, then handle it according to the on-screen instructions
- Teachers using a school work device / who do not want to link a card,stop here first and ask the person in charge or decide for yourself, and do not rush to enter a credit card at the workshop site
❓ This package cannot confirm from the official documentation: whether "using only free models" also necessarily requires filling in billing information first. Official
/docs/zen/There is no separate explanation for the free model.Please refer to the backend screen you see at the moment.💰 This quick guidedoes not state any amounts, top-up quotas, or billing thresholds. Prices change, so always refer to the official https://opencode.ai/docs/zen/ Pricing table.
Step 2A: Desktop version connection (use this route at the workshop venue)
🖐️ Requires manually clicking the screen.
- Open the OpenCode desktop version
- Go to Settings
- Find the Providers section
- Find OpenCode Zen(if you can't find it, use the search box and type
zenoropencode; the list may require clicking "Show more providers" to fully expand) - Click Connect
- Paste the API key copied in Step 1, then press Continue / Confirm
- Completely close the desktop version and reopen it
⚠️ Do not skip point 7. Newly added providers often require a restart before they appear in the model list.
ℹ️ The actual menu text of the desktop versionis not itemized in the official documentation(the official docs only describe the CLI's
/connectflow); wording may vary slightly between versions. If you can't find it, look for the keywords:Settings→Providers→Connect。
Desktop version won't connect? There are two fallbacks
Fallback 1: Enter the command directly in the chat box
Some versions of the desktop version's chat input box also accept slash commands. Try entering:
/connect
If a menu pops up, follow the Step 2B flow.
Fallback 2: Connect via CLI, then let the desktop version take over
The desktop version runs the same OpenCode server in the background (referred to as opencode-cli sidecar in the official Troubleshooting), and the credentials are the same. So:
- Follow Step 2B to connect the key using the terminal
- Completely close the desktop version and reopen it
- OpenCode Zen will then appear in the model list
❓ The point that "the desktop version and CLI share the same credential file" isnot explicitly stated in the official documentation, and is inferred from "the desktop version runs opencode-cli in the background." The success rate in practice is high, but if it doesn't work, please return to Fallback 1 or work directly with the CLI.
Step 2B: CLI (terminal) connection
On Windows, please use PowerShell, not the old CMD.
2B-1. Launch OpenCode
First switch to your test folder, then launch:
cd ~/Documents/opencode-test
opencode
If Windows can't find the folder, create one first:
mkdir ~/Documents/opencode-test
2B-2. Enter the connection command
In the OpenCode screen, enter:
/connect
2B-3. Select OpenCode Zen
Use the arrow keys to select OpenCode Zen, then press Enter.
⚠️ There is also a similarly named OpenCode Goin the list. That isa paid subscriptionplan, not what this guide is for.This guide only uses OpenCode Zen.
2B-4. Paste the API key
An input box will appear; paste the key and press Enter:
┌ API key
│
│
└ enter
Pasting tips: In Windows PowerShell, right-clicking usually pastes. After pasting, take a look first to see whether the whole string went in.
2B-5. Confirm the credential was saved
Exit OpenCode and run this in the terminal:
opencode auth list
You should be able to see OpenCode Zen-related entries in the list.
Where are credentials stored?(listed explicitly in the official Troubleshooting)
- macOS / Linux：
~/.local/share/opencode/auth.json- Windows: press
WIN+R, paste%USERPROFILE%\.local\share\opencode⚠️ Inside this file is your API key in plaintext. Do not back it up to cloud storage, and do not commit it to Git.
2B-6. You can also connect with pure commands (advanced)
If you don't want to go through the on-screen menu:
opencode auth login
It will likewise ask you which provider you want to connect to and ask you to paste the key.
Step 3: Choose a free model
3-1. Open the model list
In OpenCode, enter:
/models
(Shortcut:ctrl+x then m）
The CLI can also directly list all Zen models:
opencode models opencode
Here,
opencodeis OpenCode Zen'sprovider code（provider id）。
3-2. How to recognize which one is free
Don't memorize the list; learn to check it yourself. Free plans change very quickly, and the official side may add or remove them at any time.
Three ways to check, from highest to lowest reliability:
| Method | How to do it |
|---|---|
| ① Official Pricing table (most accurate) | Open https://opencode.ai/docs/zen/, scroll to Pricing, and those with Input / Output marked as Free are free |
| ② Machine-readable list | The official documentation provides https://opencode.ai/zen/v1/models, which can be used to get the complete model list and metadata |
③ /models to see the names |
Names ending with Free are usually the free ones (butthis is not a guarantee, and ① still takes precedence) |
3-3. Free models found as of 2026-07-27 (⚠️ the list will change; for reference only)
The following are 2026-07-27 found on the official /docs/zen/ Pricing table and marked as Free models:
| Model name | model id (to use in the config file) |
|---|---|
| Big Pickle | big-pickle |
| DeepSeek V4 Flash Free | deepseek-v4-flash-free |
| MiMo-V2.5 Free | mimo-v2.5-free |
| Laguna S 2.1 Free | laguna-s-2.1-free |
| Ling-3.0-flash Free | ling-3.0-flash-free |
| North Mini Code Free | north-mini-code-free |
| Nemotron 3 Ultra Free | nemotron-3-ultra-free |
🔴 This table will definitely become outdated. The official original description of these models is "free for a limited time(available for a limited time)"—they are free only while the vendor is collecting feedback and improving the model. At the moment you are reading this document, be sure to go back to https://opencode.ai/docs/zen/ 's Pricing table and confirm again. The purpose of this table is to "let you know what it looks like," not "copy it and it will work."
3-4. How to write it in the config file
The complete ID format for a model is 供應商代號/模型代號. OpenCode Zen's provider code is opencode。
So the complete form looks like this:
opencode/big-pickle
opencode/deepseek-v4-flash-free
Step 4: Verify it actually works (⭐ do not skip)
"The AI replied" does not mean it works. What is truly useful for a teacher is "it will actually do things for me."
Some cheap or free models are very good at chatting, butcannot call tools correctly(No file creation, no file reading) — if this kind of model is connected, the NotebookLM, Obsidian, and image-generation quick-start guides that followwill all fail, and the error messages will look nothing like a model problem.
So verification should test "whether it actually takes action."
4-1. Test command (works for both desktop and CLI)
Open OpenCode in your test folder and paste this in:
請在目前這個資料夾建立一個檔案叫 test.txt，
內容寫一行：OpenCode 連線成功。
建立完成後，把這個檔案的內容讀出來給我看。
4-2. All three must be seen to pass
| Checkpoint | What passing looks like |
|---|---|
| ① It replies | The AI gives a normal Chinese response, not an error message |
| ② It takes action | You can see on screen its action of "calling a tool to write a file" (it may pop up asking whether you allow it → choose allow) |
| ③ The file is really there | Open the folder,test.txt exists, and the content is correct |
Only ① and not ②③ → The model's tool calling doesn't work; switch to another free model and retest.
4-3. One-line CLI verification (lazy version)
opencode run --model opencode/big-pickle "請在目前資料夾建立 test.txt，內容寫：OpenCode 連線成功"
After running, check the file:
ls test.txt # macOS / Linux
dir test.txt # Windows
--modelFor the part after, replace it with the model id you found in step three that is actually free at the time.
4-4. Clean up after testing
rm test.txt # macOS / Linux
del test.txt # Windows
Step five (optional): Set a commonly used model as the default
It's annoying to reselect every time you open it, so you can write it into the config file.
Config file location(explicitly listed in the official Troubleshooting):
- macOS / Linux：
~/.config/opencode/opencode.json - Windows: press
WIN+R, paste%USERPROFILE%\.config\opencode(filenameopencode.jsonoropencode.jsonc）
Content:
{
"$schema": "https://opencode.ai/config.json",
"model": "opencode/big-pickle"
}
⚠️ Common JSON pitfalls: there must be no comma after the last item; all quotation marks must use English half-width
", not Chinese full-width 「」. If the file doesn't exist, just create a new one.
How to judge "whether this model is suitable for this task"
Echoing OpenCode Basics EP06 "Full Analysis of the Correct Usage of Various Models". Core concept:There is no strongest model, only a model suitable for this task.
Four criteria (think in this order)
| Criterion | In plain terms | How it affects you |
|---|---|---|
| ① Whether it can use tools | Whether it can really create files, modify files, and run commands | As long as it's "asking OpenCode to do something for me," failing this item means immediate elimination.Most important. |
| ② How much text it can handle（context） | How long a piece of content it can read at once | If you want to feed it a whole set of lesson-prep materials or a whole transcript, too small a context will mean it can't finish reading and will forget the earlier parts |
| ③ Fast vs. good | Instant but average vs. slow but refined | Live demonstrations need speed; final reports can be slow |
| ④ Whether the data is sensitive | Whether this content can be shown to the other party | Student personal data, grades, parent information → see the privacy reminder below |
Task comparison table (practical recommendations)
| What you want to do | Selection principle |
|---|---|
| Casual questions, translation, typo correction, brainstorming titles | The cheapest/fastest free model is enough; no need to be picky |
| Ask it to create files, modify files, run the installation process (most quick-start guides） | Prioritize ① tool capabilities. Test with the free one first; only switch if it doesn't pass |
| Read an entire textbook or a full transcript and then organize it | Look at ② context, choose one advertised for long text |
| Write code, build interactive web pages, build Firebase | Choose one whose name contains code / coder or one officially labeled as coding-oriented |
| Plan courses, break down complex tasks, write lesson plan structures | Choose a reasoning type; being a bit slower is fine |
| Heavy, repetitive work that needs to run many times at once | Choose the cheapest and fastest; don't use a large model to crush an ant |
Three practical principles for teachers
- Start with the cheapest one, and switch up only when you get stuck. Don't start with the most expensive one—for most teaching scenarios, a free model is enough.
- Switching models doesn't require redoing settings. The key is connected only once; after that,
/modelsswitch anytime; after switching, it takes effect with the next sentence. - If the same task fails more than twice, switch models before doubting yourself. A lot of "the quick-start guide won't run" is actually because the model doesn't know how to use tools, not because the steps were written wrong.
📎 Official
/docs/models/also points out the same thing: there are many models on the market, butonly a few are good at both coding and calling tools. This is exactly why in Step 4 we test "whether it can create files."
🔒 Privacy reminder (especially important for free models)
Official /docs/zen/ 's Privacy section states in black and white:
- These models during thefree period，may use collected data to improve the model
- Among them, North Mini Code Free and Nemotron 3 Ultra Free additionally note:Do not submit personal or confidential data
In terms teachers can understand:
When using a free model, what you type inmay be kept by the other party to train the model。
Teacher rules (please follow directly)
- ❌ Do not enter: student names, student IDs, national ID numbers, report cards, counseling records, parent contact information, class rosters
- ❌ Do not enter: internal school documents, unpublished exam questions
- ✅ You may enter: public teaching materials, lesson plans you wrote yourself, draft handouts, code, fake data for demonstrations
- ✅ When you need to handle real student data: replace names with "Student A, Student B" before entering, or switch to a paid model with a zero-retention policy
This rule has nothing to do with saving money; it ispersonal data protection. Please be sure to remind attendees at workshops.
Common failures and troubleshooting
| Symptom | Possible cause | How to solve |
|---|---|---|
Unauthorized / invalid api key / 401 |
key pasted incorrectly: pasted only halfway, has leading/trailing spaces, cut off by a line break | Run /connect again and paste again. Before pasting, first confirm in Notepad that the whole string is on the same line |
| After pasting, there is no response and there is nothing in the list | Not restarted | Fully closed OpenCode (the desktop version must be completely terminated, not just the window closed) and reopened |
| A payment required / insufficient balance error appears | A paid model was selected | Go back to /models and switch to a free one. How to confirm: the official Pricing table marks Free |
| It used to work, then one day it suddenly required payment | The free period ended(official wording: available for a limited time) | Go back to https://opencode.ai/docs/zen/ and recheck which Freeare still available, and switch to another one |
ProviderModelNotFoundError |
The model id format is written incorrectly | It must be 供應商/模型, Zen is opencode/<model-id>(example:opencode/big-pickle） |
| Completely unable to connect, keeps spinning, times out | Blocked by the school network | Test once with a phone hotspot: if it works, it is a school network issue, ask the IT department to allow opencode.ai and auth.opencode.ai |
The login page redirects to auth.opencode.ai and it seems suspicious |
Normal redirect | This is the official login domain, not phishing |
| The AI can chat, but cannot create files | The model's tool calling capability is insufficient | Switch to another free model and rerun step four |
The desktop version is stuck on the startup screen / Connection Failed |
A custom server address was set | Check the desktop version's server URL settings according to the official Troubleshooting |
opencode command not found |
#00 was not fully installed | Go back and do #00 environment setup |
| Accidentally pasted the key into a chat room / document | Leaked | Immediately go back to the Console and disable/delete that key, then create a new one |
If it connected to the wrong thing, how to wipe it and start over
Tell OpenCode: "My OpenCode Zen connected to the wrong thing, help me clear it and reconnect."
Or do it manually in order:
Level 1: Reconnect (most common, try this first)
/connect
Select OpenCode Zen again and paste the new key; it will directly overwrite the old one.
Level 2: Remove first, then connect
opencode auth list # 看目前連了哪些
opencode auth logout # 依提示移除指定的供應商
opencode auth login # 重新連
Level 3: Reset settings (last resort)
The official Troubleshooting for ProviderInitError is to delete OpenCode's data directory:
- macOS / Linux：
~/.local/share/opencode - Windows：
%USERPROFILE%\.local\share\opencode
🔴 Warning: this will also clear your past conversation history and session data. Only use it after trying the first two levels. After deleting, rerun
/connectto reconnect.
If the key itself is the problem: go back to https://opencode.ai/auth 's Console, delete the old key, create a new one, then come back and reconnect.
❓ Items in this package that cannot be confirmed from official documentation (please verify on site yourself)
| Item | Status |
|---|---|
| Whether using only free models also requires filling in billing information first | Official /docs/zen/ 's process says "add billing information", but there is no separate explanation for free models.Refer to the backend screen you see. |
| The actual menu text for connecting providers in the desktop version | The official documentation only fully records the CLI's /connect process, the desktop UI does not specify item by item.Refer to the actual screen. |
Whether the desktop version and CLI share the same auth.json |
Officially, only the desktop version's background execution is described opencode-cli sidecar, with no explicit statement that credentials are shared.Base it on actual testing. |
| Whether free models have hidden rate/daily limits | The official Pricing table only indicates Free, without listing the restriction conditions. |
✅ Success signals (machine-readable)
The followingallmust hold for this package to be considered complete:
CHECK_1 `opencode auth list` 輸出包含 OpenCode Zen 的項目
CHECK_2 `/models`（或 `opencode models opencode`）能列出 Zen 的模型清單，且清單非空
CHECK_3 目前選用的 model id 格式為 opencode/<model-id>，且該模型在官方 Pricing 表標示為 Free
CHECK_4 對 agent 下「建立 test.txt」指令後，agent 實際觸發了寫檔工具（非只用文字回覆）
CHECK_5 test.txt 於測試資料夾中實際存在，且內容與指令一致
CHECK_6 測試完成後 test.txt 已刪除
If any item is FAIL → refer to "Common Failures and Troubleshooting" for handling, and do not proceed with other quick-start guides.
Completion report format
## OpenCode 模型連接完成
- OpenCode 版本：<版本>
- 操作路徑：桌面版 / CLI
- Zen 帳號註冊：成功 / 失敗
- API key 取得：成功 / 失敗
- 憑證寫入（opencode auth list）：CHECK_1 PASS / FAIL
- 模型清單可列出：CHECK_2 PASS / FAIL
- 選用模型：opencode/<model-id>（免費 / 付費）
- 免費狀態查證日期：<YYYY-MM-DD>（依官方 /docs/zen/ Pricing 表）
- 工具呼叫測試：CHECK_4 PASS / FAIL
- test.txt 建立驗證：CHECK_5 PASS / FAIL
- 測試檔已清除：CHECK_6 PASS / FAIL
- 預設模型是否寫入 opencode.json：是 / 否
- 隱私提醒已告知使用者：是 / 否
### 待處理
- <把 FAIL 的項目與原因列在這裡；全部 PASS 就寫「無」>
Next steps
Once the model is connected, OpenCode is truly "alive." Next, you can:
02-file-toolkit— Install the internal toolkit so the agent can read PDFs, produce Word documents, and generate speech03-notebooklm— Automatically generate presentations, audio, and infographics07-github— Work backup and cross-computer collaboration
💡 From now on, if any package behaves oddly halfway through, the AI answers randomly or does not act,suspect the model first: go back to
/modelsand switch to another one and try again.