OpenCode 完整入门（安装 + 配置 + 使用 + 模板）

一、核心定位与优势

• 开源协议：MIT，完全免费可商用
• 三端支持：终端 TUI、桌面 App、VS Code 扩展
• 模型兼容：75 + 大模型（含 OpenCode Zen 免费模型：GLM-4.7、MiniMax 等）
• 隐私优先：代码 / 上下文仅内存存储，进程退出即清除
• 终端原生：TUI 交互，Vim 快捷键，低资源占用
• 智能代理：内置 Plan/Code/Debug/Orchestrator 等 Agent，支持多代理协作

二、安装（3 种方式，推荐 npm）

1. 全局 npm 安装（最通用）

# 安装（需Node.js）
npm install -g opencode-ai

# 验证安装
opencode --version

2. 官方脚本（Mac/Linux）

curl -fsSL https://opencode.ai/install.sh | sh

3. VS Code 扩展

• 打开扩展市场 → 搜索 OpenCode AI → 安装
• 或在终端运行 opencode，自动触发 IDE 扩展安装

三、首次配置（必做）

1. 初始化项目（进入项目目录执行）

cd your-project
opencode
# 首次启动自动初始化，生成 AGENTS.md（项目规范文件）

2. 连接 AI 模型（2 种方式）

方式 1：使用 OpenCode Zen（免费，推荐新手）

# 进入TUI后输入
/connect zen
# 自动接入免费模型（GLM-4.7等），无需API Key

方式 2：接入自定义模型（Claude/GPT 等）

# 1. 生成配置文件
opencode config init

# 2. 编辑配置（~/.config/opencode/opencode.json）
{
  "llm": {
    "provider": "anthropic",
    "apiKey": "sk-ant-xxx",
    "model": "claude-3-7-sonnet-20250219"
  }
}

# 3. 生效配置
opencode config reload

3. 常用命令（TUI 内直接输入）

• /new：新建会话
• /session：切换会话
• /connect：切换模型
• /init：重新初始化项目
• /build：AI 直接修改代码文件
• /plan：生成项目规划
• /debug：调试模式
• /exit：退出

四、基础使用（高频场景）

1. 代码生成（Code 模式）

# TUI内直接输入需求
写一个Python快速排序函数，带注释、测试用例、异常处理

2. 项目架构（Plan 模式）

# 输入
设计Vue3+Node.js全栈Todo应用：技术栈、目录结构、接口文档、数据库表

3. 调试排错（Debug 模式）

# 粘贴报错+代码
帮我分析这个Python报错：IndexError: list index out of range，修复并解释原因

4. 批量修改（Build 模式）

# 输入
把项目中所有console.log替换为logger.info，仅修改src目录下.js文件

5. 代码解释

详细解释这段代码的执行流程、关键逻辑、优化点

五、复制即用提示词模板

1. 代码生成模板

用{语言}实现{功能}：
1. 可运行、无bug
2. 清晰注释
3. 测试用例
4. 直接写入{文件名}

2. 重构优化模板

重构并优化这段{语言}代码：
1. 提升可读性/性能
2. 符合{规范}
3. 保留原有功能
4. 生成对比说明

3. 调试修复模板

修复这段代码的bug：
1. 定位问题
2. 给出完整修复代码
3. 解释错误原因
4. 验证方案

4. 项目规划模板

规划{项目类型}项目：
1. 技术栈选型
2. 目录结构
3. 核心模块设计
4. 开发计划

六、进阶技巧

1. 多会话并行：/new 新建会话，同时处理多个任务
2. 自定义 Agent：编辑 AGENTS.md 定义项目专属 AI 角色
3. 本地模型：接入 Ollama，实现完全离线开发
4. LSP 集成：自动加载语言服务器，提供代码诊断、补全GitHub
5. 会话分享：生成链接分享会话，协作调试OpenCode

七、常见问题

• 安装失败：Windows 需先装 Node.js，用 Git Bash 运行命令
• 模型不可用：检查 API Key / 网络，切换 OpenCode Zen 免费模型
• 权限问题：Mac/Linux 执行 sudo chmod +x /usr/local/bin/opencode
• 生成慢：切换轻量模型（如 Claude 3.7 Haiku），减少上下文