一、OpenCode 到底是什么？#

可以把 OpenCode 理解成一个“AI 程序员外壳”。

它本身负责：

• 读取项目目录

• 搜索代码

• 编辑文件

• 执行终端命令

• 调用工具

• 管理 Agent 工作流

真正负责“思考”的模型可以来自不同地方，例如：

• OpenCode 官方模型

• OpenAI

• Anthropic

• Gemini

• GLM

• OpenRouter

• Ollama 本地模型

所以 OpenCode 和模型是分开的。

一个比较典型的组合是：

1
VS Code
2

3
└── OpenCode
4

5
    ├── 云端模型
6

7
    └── Ollama 本地模型

二、需要专门安装 WezTerm、Ghostty 等终端吗？#

OpenCode 官方建议使用现代终端，例如：

• WezTerm

• Alacritty

• Ghostty

• Kitty

但这并不代表必须额外安装这些终端。

如果平时已经使用 VS Code，完全可以先使用：

1
VS Code + Integrated Terminal + OpenCode

这样做对刚开始 Vibe Coding 的人反而更直观。

VS Code 左侧可以看到：

• 项目目录

• .env

• .gitignore

• .vscode

• 配置文件

• OpenCode 新建或修改的代码

下面的 Terminal 则用于运行 OpenCode。

打开 VS Code 内置终端的快捷键通常为：

1
Control + `

如果后续长期大量使用终端，再考虑 Ghostty、WezTerm 等独立终端即可。

三、使用 npm 安装 OpenCode#

如果 Codex、Claude Code 等 CLI 本身就是通过 npm 安装的，那么 OpenCode 继续使用 npm 管理会比较统一。

先确认 Node.js 和 npm：

1
node -v
2

3
npm -v

例如：

1
v24.14.1
2

3
11.17.0

查看已经安装的全局 npm 包：

1
npm list -g --depth=0

如果使用 nvm，路径可能类似：

1
~/.nvm/versions/node/v24.14.1/lib

安装 OpenCode：

1
npm install -g opencode-ai

也可以简写：

1
npm i -g opencode-ai

检查版本：

1
opencode --version

如果能够输出版本号，说明 CLI 已经安装成功。

1
-g

1
npm install opencode-ai

四、npm 11 的 allow-scripts 警告#

新版 npm 可能在安装时提示：

1
npm warn allow-scripts
2

3
opencode-ai@... (postinstall: node ./postinstall.mjs)

这表示 npm 检测到了包的 postinstall 安装脚本，并提醒当前安全策略没有显式批准该脚本。

这里首先检查：

1
opencode --version

再尝试：

1
opencode

如果 CLI 可以正常运行，就不必仅仅为了消除 warning 修改长期 npm 配置。

如果确实因为安装脚本未执行导致 OpenCode 无法正常使用，可以按照 npm 给出的提示，仅针对 OpenCode 允许脚本，例如：

1
npm install -g --allow-scripts=opencode-ai opencode-ai

不建议为了省事直接开放所有包的安装脚本。

五、nvm 用户要注意 Node 版本切换#

如果 OpenCode、Codex、Claude Code 都安装在某个 nvm Node 版本下面，例如：

1
~/.nvm/versions/node/v24.14.1/

以后切换 Node：

1
nvm use 26

可能会发现：

1
opencode: command not found

原因通常不是 OpenCode 被删除，而是新的 Node 版本拥有另一套 global npm packages。

因此：

• 当前环境稳定时没有必要频繁切 Node

• 升级 Node 后可以重新安装需要的全局 CLI

• 遇到 CLI 突然消失时先检查：

1
which node
2

3
which npm
4

5
which opencode
6

7
node -v

六、启动 OpenCode#

进入项目目录：

1
**cd** ~/Projects/my-app

启动：

1
opencode

如果只是测试，也可以先建一个空项目：

1
mkdir ~/Documents/opencode-**test**
2

3
**cd** ~/Documents/opencode-**test**
4

5
opencode

七、常用基础命令#

查看版本：

1
opencode --version

查看模型：

1
opencode models

进入 OpenCode 后连接云端模型 Provider：

1
/connect

选择模型：

1
/models

直接指定模型运行：

1
opencode -m provider/model

非交互运行一次任务：

1
opencode run -m provider/model "你的任务"

打印日志排错：

1
opencode --print-logs

八、如何用 OpenCode 做第一个小软件#

进入一个空目录：

1
mkdir my-first-app
2

3
**cd** my-first-app
4

5
opencode

然后不要只说：

1
做一个记账软件

更推荐描述清楚功能和限制：

1
我要做一个本地运行的简单记账软件。
2

3

4

5
功能：
6

7
1. 添加收入和支出
8

9
2. 可以填写金额、类别、备注和日期
10

11
3. 首页显示本月收入、支出和余额
12

13
4. 可以删除记录
14

15
5. 数据保存在本地
16

17
6. 界面简单清爽
18

19

20

21
我是新手，不需要复杂架构。
22

23
请选择容易运行和维护的技术栈。
24

25
先查看当前目录并给出计划，确认方案后再开始创建。

对于稍大的修改，可以先要求：

1
先不要修改代码。
2

3
先查看当前项目结构，然后告诉我你的实现计划。

确认没问题之后：

1
按照这个方案执行。

这样可以降低 Agent 大范围误改代码的概率。

九、OpenCode 接入 Ollama：不改配置文件的方式#

如果已经安装 Ollama，最省事的方式不是手写 opencode.json，而是让 Ollama 启动 OpenCode。

直接运行：

1
ollama launch opencode

指定模型：

1
ollama launch opencode --model qwen3.6

只生成/准备配置但不启动：

1
ollama launch opencode --config

Ollama 官方说明，ollama launch opencode 会通过：

1
OPENCODE_CONFIG_CONTENT

把配置以内联环境变量的方式传递给 OpenCode，因此不需要为了试用本地模型手工编辑全局配置文件。

这特别适合：

• 想快速测试本地模型

• 不想污染 OpenCode 配置

• 想随时换 Ollama 模型

十、为什么 opencode models ollama 可能提示 Provider not found？#

可能出现：

1
Error: Provider not found: ollama

这不代表 Ollama 坏了。

OpenCode 的 provider 是否已经存在，取决于当前版本、配置方式和启动方式。

如果直接运行：

1
opencode

而没有配置 Ollama provider，那么：

1
opencode models ollama

可能找不到 ollama。

这时最简单的处理方式是：

1
ollama launch opencode --model qwen3.6

如果希望 OpenCode 永久把 Ollama 当作一个自定义 provider，也可以在 opencode.json 中配置 OpenAI-compatible endpoint，但对于新手测试并不是必须的。

十一、手动配置 Ollama Provider（可选）#

如果希望直接运行：

1
opencode

后也能长期看到 Ollama provider，可以配置：

1
~/.config/opencode/opencode.json

示例：

1
{
2

3
  "$schema": "https://opencode.ai/config.json",
4

5
  "provider": {
6

7
    "ollama": {
8

9
      "npm": "@ai-sdk/openai-compatible",
10

11
      "name": "Ollama (local)",
12

13
      "options": {
14

15
        "baseURL": "http://localhost:11434/v1"
16

17
      },
18

19
      "models": {
20

21
        "qwen3.6:latest": {
22

23
          "name": "Qwen 3.6 Local"
24

25
        }
26

27
      }
28

29
    }
30

31
  }
32

33
}

配置后模型名称通常为：

1
ollama/qwen3.6:latest

十二、本地模型也可以联网搜索#

“模型在本地运行”和“OpenCode 能联网”并不冲突。

架构可以是：

1
OpenCode
2

3
├── Ollama / Qwen3.6    ← 本地推理
4

5
├── webfetch             ← 读取网页
6

7
└── websearch            ← 搜索互联网

1
阅读 React 最新官方文档，然后按照当前推荐方案修改项目。

1
OPENCODE_ENABLE_EXA=1 opencode

1
OPENCODE_ENABLE_EXA=1 ollama launch opencode --model qwen3.6

1
本地模型负责推理
2

3
+
4

5
OpenCode 联网搜索最新资料
6

7
+
8

9
OpenCode 修改本地代码

1
本地推理 ≠ 完全离线

十三、推荐的日常使用方式#

对于刚开始使用 OpenCode 的用户，我比较推荐：

1
VS Code
2

3
│
4

5
├── Explorer：查看项目和隐藏文件
6

7
├── Git：查看 diff
8

9
└── Terminal
10

11
    └── OpenCode
12

13
        ├── 免费模型
14

15
        ├── 云端模型
16

17
        └── Ollama 本地模型

平时直接：

1
opencode

需要本地模型时：

1
ollama launch opencode --model qwen3.6

需要本地模型同时联网：

1
OPENCODE_ENABLE_EXA=1 ollama launch opencode --model qwen3.6

这套方式的好处是配置简单，而且本地/云端可以随时切换。

十四、常见排错#

1
which opencode
2

3
npm list -g --depth=0
4

5
node -v
6

7
npm -v

1
opencode --print-logs

1
curl http://127.0.0.1:11434/api/tags

1
ollama launch opencode --model 模型名

十五、参考资料#

• OpenCode 官方文档：https://opencode.ai/docs/

• OpenCode Provider 文档：https://opencode.ai/docs/providers/

• OpenCode Tools 文档：https://opencode.ai/docs/tools/

• Ollama × OpenCode 集成：https://docs.ollama.com/integrations/opencode

• Ollama：https://ollama.com/

总结#

如果本身已经习惯 VS Code、npm 和终端，那么 OpenCode 的门槛其实很低：

1
npm install -g opencode-ai
2

3
opencode

本地模型则可以进一步简化为：

1
ollama launch opencode --model qwen3.6

需要联网搜索时：

1
OPENCODE_ENABLE_EXA=1 ollama launch opencode --model qwen3.6

这套工作流最大的优势是：编辑器、Agent 和模型彼此独立。可以先用免费模型、本地模型做小软件，真正遇到复杂任务时再切换更强的云端模型，不必一开始就承担固定订阅成本。