OpenCode使用指南 - CLI命令/Skills技能/Desktop桌面端详解

OpenCode CLI 命令 opencode cli

OpenCode CLI 是功能最完整的使用方式，提供丰富的斜杠命令和 TUI 界面。以下是所有核心命令的详细说明。

基础命令

命令	功能说明
`/connect`	添加 LLM 提供商 — Zen、Anthropic、OpenAI、Z.AI、Ollama、Copilot OAuth 等
`/models`	选择或切换 AI 模型（Claude、GPT-4o、GLM-5.2、DeepSeek 等）
`/init`	分析代码仓库并创建 AGENTS.md 项目记忆文件
`Tab`	切换 Plan 模式（只读规划）与 Build 模式（编辑文件）
`/compact`	上下文压缩，长会话时使用以节省 Token
`/share`	创建当前对话的分享链接，用于调试或团队协作
`/export`	导出离线产物
`/undo`	撤销最近的修改（需要 Git 仓库）
`/redo`	重做已撤销的修改

@ 文件引用

在输入框中使用 @ 键可以模糊搜索并引用项目文件，帮助 OpenCode 精确定位需要修改的代码。

          示例
          
          # 引用文件并提问

          How is authentication handled in @packages/functions/src/api/index.ts?

          # 参考已有逻辑实现新功能

          Add auth to /settings route, mirror the logic in @packages/functions/src/notes.ts

拖放图片

OpenCode 支持将图片拖放到终端中添加到提示词。可以给代理展示设计稿、截图等视觉参考。

          # 在 Plan 模式中

          [Image #1] Take a look at this design and use it as a reference

          for the new settings screen.

Plan / Build 工作流

OpenCode 独有的双模式工作流是核心特色之一，让你对 AI 的修改有完全的控制权。

Plan 模式（只读）

只读分析代码库，制定实施方案，不会修改任何文件。适合探索不熟悉的代码、规划复杂功能。运行 bash 命令前需获得许可。

Build 模式（默认）

拥有完全权限的开发代理，可以直接编辑文件、运行命令。用于实际编码和修改，是日常开发的主要模式。

Tab 切换

随时按 Tab 键在两种模式间切换。右下角会显示当前模式状态。推荐先 Plan 再 Build 的工作流。

          # 1. 切换到 Plan 模式

          [Tab] → Plan Mode

          # 2. 描述需求

          When a user deletes a note, flag it as deleted in the database.

          Then create a screen showing recently deleted notes with

          undelete and permanent delete options.

          # 3. 审查并迭代计划

          Looks good, but also add a confirmation dialog for permanent delete.

          # 4. 切换到 Build 模式执行

          [Tab] → Build Mode

          Go ahead and make the changes.

Skills 技能系统 opencode skills

Skills 让你通过 SKILL.md 文件定义可复用的代理行为。OpenCode 会自动发现可用技能并按需加载，无需手动指定。

技能文件位置

OpenCode 搜索以下位置的技能文件（每处一个文件夹，内含 SKILL.md）：

          # 项目级配置

          .opencode/skills/<name>/SKILL.md

          .claude/skills/<name>/SKILL.md

          .agents/skills/<name>/SKILL.md

          # 全局级配置

          ~/.config/opencode/skills/<name>/SKILL.md

          ~/.claude/skills/<name>/SKILL.md

          ~/.agents/skills/<name>/SKILL.md

SKILL.md 格式

每个 SKILL.md 必须以 YAML frontmatter 开头，包含 name 和 description 字段。

          .opencode/skills/git-release/SKILL.md
          
          ---

          name: git-release

          description: Create consistent releases and changelogs

          license: MIT

          compatibility: opencode

          metadata:

            audience: maintainers

            workflow: github

          ---

          ## What I do

          - Draft release notes from merged PRs

          - Propose a version bump

          - Provide a gh release create command

          ## When to use me

          Use this when preparing a tagged release.

          Ask clarifying questions if versioning is unclear.

名称规范

name 字段必须：1-64 字符、小写字母数字加单个连字符分隔、不能以连字符开头或结尾、不能有连续 --、必须与包含 SKILL.md 的目录名一致。正则：^[a-z0-9]+(-[a-z0-9]+)*$

权限控制

在 opencode.json 中通过模式匹配控制代理可以访问哪些技能：

          {

            "permission": {

              "skill": {

                "*": "allow",

                "pr-review": "allow",

                "internal-*": "deny",

                "experimental-*": "ask"

              }

            }

          }

allow

技能立即加载

deny

技能对代理隐藏

ask

加载前需用户确认

自定义斜杠命令

在 .opencode/commands/ 目录下创建 Markdown 文件来定义自定义斜杠命令。

          .opencode/commands/test-until-green.md
          
          ---

          description: Run tests until green

          agent: build

          model: provider/model-id

          subtask: false

          ---

          Run the test suite. Fix failures. Stop when all tests pass.

          Arguments: $ARGUMENTS

支持的变量和模式

变量/模式	说明
`$ARGUMENTS`	传入命令的参数
`$1` / `$2`	位置参数
`@path`	文件引用
!`shell`	执行 shell 命令
`subtask: true`	强制子代理隔离
`agent: build`	指定代理类型（build/plan/general）
`model: provider/model-id`	指定使用的模型

OpenCode Desktop 桌面应用 opencode desktop

OpenCode Desktop 是桌面 GUI 版本（目前 Beta 测试中），使用与 CLI 相同的代理核心，适合偏好图形界面的开发者。

图形界面

提供完整的图形化对话界面，无需终端操作，对新手更友好

同一核心

桌面版使用与 CLI 相同的代理核心，功能完全一致，包括 Plan/Build 模式

跨平台

支持 macOS（Apple Silicon/Intel）、Windows 和 Linux，下载即用

桌面应用目前为 Beta 版本。从下载页面获取对应平台的安装包，或使用 brew install --cask opencode-desktop（macOS）/ scoop install extras/opencode-desktop（Windows）安装。

高级功能

OpenCode 还提供多会话并行、LSP 集成、子代理、MCP 服务器等高级功能。

多会话并行

在同一项目上启动多个并行代理。例如：线程 A 修复测试失败，线程 B 更新文档，互不干扰。

LSP 自动集成

自动加载适合的语言服务器（LSP），提供代码诊断、符号导航、跳转定义等功能，无需手动配置。

子代理（Sub-agents）

内置子代理功能，可将繁重任务交给独立子代理处理，实现上下文隔离。通过 @general 调用。

MCP 服务器

支持配置 MCP（Model Context Protocol）服务器，扩展代理能力：Web 搜索、文档查询、内部工具集成等。

隐私优先

OpenCode 不在其基础设施上存储代码或上下文数据。支持本地 Ollama 实现气隙隔离，适合受监管环境。

会话分享

/share 生成对话链接，团队成员无需安装即可查看代理运行过程，便于调试和代码审查。

配置文件

OpenCode 使用 opencode.json 进行项目级或全局配置。

          {

            "provider": {

              "anthropic": {

                "baseURL": "https://api.anthropic.com",

                "models": { "claude-sonnet-4": {} }

              }

            },

            "permission": {

              "skill": { "*": "allow" }

            },

            "agent": {

              "plan": { "tools": { "skill": false } }

            }

          }

配置项说明

配置项	说明
`provider`	每个提供商的 baseURL、模型列表和选项。对自定义端点和企业代理至关重要
`permission`	技能和工具的权限控制（allow/deny/ask）
`agent`	内置代理（build/plan/general）的工具和权限配置
`mcp`	MCP 服务器定义，一次配置跨会话复用
主题和快捷键	自定义 TUI 外观和快捷键，无需 fork 代码
格式化工具	接入 Prettier、rustfmt 等以匹配团队代码风格

开始使用 OpenCode

下载安装 OpenCode，体验开源 AI 编程代理的强大功能

opencode 下载 GitHub 仓库

OpenCode 使用指南