一、 环境依赖与安装指引

OpenCode 提供了多种安装方式以适配不同的操作系统与包管理器。用户需根据本地开发环境选择合适的安装命令。

1.1 支持的安装方式与命令列表

OpenCode 下载地址

安装命令	适用操作系统环境	依赖条件	技术说明
curl -fsSL ...	macOS / Linux	系统需预装 curl 与 Bash 解释器	官方提供的 shell 脚本，自动检测系统架构并下载对应的二进制编译文件。
npm i -g opencode-ai	跨平台（包含 Windows / macOS / Linux）	需安装 Node.js 运行时环境 (要求 v16 及以上版本)	通过 Node Package Manager 进行全局安装。适用于已配置 Node.js 环境变量的系统。
bun add -g opencode-ai	macOS / Linux	需安装 Bun 运行时	采用 Bun 包管理器进行全局安装，执行速度较快。当前版本不支持 Windows 操作系统。
brew install ...	macOS / Linux	需安装 Homebrew 包管理器	适用于 macOS 的标准软件管理方式，支持环境变量自动注册。
paru -S opencode	Arch Linux 系列	需安装 Paru AUR 助手	针对 Arch 系 Linux 发行版（如 Manjaro）的专属安装命令，从 AUR 源获取。

1.2 Windows 环境下 npm 安装的路径配置问题及解决方案

在 Windows 操作系统中使用 npm i -g opencode-ai 命令安装后，若在终端执行 opencode --version 返回“找不到命令”或“未识别的内部或外部命令”错误，其技术根本原因是 npm 的全局可执行文件存放目录未被注册到系统的 PATH 环境变量中。

标准修复操作流程：

1. 获取 npm 全局目录路径
   打开 PowerShell 或 CMD 终端，执行以下命令以查询 npm 的前缀路径：

   npm config get prefix
   

   该路径为 opencode.cmd 可执行文件的物理存储位置。

2. 注册系统环境变量
   将上述步骤获取的绝对路径，添加到 Windows 系统的“环境变量” -> “系统变量”或“用户变量”的 Path 列表中。

3. 重置终端进程
   关闭当前正在运行的所有 CMD 或 PowerShell 进程，重新启动一个新的终端实例，以重新加载系统环境变量。

4. 验证执行
   在新的终端实例中输入：

   opencode --version
   

   终端返回版本号字符串即表示环境配置完成。

1.3 首次启动与初始化流程

完成安装后，必须进行首次初始化配置方可使用 AI 编程代理能力。

1. 设定工作目录：在终端中，通过 cd 命令导航至目标项目的根目录。必须在项目目录中执行启动命令，以便程序读取本地项目文件。

   cd D:\your-project-folder
   

2. 启动 TUI 界面：输入 opencode 命令启动终端交互界面。

3. 配置模型提供商：在输入框中输入 /connect，根据终端列表选择大语言模型服务商（支持 OpenCode 官方、OpenRouter、Gemini、DeepSeek 等），并输入对应的 API 密钥配置认证信息。

4. 执行项目初始化：认证完成后，输入 /init 命令。系统将执行静态文件扫描，解析项目目录结构、配置文件（如 package.json 等），并在项目根目录自动生成核心配置文件。

5. 终止进程：若需结束运行状态，可在交互界面按 Ctrl + C 组合键，或输入 /exit 命令终止当前进程。

---

二、 核心命令与快捷操作系统

OpenCode 的指令系统分为 TUI 内部指令（以 / 前缀开头）和 CLI 外部命令行参数两种运行模式。

2.1 TUI 内部核心指令

在 opencode 运行后的终端界面内，支持以下标准指令：

指令名称	技术行为描述	适用场景
/init	触发静态代码扫描分析，生成包含项目技术栈与结构规范的配置文件（AGENTS.md）。	项目接入 OpenCode 的首个必执命令。
/connect	触发 API 密钥配置程序，修改本地认证存储文件。	首次使用或需变更 LLM 服务提供商时。
/models	查询当前认证状态下的可用模型列表，并提供切换接口。	需在不同模型（如 Claude / Gemini / GLM 等）间进行负载或能力切换时。
/undo	回滚上一执行批次的 AI 操作，包含文件系统的写操作（恢复修改前的文件状态）。	AI 生成的代码出现逻辑错误或破坏现有架构时。
/redo	取消上一次的回滚（undo）操作，重新应用 AI 的修改。	错误执行撤销指令后的恢复操作。
/help	输出指令系统帮助文档及快捷键映射表。	查询命令语法时。

2.2 文件上下文与代理操作指令

• @文件名 或 @路径/文件：上下文注入指令。触发本地文件系统的模糊匹配搜索，将选定文件的文本内容读取并加载至当前会话的上下文内存中。
• /editor：外部编辑器唤醒指令。调用系统默认或配置文件指定的外部文本编辑器（如 Vim, Nano, VS Code 等）进行长文本提示词的输入，保存退出后内容自动回传至 OpenCode 输入流。
• /export：数据导出指令。将当前会话的历史记录序列化为 Markdown 格式文件并保存至本地磁盘。
• /share / /unshare：网络分享指令。将脱敏后的会话数据上传至远程服务器并返回公开访问 URL / 撤销该 URL 的访问权限。
• /agent build：模式切换指令。将当前代理实例切换至 Build（构建）模式。该模式具备最高系统权限，被允许直接调用写操作和执行 Shell 脚本。
• /agent plan：模式切换指令。将当前代理实例切换至 Plan（规划）模式。该模式默认配置为只读权限，禁止进行文件修改操作。
• /agent list：查询指令。检索并打印当前注册的所有可用代理（Agent）列表。

2.3 CLI 命令行参数

在未启动交互界面的外部终端中，OpenCode 提供以下命令行接口：

opencode                     # 无参数运行，初始化 TUI 进程。
opencode -p "<文本>"          # 非交互式单次执行指令。将参数字符串作为 prompt 发送，接收响应后终止进程。适合集成至 CI/CD 脚本。
opencode run "<文本>"         # 语义等同于 -p 参数。
opencode --debug             # 以调试级别启动日志记录模块，输出底层网络请求与错误堆栈。
opencode serve               # 以 headless (无头) 模式启动后台服务端，监听特定端口，用于远程连接或多终端共享状态。
opencode web                 # 启动集成 Web UI 的服务端进程。
opencode attach              # 作为客户端进程附加到当前正在运行的 serve 后台实例。
opencode models              # 输出可用模型列表至标准输出 (stdout)。
opencode agent list          # 输出可用代理列表至标准输出 (stdout)。

2.4 TUI 快捷键映射

• Ctrl + C：若输入缓冲区不为空，则清空缓冲区；若输入缓冲区为空，则向进程发送 SIGINT 信号退出程序。
• Shift + Enter：在输入缓冲区插入换行符，阻断即时发送行为。
• Enter：将输入缓冲区的内容序列化并发送至服务端进行推理计算。
• Ctrl + R：触发 /redo 逻辑（依据具体软件版本而定）。
• ? 或 Ctrl + / (视终端而定)：快捷展示 /help 菜单。

---

三、 会话 (Session) 管理机制

OpenCode 采用独立的会话隔离机制，每个会话维护独立的上下文历史、状态数据以及内存数据。会话管理可通过 TUI 指令或 CLI 子命令完成。

3.1 TUI 会话管理指令

指令	别名/快捷键	行为定义
/new	/clear 或 Ctrl+X N	实例化新会话对象，清空上下文内存状态，并分配新 Session ID。
/sessions	/resume, /continue, Ctrl+X L	检索本地 SQLite 或 JSON 存储中的会话记录，渲染列表面板供用户切换上下文。
/compact	/summarize, Ctrl+X C	执行上下文压缩算法：调用 LLM 对历史对话生成摘要，释放 Token 占用空间，丢弃过早期的精确细节。
/session-info	无	打印当前 Session ID、Token 消耗统计、已加载上下文等元数据（限特定分支版本支持）。

3.2 CLI 会话管理命令 (opencode session)

使用 session 子命令对本地存储的会话数据进行增删查改。

检索与列表操作：

opencode session list                          # 打印全量会话记录
opencode session list --max-count 20           # 截断输出，限制最大返回记录数为 20 条
opencode session list --format json            # 指定标准输出格式为 JSON，便于 jq 等工具解析

恢复与分支操作：

opencode --continue                            # 根据时间戳查询并加载最后一次活跃的会话数据
opencode -c                                    # 同上，参数缩写
opencode --session <SessionID>                 # 依据指定的精确 SessionID 加载会话
opencode --session <SessionID> --fork          # 状态克隆操作：基于指定会话的状态创建一个拥有新 Session ID 的子会话，后续操作不污染源会话。

删除操作：

opencode session delete <SessionID>            # 从本地存储中抹除指定 ID 的记录
opencode session delete <SessionID> --force    # 抑制确认交互提示，强制执行删除（缩写 -f）
opencode session delete <ID1> <ID2> <ID3>      # 批处理删除多条记录
opencode session delete --all                  # 清空本地会话数据库表（缩写 -a）
opencode session delete --all --force          # 无确认提示的全局清空操作

其他数据统计类命令：

opencode stats                                 # 汇总统计本地数据库中所有会话记录的 API Token 累计消耗量。
opencode export [SessionID]                    # 指定 ID 执行序列化导出。若省略 ID 参数，则触发终端交互式选择面板。
opencode auth list                             # 查询本地密钥管理模块中已配置的认证信息列表。

3.3 会话重命名与备注系统

为解决默认的哈希字符串类型 Session ID 缺乏可读性的问题，OpenCode 提供了会话重命名接口。重命名功能是对会话记录追加字符串类型的 " 标签/备注 " 字段。

针对当前活跃会话：
在当前会话的上下文环境中（终端正在运行该会话），执行以下命令修改当前内存及持久化存储中的备注数据：

opencode session rename --current "用户中心重构-20260303"

参数 --current 指向当前运行实例。备注字符串规范建议包含 " 业务标识 + 时间戳 " 以提升检索效率。

针对后台历史会话：
若需操作非活跃会话，必须通过 list 命令获取其哈希 ID，随后显式传递给 rename 接口：

opencode session list
opencode session rename ses_34ca06735ffeknGDD6Y6TKt0MQ "订单模块优化-20260302"

重命名机制技术说明：

1. 数据呈现：重命名操作修改数据库后，在执行 opencode session list 时，渲染引擎会同时输出备注名与哈希 ID：会话ID: ses_xxx | 备注: 订单模块优化-20260302。
2. 状态覆盖：对同一会话重复执行 rename 命令，将执行 SQL UPDATE 操作覆盖原有的备注字符串。
3. 加载标识约束：备注字符串不被视为唯一检索键（Primary Key）。通过 CLI 恢复特定会话时，参数 --session 必须接收原始的哈希 [会话ID] 字符串，不可传入备注名称。

---

下一篇：OpenCode AI 编程助手的高级配置