【2】. OpenCode 快速上手

目录

1. 虚拟机的配置教程

2. 安装Node.js

2.1 Ubuntu24.04

2.2 Windows11

3. 安装 OpenCode

4. OpenCode 基础命令

启动 OpenCode

退出 OpeCode

配置 OpenCode 主题

命令面板

其余指令

5. 内置 Agent

6. 给 OpenCode 配置模型 LLM

1. 进入配置模型界面：

2. 搜索模型：

3. 给定 API Key

4. 切换模型

7. 理解 LLM 的记忆

虽然OpenCode 官网提供了Linux的一键安装脚本，但是实测在国内网络环境下并不顺利。因此我们使用npm的方式安装。

1. 虚拟机的配置教程

参考：

最新VMware安装Ubuntu虚拟机教程，图文详细，附所需资源分享链接_onepanel-CSDN博客

2. 安装Node.js

2.1 Ubuntu24.04

首先需要安装Node.js

Node.js 是啥？

大家肯定都听说过JavaScript，也知道JavaScript是运行在浏览器上的语言。

浏览器中用来解释运行JavaScript的模块被称为 "JavaScript引擎" ，其中最知名的就是Chrome 中的引擎 V8 Worker。

后来，有大佬把 V8 Worker 单独拎出来，封装了一下，赋予其更多的能力（比如可以调用系统API），此时就得到了 Node.js。

Node.js 使 JavaScript 的应用场景更广泛了，不仅仅可以进行Web前端开发，还能进行后端开发和桌面应用开发。

目前我们使用的 AI CLI 系列的开发工具，大部分都是使用 Node.js 开发的。

在 Node.js 官网 Node.js — 下载 Node.js® 提供了下载安装的方案。

apt install nodejs

对于 Ubuntu24.04 来说，apt 默认源中的 Node.js 版本较低，通常不满足 AI 开发工具的需求。因此我们需要额外安装源，使 apt 可以安装高版本的 Node.js，此处是 v24 版本。

1. 使用 root 用户，引入 Node.js 的 apt 源：

curl -sL https://deb.nodesource.com/setup_24.x | bash -

2. 安装 Node.js

apt install nodejs

但对于国内的网络环境来说，上述操作有一定概率失败，解决方法：直接从国内镜像源下载 Node.js 的压缩包

sudo wget https://registry.npmmirror.com/-/binary/node/v24.3.0/node-v24.3.0-linux-x64.tar.xz

解压：

sudo tar -xJf node-v24.3.0-linux-x64.tar.xz -C /usr/local/lib/

创建软链接：

sudo ln -s /usr/local/lib/node-v24.3.0-linux-x64/bin/node /usr/local/bin/node sudo ln -s /usr/local/lib/node-v24.3.0-linux-x64/bin/npm /usr/local/bin/npm sudo ln -s /usr/local/lib/node-v24.3.0-linux-x64/bin/npx /usr/local/bin/npx

如果安装完成后 node -v 仍输出旧版：

根因：bash 会缓存命令路径，之前执行 node 时缓存了旧版 /usr/bin/node 的路径，即使软链接已指向新版，bash 仍使用缓存的旧路径。hash -r 清除缓存后问题解决。

最终结果：

成功之后我们会获得 node 和 npm 两个命令：

什么是 npm？
npm 是 Node.js 内置的 "包管理工具"，类似于 Ubuntu 的 apt，只不过 npm下载的软件包是给 Node.js 使用的，而 apt 下载的软件包则是给 Ubuntu 系统使用的。

PS C:\Users\75060> node Welcome to Node.js v24.18.0. Type ".help" for more information. > (To exit, press Ctrl+C again or Ctrl+D or type .exit) > PS C:\Users\75060> npm npm <command> Usage: npm install install all the dependencies in your project npm install <foo> add the <foo> dependency to your project npm test run this project's tests npm run <foo> run the script named <foo> npm <command> -h quick help on <command> npm -l display usage info for all commands npm help <term> search for help on <term> (in a browser) npm help npm more involved overview (in a browser)

2.2 Windows11

Windows 上 Node.js 的安装就简单多了。直接在官网，然后双击安装包，一路 Next 即可。

3. 安装 OpenCode

在OpenCode 官网中，选择"npm"安装方式。
OpenCode | 开源 AI 编程代理

使用 root 用户执行以下命令：

npm i -g opencode-ai

由于OpenCode 是一个Node.js 上的应用程序，而Node.js 本身是跨平台的，因此无论是Windows还是Linux，OpenCode 的安装都是上面相同的命令。

4. OpenCode 基础命令

启动 OpenCode

在工作目录中执行：

• opencode

在哪个目录中运行 opencode，哪个目录就是工作目录，opencode 默认只能针对工作目录内部的内容（包括子目录）进行操作，所以先提前创建好指定的项目目录，并进入到该目录中，再启动opencode

如果发现只有 root 用户能启动 opencode，是因为 opencode 在 root 的家目录下，其它用户看不到，没有权限，解决方法：

root@iZuf6dza8bf7vp0zjipnhmZ:~# which opencode /root/nodejs/bin/opencode root@iZuf6dza8bf7vp0zjipnhmZ:~# cp /root/nodejs/bin/opencode /usr/local/bin/

退出 OpeCode

• ctrl + c 执行两次
• ctrl + d

配置 OpenCode 主题

• /theme

命令面板

• ctrl + p

OpenCode 的各种设置项均包含在命令面板中，这里的内容我们暂时不展开

其余指令

可去 OpenCode 官网查看：TUI | OpenCode

5. 内置 Agent

什么是 Agent

Agent 中文名叫做“智能体”，是当前 AI 应用开发领域中比较核心的概念。

我们知道，AI 开发工具的核心驱动力是 LLM，人和 LLM 之间的交互，核心就是通过“提示词”。所谓的 Agent，其实就是一些事先准备好的提示词（系统提示词），这些提示词中描述了该 LLM “人设”、“核心功能”、“约束”等内容。用户后续通过 Agent 来和 LLM 交互的时候，这些系统提示词都会自动生效，使 LLM 按照预定的规则进行工作。

举个例子类比：
对于一个普通人，见到“着火了”，第一时间想到的是自身的安全，要先撤离到安全地方。对于消防员来说，见到“着火了”，第一时间考虑的则是如何保护人民群众的人身财产安全。

因为在消防员的“系统提示词”中，保护人民群众是高于自身的人身安全的。

在 OpenCode 中，内置了 4 种 Agents：

• Plan：只回答问题，不修改代码。通常用来提问/进行方案设计/做规划
• Build：能回答问题，也能修改代码。开发代码的主力 Agent
• general：独立的子 Agent，有单独的上下文窗口。通常用来处理一些单独的子问题。
• explore：用来解释当前已有的项目代码。通常用来帮助我们理解一个已经存在的项目。

OpenCode 也支持自定义 Agent。我们暂时还用不到，先不考虑。其中，Plan 和 Build 是我们最常使用的 Agent。通过 Tab 键切换。

另外的 general 和 explore，则可以在对话中通过 @ 的方式来使用。

通过 ! 也可以进入 Shell 模式，即可以执行终端命令

6. 给 OpenCode 配置模型 LLM

1. 进入配置模型界面：

• /models

2. 搜索模型：

按 Ctrl + A，可以查看所有的模型供应商（供应商）
也可以搜索指定模型，比如你买的是 MinMax 的 Coding Plan，在搜索框中输入“mini”进行搜索，选择 MiniMax Coding Plan（minimaxi.com）

如果买的是 token，选择上面的 MiniMax（minimaxi.com）

minimaxi.io 是提供给海外用户的。

3. 给定 API Key

复制刚才在 Minimax 后台获取到的 API Key，粘贴到输入框中， 按 Enter 确认：

什么是 API Key
顾名思义，API Key 就是调用 API 的“钥匙”。

LLM 厂商其实是提供了一组 HTTP API，Open Code 则作为客户端，调用上述 API 完成后续任务。这些 LLM 的 API 不是随便就能调用的，得“花钱”。

那么如何识别出，当前的请求是否花钱了呢？LLM 厂商就会在用户付费之后，给用户分配这么一把钥匙。我们需要把 API Key 配置到 OpenCode 中，此时 OpenCode 发送的 HTTP 请求，就会带上这个 API Key，从而使模型厂商完成“身份校验”。

因此，这个 API Key 千万不能泄露出去，如果别人拿到了 API Key，就可以使用你账户里的额度了（相当于你的账户被白嫖了）

4. 切换模型

再次使用 /models 选择模型，选择 MiniMax Coding Plan 中的 MiniMax-M2.7 即可，如果版本升级了，选新版就行了。

7. 理解 LLM 的记忆

通过上述的简单任务，我们感受到了：使用 AI 工具进行开发，通常需要“多轮对话”才能够完成任务。这时候我们发现，当我们进行后续对话的时候，LLM 是能记得前面的对话内容的。举个例子：

• 上述过程中，当我表述“发现问题，程序一启动立即提示 GameOver”，此时 LLM 记得这是在开发一个“贪吃蛇”游戏。当我表述“刚才的问题仍然存在”时，LLM 能够知道“刚才的问题”是指“立即提示 GameOver”的问题。
• LLM 是如何记住这些内容的呢？其实，LLM 自身是没有记忆的。LLM 能够记住前面信息的关键，是 opencode 等开发工具，维护了一份“上下文”。简单来说，就是把前面已经产生的对话，重新发送给 LLM。

显而易见，随着对话轮次的增加，给 LLM 单次发送的内容就会越来越多（每次都会携带当前会话中的所有历史消息）。其中：

• 请求中的开头部分是“系统提示词”，会在每次发送的请求的最上面，作为 LLM 的基本规则。
• 标记了“用户说”的部分，称为“用户提示词”，也就是每轮对话用户输入的内容。
• 标记了“LLM 说”的部分，称为“AI 提示词”，也就是每轮对话 LLM 返回的内容。

这个内容不能无限增长。这个上限称为 LLM 的“上下文窗口大小”。
目前，主流的 LLM 上下文窗口能够达到 1MB（100 万个 ASCII 字符，几十万个汉字）
在 OpenCode 右侧面板，提示了当前上下文窗口的使用量

当上下文过长时，即使没有达到窗口上限，LLM 也容易出现“注意力不集中”的现象，导致出现更大概率“答非所问”。因此，开发时，我们需要控制上下文的大小，使 LLM 能够聚焦于当前任务。

• 使用 SPEC.md 保存项目中的关键信息，OpenCode 会把这部分作为系统提示词，相当于持久记忆
• 使用 /compact 或 /summarize 压缩上下文
• 使用 /new 创建新的会话，针对不同的功能点，使用不同的 session 来进行开发