一、 环境依赖与安装指引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-aimacOS / Linux需安装 Bun 运行时采用 Bun 包管理器进行全局安装执行速度较快。当前版本不支持 Windows 操作系统。brew install ...macOS / Linux需安装 Homebrew 包管理器适用于 macOS 的标准软件管理方式支持环境变量自动注册。paru -S opencodeArch Linux 系列需安装 Paru AUR 助手针对 Arch 系 Linux 发行版如 Manjaro的专属安装命令从 AUR 源获取。1.2 Windows 环境下 npm 安装的路径配置问题及解决方案在 Windows 操作系统中使用npm i -g opencode-ai命令安装后若在终端执行opencode --version返回“找不到命令”或“未识别的内部或外部命令”错误其技术根本原因是 npm 的全局可执行文件存放目录未被注册到系统的PATH环境变量中。标准修复操作流程获取 npm 全局目录路径打开 PowerShell 或 CMD 终端执行以下命令以查询 npm 的前缀路径npm config get prefix该路径为opencode.cmd可执行文件的物理存储位置。注册系统环境变量将上述步骤获取的绝对路径添加到 Windows 系统的“环境变量” - “系统变量”或“用户变量”的Path列表中。重置终端进程关闭当前正在运行的所有 CMD 或 PowerShell 进程重新启动一个新的终端实例以重新加载系统环境变量。验证执行在新的终端实例中输入opencode--version终端返回版本号字符串即表示环境配置完成。1.3 首次启动与初始化流程完成安装后必须进行首次初始化配置方可使用 AI 编程代理能力。设定工作目录在终端中通过cd命令导航至目标项目的根目录。必须在项目目录中执行启动命令以便程序读取本地项目文件。cd D:\your-project-folder启动 TUI 界面输入opencode命令启动终端交互界面。配置模型提供商在输入框中输入/connect根据终端列表选择大语言模型服务商支持 OpenCode 官方、OpenRouter、Gemini、DeepSeek 等并输入对应的 API 密钥配置认证信息。执行项目初始化认证完成后输入/init命令。系统将执行静态文件扫描解析项目目录结构、配置文件如 package.json 等并在项目根目录自动生成核心配置文件。终止进程若需结束运行状态可在交互界面按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或CtrlX N实例化新会话对象清空上下文内存状态并分配新 Session ID。/sessions/resume,/continue,CtrlX L检索本地 SQLite 或 JSON 存储中的会话记录渲染列表面板供用户切换上下文。/compact/summarize,CtrlX C执行上下文压缩算法调用 LLM 对历史对话生成摘要释放 Token 占用空间丢弃过早期的精确细节。/session-info无打印当前 Session ID、Token 消耗统计、已加载上下文等元数据限特定分支版本支持。3.2 CLI 会话管理命令 (opencode session)使用session子命令对本地存储的会话数据进行增删查改。检索与列表操作opencode session list# 打印全量会话记录opencode session list --max-count20# 截断输出限制最大返回记录数为 20 条opencode session list--formatjson# 指定标准输出格式为 JSON便于 jq 等工具解析恢复与分支操作opencode--continue# 根据时间戳查询并加载最后一次活跃的会话数据opencode-c# 同上参数缩写opencode--sessionSessionID# 依据指定的精确 SessionID 加载会话opencode--sessionSessionID--fork# 状态克隆操作基于指定会话的状态创建一个拥有新 Session ID 的子会话后续操作不污染源会话。删除操作opencode session deleteSessionID# 从本地存储中抹除指定 ID 的记录opencode session deleteSessionID--force# 抑制确认交互提示强制执行删除缩写 -fopencode session deleteID1ID2ID3# 批处理删除多条记录opencode session delete--all# 清空本地会话数据库表缩写 -aopencode session delete--all--force# 无确认提示的全局清空操作其他数据统计类命令opencode stats# 汇总统计本地数据库中所有会话记录的 API Token 累计消耗量。opencodeexport[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重命名机制技术说明数据呈现重命名操作修改数据库后在执行opencode session list时渲染引擎会同时输出备注名与哈希 ID会话ID: ses_xxx | 备注: 订单模块优化-20260302。状态覆盖对同一会话重复执行rename命令将执行 SQL UPDATE 操作覆盖原有的备注字符串。加载标识约束备注字符串不被视为唯一检索键Primary Key。通过 CLI 恢复特定会话时参数--session必须接收原始的哈希[会话ID]字符串不可传入备注名称。下一篇OpenCode AI 编程助手的高级配置