opencode-env-setup

@mathruffian-dot · 收录于昨天 · 上游提交昨天

從零把 OpenCode 環境裝好——OpenCode 桌面版與 CLI、Git、GitHub CLI、Node.js、uv，先偵測再安裝、每步驗證。說「建置環境」「安裝 OpenCode」「安裝開發環境」「環境建置」時載入。

场景环境配置首次安装

适合你，如果需要在电脑上从零配置 OpenCode 开发所需工具

/ 下载安装

https://github.com/mathruffian-dot/opencode-lazy-packs/tree/main/skills/00-env-setup ↗

/ 通过 npx 安装 校验哈希

npx oh-my-skill add mathruffian-dot/opencode-lazy-packs/opencode-env-setup

/ 通过 bash 安装

curl -fsSL https://oh-my-skill.com/install.sh | bash -s -- mathruffian-dot/opencode-lazy-packs/opencode-env-setup

/ 已经装过?验证本机副本,不用重装

npx oh-my-skill verify mathruffian-dot/opencode-lazy-packs/opencode-env-setup

安装目标可用 --agent / --scope 或 --to 明确指定;省略时只会在唯一已存在的 agent 目录上自动选择,零命中或多命中会停止并提示。content_hash 缺失或不一致均拒装。

53GitHub stars

~7.3K上下文体积 · 单文件

索引托管

怎么用

商店整理自技能原文 · 版本 1d61b46 · 表述以原文为准

它做什么

当你需要搭建 OpenCode 开发环境时，Claude 会先检查你的电脑上是否已安装 OpenCode 桌面版、CLI、Git、GitHub CLI、Node.js、uv 等工具，然后自动安装缺失的组件，每步都会验证成功后才继续。

什么时候触发

当你说出「建置环境」「安装 OpenCode」「安装开发环境」等关键词时触发。

装好后可以这样说

Claude 会开始检测并安装所需工具

Claude 会自动检测现有版本，跳过已装的

Claude 会依次检查并安装 Git、Node.js 等

技能原文 SKILL.md作者撰写 · MIT · 1d61b46

環境建置（懶人包 #00）

做完這一包，你的電腦會有：

| 工具 | 是什麼 | 之後誰會用到 | |------|--------|--------------| | OpenCode 桌面版 | 你要用的 AI 助手，有視窗介面 | 研習全程的主角 | | OpenCode CLI | 同一個工具的終端機版本 | 進階操作、腳本自動化 | | Git | 幫檔案存檔、記錄每次修改 | GitHub 那一包（07-github） | | GitHub CLI（gh） | 讓 AI 直接操作 GitHub | GitHub 那一包（07-github） | | Node.js | 一堆外掛（MCP）的執行環境 | 後續幾乎每一包 | | uv | Python 工具的安裝器 | NotebookLM、檔案工具包等 Python 系工具 |

⚠️ 這一包裝完，OpenCode 還不會回答你。 它只是「裝好了」，還沒有連上任何 AI 模型。 請務必接著做 #01：連接模型（01-connect-model），那一包才會讓它真的開始工作。

這包負責什麼、不負責什麼

| ✅ 這包負責 | ❌ 這包不負責（誰負責） | |------------|----------------------| | 安裝 OpenCode 桌面版 + CLI | 連接 AI 模型、API 金鑰 → 01-connect-model | | 安裝 Git 與 GitHub CLI | 登入 GitHub、設定 git 使用者資訊 → 07-github | | 安裝 Node.js、uv | 安裝各種 MCP 與外掛 → 後續各包 | | 驗證每個工具真的能跑 | 教你怎麼用 OpenCode → 研習現場 |

開始之前：你現在是哪一種狀況？

這份文件是「貼給 AI agent 執行」用的。但如果你連 AI agent 都還沒有，會有雞生蛋問題。對號入座：

| 狀況 | 怎麼做 | |------|--------| | A. 我什麼 AI 工具都沒有 | 先自己手動做完 步驟 2（裝 OpenCode 桌面版，就是下載點兩下）。打開 OpenCode 後，去做 #01 連接模型，回來把這份整份貼給它做完剩下的 | | B. 我已經有 Claude Code / Codex / 其他 agent | 直接把這份整份貼給它，從步驟 1 開始跑 | | C. 我已經有 OpenCode 而且能對話了 | 直接把這份整份貼給 OpenCode，從步驟 1 開始跑 |

給 AI Agent 的執行原則

執行這份文件時請遵守：

先偵測再安裝：每個工具都先跑偵測指令，已經有的就跳過，不要重裝。
每步都要驗證：安裝完一定要跑驗證指令，看到預期輸出才算過。
失敗不要硬闖：某一項失敗就記下來繼續下一項，最後在回報裡標 ❌，不要整份中斷。
需要人手動的地方要停下來：例如需要管理員權限、需要在瀏覽器點同意，明白告訴使用者要做什麼，等他回覆。
Windows 一律用 PowerShell，不要用 CMD。
不要在 PowerShell 用 && 串指令（Windows PowerShell 5.1 會直接語法錯誤），要用 ;。
不要對原生指令加 2>$null 或 2>&1：PowerShell 5.1 會把它們的 stderr 包成錯誤物件，讓你把成功的安裝誤判成失敗。判斷成敗請看輸出內容，不要只看 exit code。
不要幫使用者選付費方案、不要輸入任何金鑰，那是 #01 的事。

步驟 1：全面偵測（先看你已經有什麼）

Windows（PowerShell）

整段複製貼上：

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（終端機）

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

判定：把 [缺] 的項目記下來，後面只補這些。標 [有] 的一律跳過，不要重裝。

💡 順便確認 winget 在不在（Windows 才需要）：winget --version。沒有的話 → 到 Microsoft Store 安裝「應用程式安裝程式 / App Installer」，或用各步驟附的「下載頁備案」。

步驟 2：安裝 OpenCode 桌面版（研習主線）

🎯 研習現場以桌面版為主。有視窗、可以拖檔案進去、看得到程式碼差異，對第一次接觸的老師最友善。

Windows

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

驗證：

winget list --id SST.OpenCodeDesktop --exact

預期輸出：出現一行含有 SST.OpenCodeDesktop 和版本號的表格列。 失敗長相：找不到任何符合輸入準則的已安裝套件。

macOS

brew install --cask opencode-desktop

驗證：ls /Applications | grep -i opencode → 應列出 OpenCode 應用程式。

Linux

到 <https://opencode.ai/download> 下載 .deb 或 .rpm，然後：

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

🖐️ 所有平台的共同備案

winget / brew 失敗（沒有管理員權限、公司電腦鎖住、網路擋住），一律改走這條：

開瀏覽器到 <https://opencode.ai/download>
選你的系統下載（Windows 是安裝檔、macOS 是 .dmg、Linux 是 .deb / .rpm）
點兩下安裝

ℹ️ 桌面版目前標示為 beta。日常使用穩定，但偶爾有小狀況屬正常；遇到怪事先重開，再看常見問題表。

步驟 3：安裝 OpenCode CLI（輔助）

🎯 CLI 是終端機版本，跟桌面版可以並存，設定檔共用。之後要寫自動化腳本、要在遠端機器上跑，會需要它。

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

驗證（所有平台）

opencode --version

預期輸出：一組版本號（例如 1.x.x）。 失敗長相：opencode : 無法辨識… / command not found → 見下方 PATH 說明。

⚠️ 只選一種安裝方式，不要混裝。 同一台電腦上如果既用 winget（或 brew）裝、又用 npm install -g opencode-ai 裝，PATH 上會有兩個 opencode，之後升級會很混亂。本包一律以「winget / brew / 官方安裝腳本」為準；npm 版只在前三者都不可用時當備案。

🐧 Linux/macOS 用 curl … | bash 的一句提醒：這是官方文件公告的安裝方式，但「把網路上的腳本直接交給 shell 執行」本質上就是信任該網域。不放心的話，改用 brew（macOS）或到 GitHub Releases 下載執行檔。

🪟 Windows 不能用 curl … | bash：那是 bash 語法，PowerShell 跑不動。Windows 請用 winget。

步驟 4：安裝 Git

🎯 Git 幫你的檔案存檔、記錄每一次修改。之後 GitHub 那一包（07-github）要用它把教材推上 GitHub。 v2 起，Git 的安裝由本包負責，不再推給別包。

先偵測：git --version 有輸出版本號就跳過這步。

Windows

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

🔒 沒有管理員權限時（學校電腦常見）：先試 winget install --id Git.Git --exact --scope user；仍失敗就到 <https://git-scm.com/downloads> 下載安裝檔，或請資訊組協助。

📌 順便知道一件事：Windows 版的 Git 會一起裝「Git Credential Manager」(GCM)。 它負責記住你的 GitHub 登入，第一次 git push 時會開瀏覽器讓你授權一次，之後就不用再輸入任何東西。這件事在 07-github 那一包很重要：GCM 的設定寫在 system 層，用 git config --global 查不到。查不到不代表沒有——很多人因此誤以為憑證沒設好，跑去修一個根本不存在的問題。詳見 07-github 的步驟 2-3。

macOS

macOS 通常已內建 Apple 版 Git，先跑 git --version。真的沒有：

brew install git

（或執行 xcode-select --install，系統會跳視窗引導安裝。）

Linux（Debian / Ubuntu）

sudo apt update && sudo apt install -y git

驗證

git --version

預期輸出：git version 2.x.x。

📌 不要在這裡設定 git config --global user.name / user.email——那屬於 GitHub 那一包（07-github），避免兩包重複問使用者同一件事。

步驟 5：安裝 GitHub CLI（gh）

🎯 gh 讓 AI 可以直接幫你開 repo、上傳、開網站，不用你自己點網頁。

先偵測：gh --version 有輸出就跳過。

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

找不到套件的話（較舊的發行版），改用 GitHub 官方來源：

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

驗證

gh --version

預期輸出：gh version 2.x.x (…)。

📌 這一步不要登入。gh auth login 需要開瀏覽器輸入驗證碼，是 GitHub 那一包（07-github）的內容。這裡只確認「裝好了、叫得動」。

步驟 6：安裝 Node.js

🎯 之後很多 MCP 外掛是用 npx 啟動的，那需要 Node.js。 OpenCode 本身不需要 Node.js（它是獨立執行檔），所以先前 v1 把 Node 當成 OpenCode 的前置條件是寫錯的——它是「後面幾包」的前置條件。

先偵測：node --version 與 npm --version 都有輸出就跳過。

版本要求

裝目前的 LTS（長期支援版）即可，本文件刻意不釘死版本號——你在 2026 年裝到的 LTS 和 2027 年裝到的不會一樣，釘死只會讓文件過期。下面每個指令都會自動抓當下的 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 會自動對應到「當下的 LTS」，不需要每年改文件（v1 寫死的 setup_20.x 已經過時了）。若不想加外部套件庫，也可以 sudo apt install -y nodejs npm，但發行版內建的版本通常較舊。

驗證

node --version
npm --version

預期輸出：node 印出 v 開頭的版本號、npm 印出數字版本號，兩個都要有。

步驟 7：安裝 uv

🎯 uv 是 Python 工具的安裝器。NotebookLM MCP、教學檔案處理工具包等 Python 系工具都靠它安裝。 📌 這是全套懶人包裡 uv 安裝的唯一權威版本（v1 在三個檔案裡各寫一次，版本還不一致）。其他包需要 uv 時，一律回來看這一節。

先偵測：uv --version 有輸出就跳過。

Windows（建議）

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

winget 不可用時的官方腳本備案：

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

macOS

brew install uv

Linux / 通用備案

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

驗證

uv --version

預期輸出：uv 0.x.x（或更高）。

步驟 8：重開終端機，然後做最終驗證

🚨 這一步最常被跳過，也最常害人以為安裝失敗。 剛剛裝的工具會把自己加進系統 PATH，但已經開著的終端機視窗讀不到新的 PATH。所以在舊視窗打 git、gh 一定會說「找不到」——不是沒裝好，是視窗太舊。

做法：關掉目前的 PowerShell / 終端機，開一個新的，再跑驗證。

Windows 若不想關視窗，可以就地刷新 PATH：

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

macOS / Linux：source ~/.zshrc（或 source ~/.bashrc）。

最終驗證

Windows（PowerShell，用 ; 不是 &&）：

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

預期輸出：六行，每行都是版本號，沒有任何「找不到指令」。

Windows 再補一行確認桌面版：

winget list --id SST.OpenCodeDesktop --exact

步驟 9：把桌面版打開來看一眼

從開始功能表 / 啟動台 / 應用程式清單開啟 OpenCode。
能看到主視窗、不會閃退，這一包就算完成。
這時候你跟它講話它還不會回答，因為還沒接上模型——這是正常的，不是壞掉。

📎 附錄：MCP 通用守則（後面每一包都會用到，先看一眼）

從 03-notebooklm 開始，幾乎每一包都要在 ~/.config/opencode/opencode.json 的 mcp 區塊加一段設定。下面六條是每一包共用的，各包不再重複說明。裝 MCP 卡住的時候，先回來對這一頁。

🎯 這一節現在不用動手，只要知道「有這一頁」就好。等你做到後面幾包再回來查。

1. 🔴 一定要加 `timeout`，不加幾乎必翻車

OpenCode 的 MCP 逾時預設只有 5000 毫秒（5 秒）。

用 npx 啟動的 MCP，第一次要先上網把套件下載下來，通常遠超過 5 秒 → OpenCode 直接判定連線失敗。研習現場整間教室同時下載，只會更慢。這是最容易整班一起卡住的地方。

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

300000 毫秒 = 5 分鐘。套件下載過一次會被快取，之後啟動很快，但這個值留著不會有副作用，每一台 MCP 都加上去就對了。

💡 加了還是逾時？ 部分版本的 OpenCode 對「單一 server 的 timeout」支援不穩定。再補一個全域設定（跟 mcp 同一層）： ``json { "experimental": { "mcp_timeout": 300000 } } ``

🖐️ 研習現場的預防針：講師可以請大家先在終端機手動跑一次 npx -y 某個-mcp-套件，讓套件先下載完（跑起來後按 Ctrl+C 中止即可）。之後 OpenCode 啟動就不會卡在下載。

2. ✅ 驗證用 `opencode mcp list`，不要用「重開問問看」

改完設定，不要靠「重開 OpenCode，問它有沒有工具」來判斷成功——問不出來也可能只是它沒想到要用。

opencode mcp list

預期輸出：每一台 server 一列，狀態顯示 ✓ connected。看到 ✓ 才算成功，這是唯一可靠的判準。

其他相關指令：

| 指令 | 用途 | |------|------| | opencode mcp add | 互動式新增一台 server（會幫你寫成正確格式，不用背欄位） | | opencode mcp list | 列出所有 server 與連線狀態 ← 驗證就看這個 | | opencode mcp auth <名稱> | 對支援 OAuth 的遠端 server 登入（見第 6 點） | | opencode mcp logout <名稱> | 清掉該 server 的登入憑證 | | opencode mcp debug <名稱> | 連不上時看細節 |

3. ⚠️ 網路上抄來的設定多半是 Claude Code 的，直接貼一定壞

OpenCode 的欄位名稱跟 Claude Code 不相容。 這是照抄教學最常見的死法：

| 項目 | Claude Code 的寫法 | OpenCode 的寫法 | |------|-------------------|-----------------| | 區塊名稱 | "mcpServers" | "mcp" | | 執行指令 | "command": "npx"（字串） | "command": ["npx", …]（陣列） | | 參數 | "args": ["-y", "套件名"] | 沒有 args 欄位，全部併進 command 陣列 | | 環境變數 | "env": { … } | "environment": { … } | | 遠端 server | "type": "sse" / "http" | "type": "remote" + "url" |

❌ 錯誤（Claude Code 的格式，OpenCode 讀不懂）

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

✅ 正確（OpenCode 的格式）

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

對照著看：command 和 args 合併成一個陣列，env 改名叫 environment，最外層 mcpServers 改成 mcp。

4. 💬 OpenCode 的設定檔可以寫註解、容許尾逗號

OpenCode 用 JSONC（JSON with Comments）解析設定檔，所以下面這些都不會壞：

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

檔案也可以直接存成 opencode.jsonc。

📌 如果你看到某份教學說「opencode.json 絕對不能有註解、最後一項不能有逗號」——那是在講一般 JSON，對 OpenCode 不適用。 但其他格式錯誤照樣會壞：大括號少一個、引號沒成對、Windows 路徑的反斜線沒寫成兩條 \\。所以設定改完，還是要用 opencode mcp list 驗一次。

5. 🔑 金鑰不要寫明文，用 `{env:變數名}`

研習現場的設定檔會投影在大螢幕上，明文金鑰等於當場公開，還會被拍照。 OpenCode 支援從環境變數讀值：

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

怎麼設環境變數：

Windows（PowerShell，設完要重開終端機才生效）：

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

macOS / Linux（寫進 ~/.zshrc 或 ~/.bashrc）：

export MY_API_KEY="你的金鑰"

也可以改成讀檔："MY_API_KEY": "{file:~/.secrets/my-api-key}"。

🖐️ 不管用哪種，都不要把含金鑰的檔案推上 GitHub（見 07-github）。 🖐️ 金鑰打錯時，opencode mcp list 通常仍顯示 connected（連得上、但呼叫會被拒絕）。真正要驗的是實際叫一次工具。

6. 🌐 遠端 MCP（`type: "remote"`）最省事：完全不用管 token

有些服務直接提供「遠端 MCP」——不用在你電腦上裝任何東西，也不用申請金鑰。OpenCode 支援 OAuth 自動註冊：

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

然後跑一次：

opencode mcp auth example-remote

瀏覽器會開啟授權頁，按同意就好。不需要申請、複製、貼上任何 token，也沒有金鑰外洩的問題。

要換帳號 / 重來：opencode mcp logout example-remote，再 auth 一次
授權卡住：opencode mcp debug example-remote

💡 只要某個服務有提供遠端 MCP，優先走這條。 對零程式基礎的老師來說，它比「本機安裝工具 + 申請金鑰 + 貼進設定檔」簡單一個數量級。

📋 加完任何一台 MCP，照這四步收尾

對格式：command 是陣列、沒有 args、環境變數欄位叫 environment、外層是 mcp
加逾時："timeout": 300000（還逾時就再補 experimental.mcp_timeout）
完全關閉 OpenCode 再重開（不是關視窗，是整個結束程式）
opencode mcp list → 看到 ✓ connected 才算完成

➡️ 下一步：#01 連接模型

環境有了，但 OpenCode 還沒有「腦」。接著做懶人包 01-connect-model，把 AI 模型接上去，它才會開始回答你、開始幫你做事。

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

或直接對 AI 說：「幫我跑懶人包 01：連接模型」。

模型選擇、金鑰申請、費用、額度，全部在 #01 說明，本包不涉及。

🤖 機器可判讀的成功訊號

執行完請完整輸出下面這個區塊，讓後續的 agent（或「一次全裝」那一包）可以直接判讀，不必讀懂中文說明。

=== 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 ===

判定規則（agent 請照這個判斷，不要自行認定）：

| 結果 | 條件 | |------|------| | PASS | git / gh / node / npm / uv 全部有版本號，且 opencode_desktop=ok 或 opencode_cli 有版本號（至少一個） | | PARTIAL | OpenCode（桌面或 CLI 任一）有了，但其他工具至少缺一個 | | FAIL | 桌面版和 CLI 都沒裝成功 |

PASS 只代表「工具都裝好了」，不代表 OpenCode 可以使用。可用與否由 #01 判定。

完成回報範本（給人看的）

## 環境建置完成

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

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

（✅ 本來就有／ ⚠️ 這次補裝的／ ❌ 失敗，失敗一定要寫原因。）

如果裝壞了，如何重來

對 AI 說：「上次環境建置沒跑完，幫我檢查現況，把缺的補上。」

單獨移除某個工具重裝：

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

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

移除後回到步驟 1 重新偵測即可。Git、Node.js、uv 沒必要移除重裝——版本舊不影響本包，真的要更新用 winget upgrade --id <ID> 或 brew upgrade <名稱>。

常見問題

| 問題 | 解法 | |------|------| | 裝完了但打指令說「找不到」 | 九成是這個：關掉終端機重開（見步驟 8）。仍不行才查 PATH | | winget 這個指令不存在 | Windows 10 1809 以上內建。沒有就到 Microsoft Store 裝「應用程式安裝程式 / App Installer」，或改用各步驟的下載頁備案 | | winget 說需要系統管理員權限 | 先試加 --scope user；不行就用官方下載頁的安裝檔，或請學校資訊組協助 | | PowerShell 打 A && B 直接語法錯誤 | Windows PowerShell 5.1 不支援 &&，改用 ; 分隔 | | curl … \| bash 在 Windows 跑不動 | 那是 bash 語法。Windows 請用 winget，不要在 PowerShell 硬跑 | | PowerShell 說指令碼執行被停用 | uv 的腳本備案已含 -ExecutionPolicy ByPass；請照原樣整段貼上，不要拆開 | | 桌面版打開後打字沒反應 | 正常，還沒接模型 → 去做 #01 | | 電腦裡有兩個 opencode，版本不一樣 | 混裝了（winget + npm）。留一個、移除另一個，見步驟 3 的警告 | | Windows 使用者名稱是中文，某些工具報錯 | 少數工具對非 ASCII 路徑有問題。若卡住，改把專案放在 C:\projects\ 這類純英文路徑下 | | 學校網路擋下載 / 一直逾時 | 校園防火牆或 Proxy。改用手機熱點，或請資訊組把 opencode.ai、github.com、npmjs.org、astral.sh 開通 | | Linux 上 apt 找不到 gh | 用步驟 5 的 GitHub 官方套件來源那段 | | 一切都裝好了，但 OpenCode 還是不回答 | 這包本來就不會讓它回答。請做 #01 連接模型 |

按 MIT 许可原样转载,未经改动 · 在 GitHub 查看 →

登录即可评论;带「已验证安装」的,是发布者名下有本店的安装或持有记录。

…

opencode-env-setup

怎么用

環境建置（懶人包 #00）

這包負責什麼、不負責什麼

開始之前：你現在是哪一種狀況？

給 AI Agent 的執行原則

步驟 1：全面偵測（先看你已經有什麼）

Windows（PowerShell）

macOS / Linux（終端機）

步驟 2：安裝 OpenCode 桌面版（研習主線）

Windows

macOS

Linux

🖐️ 所有平台的共同備案

步驟 3：安裝 OpenCode CLI（輔助）

Windows

macOS

Linux

驗證（所有平台）

步驟 4：安裝 Git

Windows

macOS

Linux（Debian / Ubuntu）

驗證

步驟 5：安裝 GitHub CLI（gh）

Windows

macOS

Linux（Debian / Ubuntu）

驗證

步驟 6：安裝 Node.js

版本要求

Windows

macOS

Linux（Debian / Ubuntu）

驗證

步驟 7：安裝 uv

Windows（建議）

macOS

Linux / 通用備案

驗證

步驟 8：重開終端機，然後做最終驗證

最終驗證

步驟 9：把桌面版打開來看一眼

📎 附錄：MCP 通用守則（後面每一包都會用到，先看一眼）

1. 🔴 一定要加 timeout，不加幾乎必翻車

2. ✅ 驗證用 opencode mcp list，不要用「重開問問看」

3. ⚠️ 網路上抄來的設定多半是 Claude Code 的，直接貼一定壞

4. 💬 OpenCode 的設定檔可以寫註解、容許尾逗號

5. 🔑 金鑰不要寫明文，用 {env:變數名}

6. 🌐 遠端 MCP（type: "remote"）最省事：完全不用管 token

📋 加完任何一台 MCP，照這四步收尾

➡️ 下一步：#01 連接模型

🤖 機器可判讀的成功訊號

完成回報範本（給人看的）

如果裝壞了，如何重來

常見問題

评论

1. 🔴 一定要加 `timeout`，不加幾乎必翻車

2. ✅ 驗證用 `opencode mcp list`，不要用「重開問問看」

5. 🔑 金鑰不要寫明文，用 `{env:變數名}`

6. 🌐 遠端 MCP（`type: "remote"`）最省事：完全不用管 token