opencode-env-setup

Environment Setup (Lazy Pack #00)

After completing this pack, your computer will have:

Tool	What it is	Who will use it later
OpenCode Desktop	The AI assistant you'll use, with a window interface	The star of the entire workshop
OpenCode CLI	The terminal version of the same tool	Advanced operations, script automation
Git	Helps save files and record every change	The GitHub pack (`07-github`）
GitHub CLI（gh）	Lets AI operate GitHub directly	The GitHub pack (`07-github`）
Node.js	The runtime environment for a bunch of plugins (MCP)	Almost every subsequent pack
uv	The installer for Python tools	Python-based tools such as NotebookLM and the file toolkit

⚠️ After this pack is installed, OpenCode still won't answer you. It's just "installed," and isn't connected to any AI model yet. Be sure to continue with #01: Connect a Model (01-connect-model）, that pack is what will make it actually start working.

What this pack covers and doesn't cover

✅ This pack covers	❌ This pack doesn't cover (who does)
Installing OpenCode Desktop + CLI	Connecting AI models, API keys → `01-connect-model`
Installing Git and GitHub CLI	Logging in to GitHub, setting git user info → `07-github`
Installing Node.js, uv	Installing various MCPs and plugins → subsequent packs
Verifying that each tool actually runs	Teaching you how to use OpenCode → at the workshop

Before You Start: Which Situation Are You In?

This document is meant to be "pasted to an AI agent to execute". But if you don't even have an AI agent yet, there's a chicken-and-egg problem. Find your match:

Situation	What to do
A. I don't have any AI tools	First manually complete Step 2(install OpenCode Desktop—it's just download and double-click). After opening OpenCode, go do #01 Connect a Model, then come back and paste this entire document to it to finish the rest
B. I already have Claude Code / Codex / another agent	Paste this entire document to it and run from Step 1
C. I already have OpenCode and can converse with it	Paste this entire document to OpenCode and run from Step 1

Execution Principles for the AI Agent

When executing this document, please follow:

Detect first, then install: Run the detection command for every tool first; skip anything already present, and don't reinstall.
Verify every step: After installation, you must run the verification command; it only counts as passed when you see the expected output.
Don't force your way through failures: If any single item fails, note it down and continue to the next item, and mark it ❌ in the final report at the end; do not abort the whole thing.
Where manual action is needed, stop: for example, when administrator privileges are required or when you need to click Agree in a browser, clearly tell the user what to do and wait for their reply.
On Windows, always use PowerShell, do not use CMD.
Do not use && to chain commands in PowerShell(Windows PowerShell 5.1 will give a syntax error directly); use ;。
Do not add 2>$null or 2>&1to native commands: PowerShell 5.1 wraps their stderr into error objects, causing you to misjudge a successful installation as a failure. To judge success or failure, look at theoutput content, not just the exit code.
Do not choose a paid plan for the user, and do not enter any keys; that is #01's job.

Step 1: Full detection (first see what you already have)

Windows（PowerShell）

Copy and paste the whole block:

foreach ($c in 'opencode','git','gh','node','npm','uv') {
  $cmd = Get-Command $c -ErrorAction SilentlyContinue
  if ($cmd) { "[有] $c  ->  " + ((& $c --version) | Select-Object -First 1) }
  else { "[缺] $c" }
}
"--- 桌面版 ---"
winget list --id SST.OpenCodeDesktop --exact --accept-source-agreements

macOS / Linux (Terminal)

for c in opencode git gh node npm uv; do
  if command -v "$c" >/dev/null 2>&1; then
    echo "[有] $c  →  $("$c" --version 2>/dev/null | head -n1)"
  else
    echo "[缺] $c"
  fi
done

Judgment: note down the items in [缺] , and only fill in these later. Skip anything marked [有] ; do not reinstall.

💡 Also confirm whether winget is present(only needed on Windows):winget --version. If not present → install "App Installer" from the Microsoft Store, or use the "download page fallback" attached to each step.

Step 2: Install the OpenCode desktop version (main workshop track)

🎯 At the workshop, the desktop version is the main focus. It has a window, you can drag files into it, and you can see code differences; it is the friendliest for teachers encountering it for the first time.

Windows

winget install --id SST.OpenCodeDesktop --exact --accept-source-agreements --accept-package-agreements

Verify:

winget list --id SST.OpenCodeDesktop --exact

Expected output: a table row appears containing SST.OpenCodeDesktop and the version number. What failure looks like：找不到任何符合輸入準則的已安裝套件。

macOS

brew install --cask opencode-desktop

Verify:ls /Applications | grep -i opencode → should list the OpenCode application.

Linux

Go to https://opencode.ai/download to download .deb or .rpm, then:

# Debian / Ubuntu
sudo apt install ./opencode-desktop_*.deb
# Fedora / RHEL
sudo dnf install ./opencode-desktop-*.rpm

🖐️ Common fallback for all platforms

If winget / brew fails (no administrator privileges, company computer locked down, network blocked), always switch to this route:

Open a browser and go to https://opencode.ai/download
choose your system to download (Windows is the installer, macOS is .dmg, Linux is .deb / .rpm）
Double-click to install

ℹ️ The desktop version is currently labeled beta. It is stable for daily use, but occasional minor issues are normal; if you encounter something strange, restart first, then check the common issues table.

Step 3: Install OpenCode CLI (auxiliary)

🎯 The CLI is the terminal version, and it can coexist with the desktop versioncan coexist, and they share configuration files. Later, when you want to write automation scripts or run on a remote machine, you will need it.

Windows

winget install --id SST.opencode --exact --accept-source-agreements --accept-package-agreements

macOS

brew install opencode

Linux

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

Verify (all platforms)

opencode --version

Expected output: a set of version numbers (for example 1.x.x）。 What failure looks like：opencode : 無法辨識… / command not found → see the PATH explanation below.

⚠️ Choose only one installation method; do not mix installations. If on the same computer you install both with winget (or brew) and with npm install -g opencode-ai , there will be two on PATH opencode, upgrading later will be very messy. This package consistently follows "winget / brew / official install scripts"; the npm version is only used as a fallback when none of the first three are available.

🐧 For Linux/macOS use curl … | bash a reminder: This is the installation method announced in the official documentation, but "handing a script from the internet directly to the shell to execute" is essentially trusting that domain. If you're not comfortable with that, use brew (macOS) or download the executable from GitHub Releases.

🪟 Windows cannot use curl … | bash: that is bash syntax, and PowerShell cannot run it. On Windows, use winget.

Step 4: Install Git

🎯 Git saves your files and records every change. Later, the GitHub package (07-github) will use it to push the teaching materials to GitHub. Starting from v2, Git installation is handled by this package and is no longer delegated to another package.

Detect first：git --version If a version number is output, skip this step.

Windows

winget install --id Git.Git --exact --accept-source-agreements --accept-package-agreements

🔒 When there are no administrator privileges(common on school computers): first try winget install --id Git.Git --exact --scope user; if it still fails, go to https://git-scm.com/downloads to download the installer, or ask the IT department for assistance.

📌 By the way, one thing to know: the Windows version of Git also installs "Git Credential Manager" (GCM). It is responsible for remembering your GitHub login. The first time you git push , it will open a browser for you to authorize once, and after that you won't need to enter anything again.

This matters a lot in the 07-github package:GCM's settings are written at the system level, so git config --global cannot find them. Not finding them doesn't mean they aren't there—many people therefore mistakenly think the credentials aren't set up and go fix a problem that doesn't exist at all. See 07-github steps 2-3.

macOS

macOS usually already has Apple's version of Git built in; first run git --version. If it's really not there:

brew install git

(or run xcode-select --install, and the system will pop up a window to guide the installation.)

Linux（Debian / Ubuntu）

sudo apt update && sudo apt install -y git

Verify

git --version

Expected output：git version 2.x.x。

📌 Do not set git config --global user.name / user.emailhere—that belongs to the GitHub package (07-github), to avoid the two packages asking the user the same thing twice.

Step 5: Install GitHub CLI (gh)

🎯 gh lets the AI directly help you create a repo, upload, and open a website, without you having to click through web pages yourself.

Detect first：gh --version If there is output, skip.

Windows

winget install --id GitHub.cli --exact --accept-source-agreements --accept-package-agreements

macOS

brew install gh

Linux（Debian / Ubuntu）

sudo apt update && sudo apt install -y gh

If the package cannot be found (on older distributions), use the official GitHub source instead:

sudo apt install -y curl
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list
sudo apt update && sudo apt install -y gh

Verify

gh --version

Expected output：gh version 2.x.x (…)。

📌 Do not log in at this step。gh auth login requires opening a browser and entering a verification code; that is part of the GitHub package (07-github). Here, only confirm that "it is installed and can be invoked."

Step 6: Install Node.js

🎯 Many MCP plugins later are started with npx , which requires Node.js. OpenCode itself does not need Node.js(it is a standalone executable), so the earlier v1 statement treating Node as a prerequisite for OpenCode was wrong—it is a prerequisite for "the later packages."

Detect first：node --version and npm --version If both have output, skip.

Version requirements

Just install **the current LTS (Long-Term Support) version**; this document deliberately does not pin a version number—the LTS you install in 2026 will not be the same as the one you install in 2027, and pinning it would only make the document outdated. Each command below will automatically fetch the current LTS.

Windows

winget install --id OpenJS.NodeJS.LTS --exact --accept-source-agreements --accept-package-agreements

macOS

brew install node

Linux（Debian / Ubuntu）

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

setup_lts.x will automatically map to "the current LTS," so you do not need to change the document every year (the hardcoded setup_20.x in v1 is already outdated). If you do not want to add an external package repository, you can also sudo apt install -y nodejs npm, but the version built into the distribution is usually older.

Verify

node --version
npm --version

Expected output：node prints a version number starting with v , andnpm prints a numeric version number; both must be present.

Step 7: Install uv

🎯 uv is the installer for Python tools. Python-based tools such as NotebookLM MCP and the teaching file processing toolkit all rely on it for installation. 📌 This is the single authoritative version of the uv installation in the whole all-in-one lazy pack(v1 wrote it once in each of three files, and the versions were even inconsistent). When other packs need uv, always come back to this section.

Detect first：uv --version If there is output, skip it.

Windows (recommended)

winget install --id astral-sh.uv --exact --accept-source-agreements --accept-package-agreements

Official script fallback when winget is unavailable:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS

brew install uv

Linux / general fallback

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify

uv --version

Expected output：uv 0.x.x(or higher).

Step 8: Reopen the terminal, then do the final verification

🚨 This step is the most commonly skipped, and it most often makes people think the installation failed. The tool you just installed will add itself to the system PATH, butan already-open terminal window cannot read the new PATH. So typing git、gh in the old window will definitely say "not found"—it is not that the installation failed, it is that the window is too old.

What to do: close the current PowerShell / terminal,open a new one, then run the verification.

On Windows, if you do not want to close the window, you can refresh PATH in place:

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

macOS / Linux：source ~/.zshrc(or source ~/.bashrc）。

Final verification

Windows (PowerShell, use ; not &&）：

opencode --version; git --version; gh --version; node --version; npm --version; uv --version

macOS / Linux：

opencode --version && git --version && gh --version && node --version && npm --version && uv --version

Expected output: six lines, each line is a version number, with no "command not found" at all.

On Windows, add one more line to confirm the desktop version:

winget list --id SST.OpenCodeDesktop --exact

Step 9: Open the desktop version and take a look

Open from the Start menu / Launchpad / app list OpenCode。
If you can see the main window and it does not crash, this pack is complete.
At this point, if you talk to itit still will not answer, because it is not connected to a model yet—this is normal, not broken.

📎 Appendix: General MCP rules (used by every later pack, take a quick look first)

Starting from 03-notebooklm , almost every pack requires adding a configuration section in the ~/.config/opencode/opencode.json of mcp . The six rules below areshared by every pack, and each pack will not repeat them.When you get stuck installing MCP, come back and check this page first.

🎯 You do not need to take action on this section right now; just know that "this page exists." Come back to check it when you get to the later packs.

1. 🔴 You must add `timeout`, or it will almost certainly go wrong

OpenCode's MCP timeout defaults to only 5000 milliseconds (5 seconds).

Use npx For an MCP that is started for the first time, the package must be downloaded from the internet first, which usually takes far more than 5 seconds → OpenCode immediately determines that the connection failed. At a workshop, an entire classroom downloading at the same time will only be slower.This is the place where the whole class is most likely to get stuck together.

{
  "mcp": {
    "example": {
      "type": "local",
      "command": ["npx", "-y", "某個-mcp-套件"],
      "enabled": true,
      "timeout": 300000
    }
  }
}

300000 milliseconds = 5 minutes. Once a package is downloaded, it will be cached, and subsequent startups will be fast, but keeping this value does not have side effects,just add it to every MCP。

💡 Added it and it still times out? Some versions of OpenCode have unstable support for "a single server's timeout". Add another global setting (at the same level as mcp ):
{
  "experimental": {
    "mcp_timeout": 300000
  }
}

🖐️ Preventive measure for the workshop: the instructor can ask everyone tofirst manually run it once in the terminal npx -y 某個-mcp-套件, so the package is downloaded first (after it runs, press Ctrl+C to stop it). After that, OpenCode will not get stuck downloading when it starts.

2. ✅ For verification use `opencode mcp list`, do not use "restart and ask"

After changing the settings,do notrely on "restart OpenCode and ask it whether it has the tool" to judge success—if it cannot answer, it may just be that it did not think to use it.

opencode mcp list

Expected output: one row per server, with the status showing ✓ connected. Seeing ✓ counts as success; this is the only reliable criterion.

Other related commands:

Command	Purpose
`opencode mcp add`	Interactively add a server (it will write it in the correct format for you, so you do not have to memorize the fields)
`opencode mcp list`	List all servers and connection status ← this is what you check for verification
`opencode mcp auth <名稱>`	Log in to a remote server that supports OAuth (see point 6)
`opencode mcp logout <名稱>`	Clear that server's login credentials
`opencode mcp debug <名稱>`	Check details when it cannot connect

3. ⚠️ Most settings copied from the internet are for Claude Code; pasting them directly will definitely break

OpenCode's field names are incompatible with Claude Code. This is the most common way copying tutorials goes wrong:

Item	Claude Code syntax	OpenCode syntax
Block name	`"mcpServers"`	`"mcp"`
Run command	`"command": "npx"`(string)	`"command": ["npx", …]`(array)
Parameters	`"args": ["-y", "套件名"]`	No `args` field, all merged into the `command` array
Environment variables	`"env": { … }`	`"environment": { … }`
Remote server	`"type": "sse"` / `"http"`	`"type": "remote"` + `"url"`

❌ Incorrect (Claude Code format, OpenCode cannot read it)

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "某個-mcp-套件"],
      "env": { "MY_TOKEN": "abc123" }
    }
  }
}

✅ Correct (OpenCode format)

{
  "mcp": {
    "example": {
      "type": "local",
      "command": ["npx", "-y", "某個-mcp-套件"],
      "environment": { "MY_TOKEN": "{env:MY_TOKEN}" },
      "enabled": true,
      "timeout": 300000
    }
  }
}

Compare them:command and args merge into one array，env rename to environment, and the outermost mcpServers changes to mcp。

4. 💬 OpenCode's config filecanwrite comments,allowtrailing commas

OpenCode parses the config file with JSONC (JSON with Comments), so none of the following will break:

{
  "mcp": {
    // 這行註解是合法的
    "example": {
      "type": "local",
      "command": ["npx", "-y", "某個-mcp-套件"],
      "timeout": 300000,   // 行末註解也可以
    },                     // 最後一項後面多一個逗號，也不會壞
  }
}

The file can also be saved directly as opencode.jsonc。

📌 If you see a tutorial saying "opencode.json absolutely cannot have comments and the last item cannot have a comma"—that is talking about ordinary JSON, and does not apply to OpenCode. ButOther format errors will break it just the same: a missing curly brace, unpaired quotes, a Windows path backslash not written as two \\. So after changing the config, you still need to use opencode mcp list to verify it once.

5. 🔑 Don't write keys in plaintext, use `{env:變數名}`

The config file at the workshop will be projected on a big screen, so a plaintext key is effectively made public on the spot, and it'll get photographed too. OpenCode supports reading values from environment variables:

{
  "mcp": {
    "example": {
      "type": "local",
      "command": ["npx", "-y", "某個-mcp-套件"],
      "environment": { "MY_API_KEY": "{env:MY_API_KEY}" },
      "enabled": true,
      "timeout": 300000
    }
  }
}

How to set environment variables:

Windows (PowerShell, after setting you need torestart the terminalfor it to take effect):

[System.Environment]::SetEnvironmentVariable("MY_API_KEY", "你的金鑰", "User")

macOS / Linux (write into ~/.zshrc or ~/.bashrc）：

export MY_API_KEY="你的金鑰"

You can also change it to read from a file:"MY_API_KEY": "{file:~/.secrets/my-api-key}"。

🖐️ No matter which one you use,never push files containing keys to GitHub(see 07-github). 🖐️ When the key is entered wrong,opencode mcp list usually still shows connected (it can connect, but calls will be rejected). What you really need to verify is actually calling a tool once.

6. 🌐 Remote MCP (`type: "remote"`) is the least hassle: you don't have to deal with tokens at all

Some services directly provide "remote MCP"—you don't need to install anything on your computer, and you don't need to apply for a key. OpenCode supports OAuth automatic registration:

{
  "mcp": {
    "example-remote": {
      "type": "remote",
      "url": "https://某服務的網址/mcp",
      "enabled": true,
      "timeout": 300000
    }
  }
}

Then run once:

opencode mcp auth example-remote

The browser will open an authorization page,just click agree. No need to apply for, copy, or paste any token, and there's no key leak problem.

To switch accounts / start over:opencode mcp logout example-remote, then auth again
Authorization stuck:opencode mcp debug example-remote

💡 As long as a service provides remote MCP, prioritize this route. For teachers with zero programming background, it's an order of magnitude simpler than "install a local tool + apply for a key + paste into config file".

📋 After adding any MCP, wrap up with these four steps

Check the format：command is an array,no args, the environment variable field is called environment, the outer layer is mcp
Add a timeout："timeout": 300000(if it still times out, add more experimental.mcp_timeout）
Completely close OpenCode and reopen it(not closing the window, but ending the whole program)
opencode mcp list → seeing ✓ connected counts as complete

➡️ Next step: #01 Connect a model

The environment is ready, but OpenCode still doesn't have a "brain".Next, do the quick-start guide 01-connect-model, connect the AI model, and it will start answering you and start doing things for you.

npx skills add mathruffian-dot/opencode-lazy-packs --skill 01-connect-model -g -y

Or just tell the AI: "Run quick-start guide 01 for me: connect a model".

Model selection, key application, costs, and quotas are all explained in #01; this guide does not cover them.

🤖 Machine-readable success signals

After running, please output the following block in full, so that subsequent agents (or the "install everything at once" guide) can directly interpret it without needing to understand the Chinese instructions.

=== OPENCODE_ENV_SETUP ===
result=PASS            # PASS | PARTIAL | FAIL
os=windows             # windows | macos | linux
opencode_desktop=ok    # ok | missing | skipped
opencode_cli=1.18.5    # 版本號 | missing
git=2.55.0             # 版本號 | missing
gh=2.96.0              # 版本號 | missing
node=v24.18.0          # 版本號 | missing
npm=11.6.2             # 版本號 | missing
uv=0.11.32             # 版本號 | missing
shell_restarted=yes    # yes | no
next=01-connect-model
=== END ===

Decision rules (agents, please judge according to this, do not decide on your own):

Result	Condition
`PASS`	`git` / `gh` / `node` / `npm` / `uv` all have version numbers,and `opencode_desktop=ok` or `opencode_cli` has a version number (at least one)
`PARTIAL`	OpenCode (either desktop or CLI) is present, but at least one other tool is missing
`FAIL`	Neither the desktop version nor the CLI installed successfully

PASS only means "the tools are all installed,"it does not mean OpenCode is usable. Whether it is usable is determined by #01.

Completion report template (for humans)

## 環境建置完成

| 項目 | 狀態 | 版本 |
|------|------|------|
| OpenCode 桌面版 | ✅ 已安裝 / ⚠️ 已補裝 / ❌ 失敗 | — |
| OpenCode CLI | ✅ / ⚠️ / ❌ | v… |
| Git | ✅ / ⚠️ / ❌ | … |
| GitHub CLI | ✅ / ⚠️ / ❌ | … |
| Node.js | ✅ / ⚠️ / ❌ | … |
| uv | ✅ / ⚠️ / ❌ | … |

- 作業系統：Windows / macOS / Linux
- 終端機已重開：是 / 否
- 需要你手動處理的事：（沒有 / 條列）
- 下一步：懶人包 #01 連接模型 → OpenCode 才會開始回答你

(✅ already there ／ ⚠️ installed this time ／ ❌ failed; if failed, you must write the reason.)

If the installation is broken, how to start over

Tell the AI: "Last time the environment setup didn't finish; help me check the current state and fill in what's missing."

Remove a single tool and reinstall it:

# Windows
winget uninstall --id SST.OpenCodeDesktop --exact
winget uninstall --id SST.opencode --exact

# macOS
brew uninstall --cask opencode-desktop
brew uninstall opencode

After removal, just return to step 1 and re-detect.There is no need to remove and reinstall Git, Node.js, or uv—an older version does not affect this package; if you really need to update, use winget upgrade --id <ID> or brew upgrade <名稱>。

Common issues

Problem	Solution
After installation, the command says "not found"	Nine times out of ten it's this: close the terminal and reopen it (see step 8). Only if it still doesn't work, check PATH
`winget` this command does not exist	Built into Windows 10 1809 and later. If not, install "App Installer" from the Microsoft Store, or use the download page fallback in each step
winget says administrator privileges are required	First try adding `--scope user`; if that doesn't work, use the installer from the official download page, or ask the school IT team for help
In PowerShell, typing `A && B` is a direct syntax error	Windows PowerShell 5.1 does not support `&&`, use `;` as the separator
`curl … \| bash` does not run on Windows	That is bash syntax. On Windows, use winget; don't force it in PowerShell
PowerShell says script execution is disabled	uv's script fallback already includes `-ExecutionPolicy ByPass`; paste the whole thing as-is, don't split it apart
After opening the desktop version, typing does nothing	Normal, no model is connected yet → go do #01
There are two `opencode`on the computer, with different versions	Mixed installation (winget + npm). Keep one and remove the other; see the warning in step 3
The Windows username is in Chinese, and some tools report errors	A few tools have problems with non-ASCII paths. If you get stuck, put the project under `C:\projects\` an all-English path like this
The school network blocks downloads / keeps timing out	Campus firewall or Proxy. Use a phone hotspot instead, or ask the IT team to allow `opencode.ai`、`github.com`、`npmjs.org`、`astral.sh` open up
On Linux, `apt` cannot find `gh`	Use the official GitHub package source section from step 5
Everything is installed, but OpenCode still doesn't answer	This packagewas never going tomake it answer. Please do #01 to connect a model

About this skill

What this pack covers and doesn't cover

Before You Start: Which Situation Are You In?

Execution Principles for the AI Agent

Step 1: Full detection (first see what you already have)

Windows（PowerShell）

macOS / Linux (Terminal)

Step 2: Install the OpenCode desktop version (main workshop track)

Windows

macOS

Linux

🖐️ Common fallback for all platforms

Step 3: Install OpenCode CLI (auxiliary)

Windows

macOS

Linux

Verify (all platforms)

Step 4: Install Git

Windows

macOS

Linux（Debian / Ubuntu）

Verify

Step 5: Install GitHub CLI (gh)

Windows

macOS

Linux（Debian / Ubuntu）

Verify

Step 6: Install Node.js

Version requirements

Windows

macOS

Linux（Debian / Ubuntu）

Verify

Step 7: Install uv

Windows (recommended)

macOS

Linux / general fallback

Verify

Step 8: Reopen the terminal, then do the final verification

Final verification

Step 9: Open the desktop version and take a look

📎 Appendix: General MCP rules (used by every later pack, take a quick look first)

1. 🔴 You must add timeout, or it will almost certainly go wrong

2. ✅ For verification use opencode mcp list, do not use "restart and ask"

3. ⚠️ Most settings copied from the internet are for Claude Code; pasting them directly will definitely break

4. 💬 OpenCode's config filecanwrite comments,allowtrailing commas

5. 🔑 Don't write keys in plaintext, use {env:變數名}

6. 🌐 Remote MCP (type: "remote") is the least hassle: you don't have to deal with tokens at all

📋 After adding any MCP, wrap up with these four steps

➡️ Next step: #01 Connect a model

🤖 Machine-readable success signals

Completion report template (for humans)

If the installation is broken, how to start over

Common issues

1. 🔴 You must add `timeout`, or it will almost certainly go wrong

2. ✅ For verification use `opencode mcp list`, do not use "restart and ask"

5. 🔑 Don't write keys in plaintext, use `{env:變數名}`

6. 🌐 Remote MCP (`type: "remote"`) is the least hassle: you don't have to deal with tokens at all