OpenCode 完整使用教程：安装、配置本地模型、卡顿排查与任务恢复

OpenCode 完整使用教程：安装、配置本地模型、卡顿排查与任务恢复

面向普通开发者的实战指南：从安装 OpenCode，到接入本地模型，再到解决执行过程中卡住、异常退出、任务恢复等常见问题。

一、什么是 OpenCode？

OpenCode 官方网站https://opencode.ai
OpenCode 官方文档https://opencode.ai/docs
OpenCode GitHubhttps://github.com/sst/opencode

OpenCode 是一款运行在终端中的 AI 编码助手。

它的核心特点包括：

支持本地大模型（LM Studio、Ollama 等）
支持云端模型（OpenAI、Anthropic 等）
自动分析项目结构
自动读写文件
自动执行 Shell 命令
自动生成代码、文档和测试
支持多轮上下文协作

如果你使用过：

Claude Code
OpenAI Codex CLI
OpenClaw

那么可以把 OpenCode 理解为一个轻量、现代、专注于代码工作的终端 AI Agent。

二、OpenCode 的工作原理

OpenCode 并不是简单地“把问题发给模型”。

它的执行流程通常如下：

用户提出任务
      ↓
扫描项目文件
      ↓
构建上下文
      ↓
调用模型制定计划
      ↓
执行命令（npm、git、mvn 等）
      ↓
修改文件
      ↓
再次调用模型
      ↓
完成任务

也就是说，模型只是其中一个环节。

很多时候界面显示“正在执行”，但实际上 OpenCode 正在运行本地命令，而不是调用大模型。

三、安装 OpenCode

1. 安装 Node.js

urlNode.js 官方网站https://nodejs.org

建议安装：

Node.js 20+

2. 全局安装

npm install -g opencode-ai

3. 验证安装

opencode --version

如果输出版本号，说明安装成功。

四、项目目录结构

推荐在项目根目录中准备以下文件：

my-project/
├── opencode.json   # OpenCode 配置
├── SOUL.md         # 项目级系统提示词
├── .gitignore
└── src/

五、配置本地模型（局域网 IP）

如果你的模型服务已经部署在局域网中，例如：

http://192.168.10.86:1234/v1

则可以在项目根目录创建 opencode.json。

最简配置示例

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Local Model",
      "options": {
        "baseURL": "http://192.168.10.86:1234/v1",
        "apiKey": "dummy"
      },
      "models": {
        "google/gemma-3-27b-it": {
          "name": "Gemma 3 27B",
          "limit": {
            "context": 128000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "local/google/gemma-3-27b-it"
}

六、配置项详解

provider

定义模型提供者。

"provider": {
  "local": { ... }
}

这里的 local 是你自定义的名称。

npm

指定兼容 OpenAI API 的 SDK。

"npm": "@ai-sdk/openai-compatible"

baseURL

模型 API 地址。

"baseURL": "http://192.168.10.86:1234/v1"

apiKey

即使本地模型不验证，也需要提供一个值。

"apiKey": "dummy"

models

定义可用模型。

limit.context

上下文窗口大小。

limit.output

最大输出 token 数。

model

默认使用的模型。

"model": "local/google/gemma-3-27b-it"

七、获取正确的模型名称

在浏览器中打开：

http://192.168.10.86:1234/v1/models

{
  "data": [
    {
      "id": "google/gemma-3-27b-it"
    }
  ]
}

其中的 id 就是模型名称。

八、启动 OpenCode

cd my-project
opencode

九、常用命令

查看帮助

/help

查看模型

/models

切换模型

/model local/google/gemma-3-27b-it

退出

/exit

十、SOUL.md：项目级提示词

在项目根目录创建：

SOUL.md

示例：

你是一位资深 Java 架构师。

要求：
- 使用 Spring Boot 3
- 使用 MyBatis
- 所有注释使用中文
- 优先考虑可维护性
- 修改代码前先分析整体架构

OpenCode 启动时会自动加载。

十一、基础使用示例

分析项目

请分析当前项目架构，并给出优化建议。

修复 Bug

找出登录失败的原因并修复。

生成代码

创建用户管理 REST API。

生成测试

为 UserService 编写 JUnit 5 测试。

编写文档

生成完整 README.md。

十二、推荐的高质量提示词

请先分析项目结构，列出执行计划，逐步完成任务，并在每一步说明原因。

这个提示词可以显著提高结果质量和稳定性。

十三、OpenCode 卡在 14% 是什么原因？

很多用户会遇到这种情况：

OpenCode 显示 14% Executing
LM Studio 没有任何请求
CPU 占用很低
长时间无响应

这通常说明：

OpenCode 正在执行本地工具步骤，而尚未调用模型。

十四、执行流程示意图

任务开始
   ↓
创建目录
   ↓
安装依赖（npm install）  ← 最常卡住
   ↓
扫描文件
   ↓
调用模型
   ↓
生成代码

如果卡在前面步骤，模型不会被调用。

十五、最常见卡顿原因

1. npm install 或 pnpm install 阻塞

最常见原因。

可能是：

下载依赖过慢
网络问题
等待输入
镜像源异常

2. 等待权限确认

OpenCode 在执行命令或写文件前可能等待批准。

3. 文件数量过多

例如：

node_modules
.git
dist
build

4. Windows Defender 实时扫描

大量文件操作会导致明显变慢。

5. 模型尚未准备好

虽然通常会显示请求，但部分情况下加载模型也会造成延迟。

十六、如何排查卡顿

开启调试模式

opencode --debug

你可以看到：

正在执行的命令
是否等待批准
是否调用模型
错误信息

手动测试命令

git status
npm install
pnpm install

检查模型接口

curl http://192.168.10.86:1234/v1/models

十七、为什么 OpenCode 会自动关闭？

可能原因：

Shell 命令失败
模型请求超时
Node.js 崩溃
内存不足
未捕获异常

十八、自动关闭后为什么任务消失？

OpenCode 的会话主要保存在内存中。

当进程退出时：

内存中的上下文丢失
已生成的文件仍然保留

重新启动时会创建新会话。

十九、如何恢复任务

进入项目目录：

cd your-project
opencode

然后输入：

请扫描当前目录，确认哪些部分已经完成，并继续完成未完成的工作。

二十、推荐恢复提示词

请分析当前项目状态，判断哪些内容已经完成，哪些尚未完成，并从中断处继续。

二十一、检查是否已生成部分文件

git status

或者：

dir

通常会发现：

项目目录已创建
部分文件已生成
依赖尚未安装完成

二十二、避免任务丢失的最佳实践

1. 初始化 Git

git init
git add .
git commit -m "initial state"

2. 分阶段执行

不要一次性要求：

创建项目
安装依赖
编写全部代码
执行测试

建议拆成多个步骤。

3. 使用调试模式

opencode --debug

4. 手动安装依赖

npm install

二十三、最稳定的工作流

第一步：手动创建项目

npm create vite@latest myapp
cd myapp
npm install

第二步：初始化 Git

git init
git add .
git commit -m "base project"

第三步：启动 OpenCode

opencode

第四步：逐步下达任务

先分析项目，然后实现用户管理功能。

二十四、适合 Java 开发者的使用方式

作为 Java 程序员，可以让 OpenCode 处理以下工作：

Spring Boot 接口开发
MyBatis Mapper 编写
SQL 优化
单元测试
架构分析
技术文档生成

二十五、推荐任务模板

创建 REST API

使用 Spring Boot 3 和 MyBatis 实现用户管理模块。

优化 SQL

分析这些 SQL 并给出索引优化建议。

生成博客

根据项目内容生成一篇技术博客。

二十六、性能优化建议

在子目录运行

cd backend
opencode

避免扫描整个仓库。

配置 .gitignore

node_modules
dist
build
.next
coverage
*.log

Windows Defender 排除

建议将以下目录加入排除：

二十七、常见问题汇总

Q1：启动后提示找不到模型

原因：模型 ID 配置错误。

解决：访问 /v1/models 获取正确的 id。

Q2：显示执行中但模型没有调用

原因：OpenCode 正在执行本地命令。

Q3：程序自动退出

原因：命令失败、超时或异常。

Q4：重新打开任务不见了

原因：会话保存在内存中，进程退出后丢失。

二十八、与其他工具对比

工具	特点	适用人群
OpenCode	轻量、终端优先	普通开发者
Claude Code	工具能力强	高级开发者
Codex CLI	官方生态	OpenAI 用户
OpenClaw	自动化程度高	高级玩家

二十九、推荐的生产实践

建议按照以下流程使用：

1. 手动创建项目
2. 手动安装依赖
3. 初始化 Git
4. 编写 SOUL.md
5. 启动 OpenCode
6. 分步骤完成任务
7. 每个阶段提交 Git

三十、我的实际建议

如果你的主要工作是：

Java 后端开发
技术博客写作
自动生成测试
项目重构

那么 OpenCode 是一个非常高效的终端 AI 工具。

尤其适合与本地模型结合使用：

数据不离开本地
成本几乎为零
可长期稳定使用

三十一、最推荐的提示词模板

请先分析整个项目结构，列出详细计划，逐步完成任务。
在每一步执行前说明原因，执行后总结结果。
如果遇到错误，请自行排查并继续。

三十二、总结

OpenCode 的本质并不是“聊天机器人”，而是一个能够：

理解代码
制定计划
执行命令
修改文件
自动恢复上下文

的终端 AI Agent。

理解以下三个关键点后，使用体验会非常稳定：

执行中不一定是在调用模型
自动关闭后文件仍然存在
重新扫描项目即可继续任务

三十三、最简工作流程

# 安装
npm install -g opencode-ai

# 进入项目
cd my-project

# 启动
opencode --debug