1. 项目概述：这不是装个软件，而是给你的终端装上“AI编程副驾驶”

“阿超会手把手教你 安装 OpenCode，5分钟搞定环境配置！”——看到这个标题，别急着点开视频。先问自己一句：你真以为这只是教你怎么敲几行命令、改个配置文件？错了。OpenCode 不是 VS Code 的插件，也不是 PyCharm 的一个新主题；它是一个运行在终端里的 AI Coding Agent，本质是把 StepFun 的 Step 系列大模型（比如 step-3.7-flash）直接塞进你的 shell 里，让你用自然语言指令驱动整个开发流程：生成函数、重构模块、分析报错、甚至解释一段陌生的 C++ 源码。它不依赖 GUI，不启动 Electron 进程，不占用 2GB 内存，只靠opencode这个命令，在你每天打开的 Terminal 或 PowerShell 里，就完成原本要切窗口、查文档、写草稿、反复调试的整套动作。所以，“5分钟搞定环境配置”的真正含义，不是“快”，而是“精准”——快的前提是避开所有国内开发者踩过的典型深坑：npm.ps1 脚本执行被禁、brew 命令找不到、choco 安装卡死、zsh 配置文件路径写错、API Key 环境变量没生效、opencode.json 的 Base URL 指向了普通付费接口而非 Step Plan 专属端点……这些坑每一个都足以让一个有经验的工程师卡住半小时以上。我带过十几支开发团队，从实习生到架构师，90% 的人第一次失败，都不是因为不会写代码，而是因为没搞懂：OpenCode 的配置核心从来不在“装”，而在“连”——连对 API 地址，连对认证凭证，连对模型路由。它不像 Node.js 那样装完就能跑node -v，也不像 Python 那样配好 PATH 就能python --version；它的“hello world”必须是opencode启动后，输入/models能看到stepfun/step-3.7-flash，再输入Create a hello world script in Python，终端里立刻返回print("Hello, world!")。少了这最后一步验证，前面所有操作都是空中楼阁。所以这篇内容，不讲废话，不堆概念，只聚焦一件事：用最短路径、最稳方案、最细颗粒度，帮你把 OpenCode 的终端入口，稳稳地焊死在你的开发工作流里。无论你是 macOS 用户被zsh: command not found: brew折磨过，还是 Windows 用户对着npm : 无法加载文件 c:\program files\nodejs\npm.ps1的红色报错发呆，或是 Linux 用户在 WSL 里反复source ~/.bashrc却发现opencode --version依然报错——这里都有你缺的那一块拼图。

2. 核心设计思路与方案选型逻辑：为什么推荐这四条安装路径？

OpenCode 官方提供了至少五种安装方式：curl 脚本、Homebrew、Chocolatey、Scoop 和 npm 全局安装。但“有选择”不等于“随便选”。我在实际带团队落地时，会根据操作系统、网络环境、用户权限和长期维护成本，强制锁定其中一条作为主推路径，并明确告知其他路径的适用边界和潜在风险。这不是拍脑袋决定，而是基于上千次真实部署记录总结出的“最小阻力路径”。

2.1 macOS：Homebrew 是唯一值得无脑推荐的方案

很多人看到curl -fsSL https://opencode.ai/install | bash这行命令，第一反应是“够简单，就用它”。但实测下来，在国内网络环境下，这条命令的失败率高达 65%。原因很直接：脚本内部会调用curl从 GitHub Releases 下载二进制包，而 GitHub 的 CDN 在国内节点极不稳定，经常出现Connection timed out或Failed to connect。更麻烦的是，一旦下载中断，脚本不会自动重试，也不会清理临时文件，你得手动rm -rf /tmp/opencode*，再重新执行，陷入“下载-中断-清理-重试”的死循环。相比之下，brew install anomalyco/tap/opencode的优势在于：Homebrew 本身已内置了国内镜像源（如清华、中科大），且具备断点续传和校验机制。当你执行brew install时，它会先从镜像站拉取 formula（配方文件），再根据 formula 中定义的 URL 和 SHA256 值去下载二进制，下载失败自动重试，校验失败自动报错并提示你brew cleanup。更重要的是，Homebrew 的安装路径是/opt/homebrew/bin/opencode（Apple Silicon）或/usr/local/bin/opencode（Intel），这两个路径天然就在 macOS 的默认$PATH里，装完即用，无需任何额外的export PATH操作。我试过用 curl 脚本装完后，which opencode返回空，查了半天才发现脚本把二进制放到了/usr/local/share/opencode/bin/，而这个路径根本不在$PATH里。这就是“看似简单”背后的隐形成本。所以，对 macOS 用户，我的建议是：忘掉 curl 脚本，直接brew install anomalyco/tap/opencode。如果 brew 本身没装，那就先用curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh | bash装 brew——这条命令的稳定性远高于 OpenCode 的安装脚本，因为 Homebrew 团队维护了专门的国内镜像分发逻辑。

2.2 Windows：Chocolatey 是 WSL 外最可靠的原生方案

Windows 用户常陷入两个误区：一是执着于用 PowerShell 直接运行 npm 安装，二是迷信 WSL。先说 npm：npm install -g opencode-ai在 Windows 上最大的雷，就是那个著名的npm : 无法加载文件 c:\program files\nodejs\npm.ps1报错。这不是 OpenCode 的问题，而是 Windows PowerShell 默认启用了Execution Policy（执行策略），禁止运行未签名的脚本。网上流传的“以管理员身份运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser”方案，看似解决了问题，实则埋下巨大隐患——它相当于给整个 PowerShell 环境开了后门，任何恶意 npm 包里的.ps1脚本都能被执行。我见过团队因此中招，一个伪装成eslint-config的包悄悄在后台启动了挖矿进程。再说 WSL：虽然官方文档写着“Windows（推荐使用 WSL）”，但这推荐是针对“需要完整 Linux 开发环境”的用户，比如要编译内核模块或跑 Docker Desktop。如果你只是想在终端里用 OpenCode 写 Python 脚本、改 Git 提交信息、生成 SQL 查询，WSL 就是杀鸡用牛刀——它要额外安装 Ubuntu 镜像、配置wsl.conf、处理 Windows 和 Linux 文件系统的路径映射（/mnt/c/Users/xxx），光是opencode启动时的延迟就比原生高 300ms。而 Chocolatey 的优势在于：它是 Windows 原生的包管理器，安装过程完全走 PowerShell，但所有操作都在 choco 自己的沙箱里完成，不会污染你的全局 Execution Policy。choco install opencode会自动下载预编译的 Windows 二进制（.exe），解压到C:\ProgramData\chocolatey\lib\opencode\tools\，并把这个路径加到系统级PATH，重启 CMD 或 PowerShell 就能直接用。最关键的是，choco 的国内源（如https://chocolatey.org/api/v2/）在国内访问稳定，下载速度基本能达到带宽上限。我们团队做过对比测试：在相同网络条件下，choco install opencode平均耗时 42 秒，npm install -g opencode-ai（配合 Execution Policy 修改）平均耗时 118 秒，且后者有 23% 的概率因网络抖动导致npm ERR! code ETIMEDOUT。所以，除非你明确需要 WSL 的 Linux 生态，否则 Windows 用户请闭眼选 Chocolatey。

2.3 Linux（含 WSL）：curl 脚本反而是最稳妥的选择

Linux 发行版碎片化严重，Ubuntu、CentOS、Arch、Debian 各自的包管理器（apt/yum/pacman）都不可能官方收录 OpenCode。Scoop 在 Linux 上根本不存在，Homebrew 虽然支持 Linux，但其生态远不如 macOS 成熟，很多 formula 维护滞后。这时候，官方提供的curl -fsSL https://opencode.ai/install | bash就成了最务实的选择。但注意，这里的“务实”不等于“无脑执行”。我要求团队成员在执行前，必须先做三件事：第一，用curl -I https://opencode.ai/install检查脚本 URL 是否可访问，HTTP 状态码必须是200 OK；第二，用curl -s https://opencode.ai/install | head -n 20查看脚本前 20 行，确认它没有硬编码https://github.com/.../releases/download/...这样的直连 GitHub 地址（官方脚本已优化为通过ghcr.io分发，但第三方镜像站可能未同步）；第三，把脚本下载到本地，用vim install.sh手动检查INSTALL_DIR变量，默认是/usr/local/bin，如果你的用户没有该目录写入权限，就必须提前sudo mkdir -p /usr/local/bin && sudo chown $USER:$USER /usr/local/bin。之所以推荐 Linux 用 curl，是因为它绕过了所有包管理器的依赖解析环节。apt 会试图安装libssl1.1、ca-certificates等一堆依赖，而这些依赖在不同发行版版本号不同，极易引发冲突；curl 脚本则直接下载静态链接的二进制，不碰系统库，装完就是个独立可执行文件。我们线上服务器（CentOS 7）部署时，curl方案一次成功率 98%，而强行用yum install nodejs再npm install -g opencode-ai的方案，失败率高达 41%，主要卡在node-gyp编译sqlite3原生模块上——这跟 OpenCode 本身毫无关系，纯粹是 npm 生态的兼容性灾难。

2.4 跨平台兜底方案：npm 全局安装的正确姿势

npm 安装 (npm install -g opencode-ai) 是唯一标榜“跨平台”的方案，但它也是最需要精细调控的。问题根源在于：npm 本身是个 JavaScript 工具，它依赖 Node.js 运行时，而 Node.js 的安装和环境配置，恰恰是全网搜索热词里占比最高的痛点（nodejs安装及环境配置、npm安装、npm切换淘宝最新镜像源）。所以，用 npm 装 OpenCode，本质是先解决 Node.js 的“地基”问题。我的标准流程是：第一步，用nvm（Node Version Manager）安装 Node.js，而不是直接下载.msi或.pkg。因为nvm能隔离不同项目的 Node 版本，避免nvm install 20.12.0 && nvm use 20.12.0后，全局npm命令指向错误的node_modules。第二步，nvm装完后，必须立即执行npm config set registry https://registry.npmmirror.com，把 npm 源切到淘宝镜像（现为 npmmirror），否则npm install -g opencode-ai会卡在fetchMetadata阶段，因为默认的https://registry.npmjs.org在国内 DNS 解析极慢。第三步，安装时加--force参数：npm install -g opencode-ai --force。别被npm warn using --force recommended protections disabled.的警告吓住——这个警告是 npm 5.x 之后加的“道德提醒”，实际不影响功能。加--force的真实目的是绕过peerDependencies检查。OpenCode 的 package.json 里声明了peerDependencies: {"node": ">=18.0.0"}，如果你用nvm切换的 Node 版本是20.12.0，npm 会认为满足，但某些旧版 npm（如 8.19.2）的 peerDep 检查逻辑有 bug，会误报UNMET PEER DEPENDENCY并终止安装。--force强制跳过此检查，实测 100% 安装成功。最后一步，也是最关键的一步：npm install -g安装的全局命令，默认放在~/.npm-global/bin/（macOS/Linux）或%AppData%\npm\（Windows），这个路径必须手动加到$PATH。很多人装完npm install -g opencode-ai，which opencode找不到，就是因为忘了这一步。在 macOS/Linux 上，执行echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc && source ~/.zshrc；在 Windows 上，用 PowerShell 运行[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\Users\$env:USERNAME\AppData\Roaming\npm", "User")。做完这四步，npm 方案才真正可靠。

3. 核心配置细节与实操要点：opencode.json和环境变量的生死线

装完opencode命令只是万里长征第一步。真正的“环境配置”核心，藏在两个地方：一个是~/.config/opencode/opencode.json配置文件，另一个是STEPFUN_API_KEY环境变量。90% 的用户卡在这两步，不是因为不会写 JSON 或不会设环境变量，而是因为没理解它们各自的职责边界和生效逻辑。我见过太多人把 API Key 直接写在opencode.json里，或者把provider.stepfun.api的 URL 写成https://api.stepfun.com/v1，结果调用时永远走付费接口，Step Plan 订阅额度一分不花。下面，我把每个字符、每个路径、每个参数的意义，掰开揉碎讲清楚。

3.1opencode.json：不是“配置文件”，而是“模型路由表”

首先，opencode.json的位置必须是~/.config/opencode/opencode.json（Linux/macOS）或%USERPROFILE%\.config\opencode\opencode.json（Windows）。注意，是.config，不是.opencode，也不是AppData\Roaming\opencode。这个路径是 OpenCode 源码里硬编码的（见src/config.rs的DEFAULT_CONFIG_PATH常量），改不了。创建它，不是为了“告诉 OpenCode 你的 API Key 是什么”，而是为了“告诉 OpenCode，当你要调用 StepFun 的模型时，应该把请求发到哪个 URL”。这是关键区别。OpenCode 内置了多个 Provider（StepFun、Claude、Hermes 等），每个 Provider 都有默认的 Base URL。对于 StepFun，它的默认值是https://api.stepfun.com/v1，这是一个通用的、按 token 付费的 API 端点。但 Step Plan 订阅用户，必须用专属端点https://api.stepfun.com/step_plan/v1，只有这个 URL 才会识别你的订阅状态，扣减你的月度额度。所以，opencode.json的核心作用，就是覆盖这个默认 URL。它的最小可行配置如下：

{ "$schema": "https://opencode.ai/config.json", "provider": { "stepfun": { "api": "https://api.stepfun.com/step_plan/v1" } } }

注意三点：第一，"$schema"字段不是可选的，它是 OpenCode 启动时校验 JSON 结构合法性的依据，漏掉会导致opencode启动失败并报invalid config schema；第二，"provider"对象下，必须是"stepfun"（小写，不能是StepFun或STEPFUN），这是 Provider 的注册名，大小写敏感；第三，"api"的值必须是完整的 URL 字符串，末尾不能带/，也不能少https://。我曾帮一个用户排查，他写的 URL 是https://api.stepfun.com/step_plan/v1/（多了一个斜杠），结果 OpenCode 内部拼接/chat/completions时变成了https://api.stepfun.com/step_plan/v1//chat/completions，HTTP 404。另外，"models"字段不是必须的。上面的配置里没写"models"，OpenCode 会自动从https://api.stepfun.com/step_plan/v1/models接口拉取当前可用的模型列表（如step-3.7-flash、step-3.5-flash）。只有当你想给某个模型起别名，或者屏蔽某个模型时，才需要显式定义"models"。例如，如果你想把step-3.7-flash显示为闪电快模，可以这样写：

"models": { "step-3.7-flash": { "name": "闪电快模" } }

但记住，"name"只影响/models命令显示的名称，不影响实际调用。调用时仍需用stepfun/step-3.7-flash这个 ID。

3.2STEPFUN_API_KEY：环境变量的“生效范围”陷阱

STEPFUN_API_KEY是 OpenCode 读取 Step API Key 的唯一官方渠道。它不接受opencode.json里写"apiKey"，也不接受opencode auth login（那是旧版 CLI 的交互式登录，新版已废弃）。它的设置看似简单：export STEPFUN_API_KEY="sk-xxx"。但“生效”二字，藏着巨大的坑。关键在于：环境变量只对当前 Shell 会话及其子进程有效。你在 iTerm 里执行export STEPFUN_API_KEY="sk-xxx"，然后运行opencode，没问题；但你关掉这个 iTerm 窗口，新开一个，echo $STEPFUN_API_KEY就是空的，opencode启动后也无法调用 Step 模型。所以，必须把它写入 Shell 的初始化文件。但写哪个文件，取决于你的 Shell 类型和系统。macOS Catalina 及以后默认用zsh，初始化文件是~/.zshrc；老系统或手动切换过 Shell 的，可能是~/.bash_profile或~/.bashrc。Windows PowerShell 的初始化文件是Microsoft.PowerShell_profile.ps1，位于$HOME\Documents\PowerShell\。很多人在这里栽跟头：在 macOS 上写了~/.bash_profile，但系统用的是 zsh，结果无效；在 Windows 上写了C:\Users\xxx\Documents\PowerShell\profile.ps1，但 PowerShell 的 Execution Policy 没开，导致 profile 文件被忽略。正确的做法是：先确认你的 Shell，再写对应文件。macOS 终端里执行echo $SHELL，如果是/bin/zsh，就写~/.zshrc；如果是/bin/bash，就写~/.bash_profile。写入命令必须是追加（>>），不能覆盖（>），否则会删掉你之前配置的PATH或其他变量。标准命令是：

# macOS/Linux (zsh) echo 'export STEPFUN_API_KEY="sk-xxx"' >> ~/.zshrc source ~/.zshrc # macOS/Linux (bash) echo 'export STEPFUN_API_KEY="sk-xxx"' >> ~/.bash_profile source ~/.bash_profile # Windows PowerShell Add-Content "$HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1" "`n`$env:STEPFUN_API_KEY='sk-xxx'"

提示：API Key 必须用双引号包裹，且不能有多余空格。echo 'export STEPFUN_API_KEY="sk-xxx"'中的单引号是为了防止 Shell 解析sk-xxx里的-为选项，双引号则是确保 Key 字符串原样写入文件。复制 Key 时，务必用鼠标拖选，不要用 Ctrl+A 全选，避免首尾混入不可见的 Unicode 字符（如零宽空格），这种字符会导致401 Incorrect API key错误，且肉眼完全无法察觉。

3.3 验证配置是否成功的“黄金三步法”

装完、配完，不代表就通了。必须用一套标准化的验证流程，逐层排除故障。我称之为“黄金三步法”，每一步失败，都对应一个明确的故障域：

第一步：验证命令是否存在且可执行

which opencode opencode --version

如果which opencode无输出，说明 PATH 没配对，回到安装步骤检查二进制路径是否加入$PATH；如果opencode --version报command not found，同上；如果报Permission denied，说明二进制文件没有执行权限，用chmod +x $(which opencode)修复。

第二步：验证环境变量是否加载

echo $STEPFUN_API_KEY

输出必须是你完整的 API Key 字符串（以sk-开头，长度约 48 位）。如果为空，说明环境变量没写对文件，或没source，或 Shell 类型判断错了。此时不要猜，直接cat ~/.zshrc | grep STEPFUN（macOS）或Get-Content $HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1 | Select-String STEPFUN（Windows）查看文件里是否有那行export。

第三步：验证配置文件语法和路径

opencode providers list

这个命令会列出 OpenCode 当前识别到的所有 Provider。如果输出里没有stepfun，说明opencode.json路径错、文件名错、JSON 格式错（比如多了一个逗号）、或provider.stepfun.api的 URL 格式错。此时，用cat ~/.config/opencode/opencode.json | python3 -m json.tool（macOS/Linux）或Get-Content %USERPROFILE%\.config\opencode\opencode.json | ConvertFrom-Json（Windows）来格式化并校验 JSON 语法。如果校验通过但providers list仍不显示stepfun，唯一的可能是opencode.json里provider对象下的键名写错了，比如写成了"StepFun"或"stepfun-api"。

只有这三步全部通过，才能进行最终的模型调用测试。任何一步失败，都不要急着输入/models，先解决底层问题。

4. 实操全流程与关键环节实现：从零开始，5分钟真实复现

现在，我们把前面所有理论，浓缩成一份可逐字照抄、100% 复现的实操清单。全程计时，从打开终端到看到print("Hello, world!")，严格控制在 5 分钟内。我用 macOS（M2 Max）实测，耗时 4 分 18 秒。每一步都标注了“为什么这么做”和“不做会怎样”，拒绝黑盒操作。

4.1 macOS 实操：Homebrew 全流程（2分30秒）

第 1 步（0:00-0:25）：检查并安装 Homebrew（如果未安装）

# 检查 brew 是否存在 which brew # 如果输出为空，执行安装（国内镜像加速） /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 安装完成后，brew 会自动添加到 PATH，但需要重启终端或执行： source ~/.zshrc

为什么必须用这个 URL？因为https://brew.sh/install.sh是官网地址，国内访问极慢；而raw.githubusercontent.com的镜像由 Homebrew 官方维护，且安装脚本内建了智能 DNS 切换逻辑，会自动选择最快的节点。如果跳过这步直接brew install，大概率遇到curl: (7) Failed to connect。

第 2 步（0:25-1:10）：添加 anomalyco tap 并安装 OpenCode

# 添加官方 tap（这是 OpenCode 的发布源） brew tap anomalyco/tap # 安装 opencode brew install anomalyco/tap/opencode # 验证安装 opencode --version # 输出应为类似：opencode 0.12.3

为什么先brew tap？因为anomalyco/tap是一个第三方 tap（类似软件源），brew install anomalyco/tap/opencode的意思是“从 anomalyco 这个 tap 里安装 opencode 包”。如果不先tap，brew 会报Error: No available formula or cask with the name "anomalyco/tap/opencode"。brew tap本身很快，因为它只下载一个很小的formula描述文件。

第 3 步（1:10-2:30）：创建配置文件并设置环境变量

# 创建配置目录 mkdir -p ~/.config/opencode # 创建 opencode.json cat > ~/.config/opencode/opencode.json << 'EOF' { "$schema": "https://opencode.ai/config.json", "provider": { "stepfun": { "api": "https://api.stepfun.com/step_plan/v1" } } } EOF # 获取你的 Step API Key（假设为 sk-abc123...） # 设置环境变量（追加到 .zshrc） echo 'export STEPFUN_API_KEY="sk-abc123..."' >> ~/.zshrc source ~/.zshrc # 验证环境变量 echo $STEPFUN_API_KEY # 应输出你的完整 Key

注意<< 'EOF'中的单引号，它告诉 Shell 不要解析$、\等特殊字符，确保 JSON 里的双引号和斜杠原样写入。如果漏了单引号，$schema会被当成变量展开，导致 JSON 语法错误。

4.2 Windows 实操：Chocolatey 全流程（3分10秒）

第 1 步（0:00-0:45）：以管理员身份安装 Chocolatey

# 以管理员身份打开 PowerShell # 执行安装命令（官方推荐，国内镜像已内置） Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

为什么用Bypass -Scope Process？这是最安全的策略：只对当前 PowerShell 进程临时禁用执行策略，安装完 choco 后，策略自动恢复，不会永久降低系统安全性。iex（Invoke-Expression）是 PowerShell 的标准执行方式，DownloadString从社区源下载安装脚本，该源在国内有 CDN 加速。

第 2 步（0:45-1:50）：安装 OpenCode 并验证

# 安装 opencode choco install opencode # 验证（可能需要重启 PowerShell） opencode --version # 输出应为：opencode 0.12.3

choco install会自动处理 PATH，所以装完就能用。如果opencode --version报错，唯一原因是 PowerShell 没重启，因为 choco 修改的是系统级 PATH，当前会话的$env:PATH缓存没刷新。

第 3 步（1:50-3:10）：配置环境变量和 JSON

# 创建配置目录 mkdir "$env:USERPROFILE\.config\opencode" -Force # 创建 opencode.json（用 PowerShell 原生命令，避免编码问题） $JsonContent = @{ '$schema' = 'https://opencode.ai/config.json' provider = @{ stepfun = @{ api = 'https://api.stepfun.com/step_plan/v1' } } } | ConvertTo-Json -Depth 10 $JsonContent | Out-File "$env:USERPROFILE\.config\opencode\opencode.json" -Encoding utf8 # 设置环境变量（用户级，永久生效） [Environment]::SetEnvironmentVariable("STEPFUN_API_KEY", "sk-abc123...", "User") # 重启 PowerShell，然后验证 echo $env:STEPFUN_API_KEY

PowerShell 的ConvertTo-Json会自动处理 UTF-8 编码和转义，比手动写字符串更可靠。-Depth 10确保嵌套对象（如provider.stepfun.api）能被完整序列化。[Environment]::SetEnvironmentVariable设置的是用户级变量，重启后依然存在，比在 profile.ps1 里写\$env:STEPFUN_API_KEY更彻底。

4.3 终极验证：启动 OpenCode 并完成 Hello World（30秒）

无论 macOS 还是 Windows，最后这一步完全一致：

# 启动 OpenCode TUI（文本用户界面） opencode # 进入后，按键盘 `/` 键，输入 models，回车 # 在弹出的模型列表中，用方向键选择 stepfun/step-3.7-flash，回车 # 此时终端底部应显示：> build · step-3.7-flash # 输入自然语言指令： Create a hello world script in Python # 等待 2-5 秒，模型会返回： print("Hello, world!")

这 30 秒里，opencode启动是最快的（<1 秒），/models加载列表约 2 秒（首次会缓存），选择模型瞬间完成，生成代码响应时间取决于网络，国内直连一般 3 秒内。如果卡在> build · ...不动，说明opencode.json的apiURL 错了，正在尝试连接https://api.stepfun.com/v1这个付费端点，而你的账号没开通付费，所以超时。此时立刻Ctrl+C退出，检查 JSON 文件。

5. 常见问题与排查技巧实录：那些没人告诉你的真实坑

在上百次远程协助和团队内部答疑中，我整理出一份“高频故障速查表”。这些问题，99% 的官方文档不会写，但 80% 的用户都会撞上。我把它们按发生频率排序，并给出“一招毙命”的排查口诀。

5.1 “401 Incorrect API key”：不是 Key 错了，是 Key 没“活”过来

这是最高频报错，但绝大多数人第一反应是“Key 复制错了”，然后疯狂重生成 Key、重复制。错！401的真实含义是：OpenCode 确实把请求发出去了，服务端也收到了，但服务端校验 Key 失败。失败原因，90% 是环境变量没生效，10% 是 Key 本身有问题。排查口诀：“三查一试”。

• 一查：echo $STEPFUN_API_KEY（macOS/Linux）或echo $env:STEPFUN_API_KEY（Windows PowerShell）。如果为空，环境变量根本没加载，回到配置步骤。
• 二查：opencode providers list。如果stepfun出现在列表里，说明opencode.json读取成功，问题一定在 Key；如果stepfun不在列表里，说明opencode.json没生效，Key 再对也没用。
• 三查：opencode --debug。加--debug参数启动，OpenCode 会输出详细日志，其中有一行Using API key: sk-***，如果这一行显示的是sk-***（星号），说明 Key 被截断了；如果显示null或空白，说明 Key 没读到。
• 一试：把 Key 临时写进opencode.json（仅用于测试！）：

  "provider": { "stepfun": { "api": "https://api.stepfun.com/step_plan/v1", "options": { "apiKey": "sk-abc123..." } } }

  如果这样能成功，100% 确认是环境变量问题；如果还是 401，则 Key 本身有误（比如复制时多了空格，或用了旧版 Key）。

实操心得：我教团队成员一个“防呆”技巧——在设置环境变量时，用echo 'export STEPFUN_API_KEY="sk-'"$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 48 | head -n 1)"'"'生成一个随机字符串，先测试echo $STEPFUN_API_KEY是否能输出这个随机串。如果能，说明环境变量链路通；再换成真实的 Key。这招能瞬间区分是“环境变量问题”还是“Key 问题”。

5.2 “400 you have no active step plan subscription”：订阅没“绑定”到 Key

这个报错意味着：你的 Key 是对的，opencode.json的 URL 也是对的，但服务端查不到你的订阅记录。根本原因只有一个：你创建 API Key 时，用的不是订阅 Step Plan 的那个账号。StepFun 平台要求，API Key 必须由已订阅 Step Plan 的账号创建，且 Key 的权限范围必须包含step_plan。排查口诀：“一登二查三换”。

• 一登：打开 StepFun 控制台（https://stepfun.com/console），确认你登录的邮箱，就是购买 Step Plan 时用的邮箱。如果公司用 SSO 登录，必须确保 SSO 账号已关联 Step Plan。
• 二查：在控制台的API Keys页面，找到你正在用的 Key，点击右侧Edit，查看Scopes（权限范围）。必须勾选step_plan。如果没勾选，编辑它，勾上，保存。
• 三换：如果Scopes已勾选，但还是报错，立刻删除这个 Key，重新创建一个全新的 Key，并