OpenCode 是一个开源的 AI 编程代理，拥有超 16 万 GitHub Stars、900 多位贡献者，每月服务超 750 万开发者。除了终端 CLI 和 IDE 扩展之外，OpenCode 提供桌面端应用（Beta），支持 macOS（Apple Silicon & Intel）、Windows（x64）和 Linux（.deb / .rpm）。桌面端将 TUI 包装为原生窗口，搭配多会话标签页、桌面通知、系统菜单栏等原生能力。以下逐一拆解其全部功能。

一、桌面端原生体验

桌面端的核心定位是将 OpenCode 的 TUI（Terminal User Interface）以原生应用形态呈现，同时叠加窗口系统专属能力。

1.1 安装与启动

首次启动后，桌面端可直接从系统 Dock / 任务栏 / 应用菜单启动，无需打开终端。支持自动更新（可在 opencode.json 中设置 autoupdate: false 禁用，或设为 "notify" 仅接收更新通知）。

1.2 窗口与标题栏

• 标题栏内嵌会话标签页导航，当前会话状态（如运行中、等待输入）直接显示在标题栏
• 支持标签页布局切换（设置中可选择标签页排列方式）
• 每个标签页对应一个独立的 OpenCode 会话，互不干扰
• 标题栏集成应用更新操作入口
• Linux / Windows 支持菜单栏自动隐藏

1.3 多会话管理

• Ctrl / Cmd + 数字键：在多个项目间快速切换
• 关闭当前项目后自动打开下一个可用项目
• 每个标签页独立维护自己的上下文、模型选择和对话历史
• 标签页关闭按钮可视化（修复了早期版本不稳定显示的问题）

二、完整 TUI 界面

桌面端内置了完整的 TUI，是日常交互的核心界面。

2.1 会话控制

斜杠命令系统

输入 / 即可触发命令，完整命令列表：

Plan 模式与 Build 模式

• 按 Tab 键 在 Plan（计划模式）和 Build（构建模式）之间切换
• Plan 模式：AI 只能生成方案，禁止任何文件修改，适合需求讨论阶段
• Build 模式：AI 可以读取、写入、修改文件，执行实际编码
• 状态指示器显示在右下角，清晰标明当前所处模式

撤销 / 重做系统

• 基于 Git 管理文件变更，项目必须是 Git 仓库
• 支持多次连续撤销，每次回到上一个消息状态
• 重做恢复撤销的变更及其对应的文件修改
• 快照功能默认开启（可在 opencode.json 中设置 snapshot: false 关闭）

2.2 消息与输入

文件引用（@ 语法）

• 在消息中输入 @ 触发模糊搜索，自动补全项目文件路径
• 引用文件的全部内容自动加入对话上下文
• 支持配置引用别名：@alias 添加根目录，@alias/ 深度搜索子文件

Shell 命令（! 语法）

• 消息以 ! 开头直接执行 Shell 命令
• 命令输出自动作为工具结果返回给 AI
• Shell 可配置（opencode.json 中 shell 选项，支持 pwsh、zsh、bash 等）

提示输入功能

• 输入框随终端宽度自适应 resize，可通过配置设定最小/最大尺寸
• 多行输入：Shift+Enter 换行，Enter 提交
• 输入历史：上下箭头浏览历史消息
• 剪贴板粘贴：支持 Ctrl+V（可配置 preventDefault）
• 拖放图片：直接拖拽图片到输入框，自动转换为上下文

编辑器集成

• /editor 使用 $EDITOR 环境变量指定的编辑器撰写长消息
• /export 导出会话到编辑器查看
• 支持 VS Code、Cursor、Neovim、Vim、Nano、Sublime Text 等编辑器
• GUI 编辑器需要 --wait 标志

2.3 Diff 查看器

• 内置代码差异查看器，支持文件树浏览
• 单一子目录自动折叠，保持文件树简洁
• 差异展示模式：auto（自适应宽度）、stacked（固定单列）
• 进入 Diff 查看器后自动聚焦第一个变更文件
• 关闭 Diff 查看器后返回之前浏览的界面
• 键盘快捷键操作，支持快速浏览

2.4 命令面板

• Ctrl+P 打开命令面板
• 支持模糊搜索所有可用操作
• 部分设置（如用户名显示切换）通过命令面板调整且重启后持久化

2.5 思维链（Thinking）显示

• 支持模型的逐步推理过程展示
• 可折叠/展开推理块
• /thinking 命令控制推理块的显示与隐藏
• Ctrl+T 循环切换模型变体（含是否启用扩展推理）
• 折叠状态的默认为收起

三、多模型与多供应商

桌面端支持对接 75+ LLM 供应商，覆盖云模型和本地模型。

3.1 模型接入方式

3.2 模型管理

• /models 列出所有可用模型
• Ctrl+A 供应商列表，Ctrl+F 收藏模型
• F2 / Shift+F2 最近使用模型快速切换
• 模型选择跨会话持久化，切换标签页不会丢失选定模型
• model 和 small_model 配置主模型与轻量模型（标题生成等小任务）
• 支持按供应商级别配置超时（timeout、chunkTimeout）

3.3 OpenCode Go 模型矩阵

四、会话管理

4.1 多会话并行

• 每个标签页一个独立会话，可并行运行
• 会话数据持久化存储，重启应用后恢复
• 最近会话自动出现在会话选择器中

4.2 会话置顶

• 支持将会话置顶到会话列表顶部
• 已置顶会话分配快速切换快捷键槽位
• 置顶会话在列表中保持固定位置（不因新活动而移动）
• 允许在置顶会话间循环切换

4.3 会话压缩（Compaction）

• 当上下文即将填满时自动压缩（默认开启）
• auto：自动触发；prune：移除旧工具输出节省 token
• reserved：保留 token 缓冲区（默认 10000），避免压缩期间溢出
• 压缩后保留最近几轮对话（不会全部折叠到摘要中）
• 可手动 /compact 触发

4.4 会话分叉（Fork）

• 从已有会话创建分叉，保留到分叉点的所有历史
• 分叉后新旧会话独立演进

4.5 会话导入/导出

• 会话可导出为 Markdown 文件
• 导入的会话自动刷新目录和相对路径字段
• 支持 --replay 和 --replay-limit 参数恢复最近历史

五、分享与协作

5.1 分享机制

• /share 生成唯一 URL：opncd.ai/s/<share-id>
• 分享内容同步到 OpenCode 服务器
• 任何拥有链接的人可公开访问

5.2 分享模式

5.3 取消分享

• /unshare 停止分享并删除服务器数据
• 删除全部会话历史、消息和元数据

5.4 企业级安全

• 支持 SSO 认证用户仅限分享
• 支持自托管分享服务器
• 可通过 MDM / 托管配置强制禁用分享

六、桌面通知与注意力系统（Attention）

6.1 触发场景

桌面端在以下场景触发注意力机制：

• AI 需要用户确认（提问）
• 需要用户授权（权限请求）
• 会话出错
• 会话完成
• 子代理任务完成

6.2 配置项（tui.json）

{
  "attention": {
    "enabled": true,        // 总开关
    "notifications": true,  // 桌面通知（窗口失焦时）
    "sound": true,          // 音效开关
    "volume": 0.4,          // 音量 0~1
    "sound_pack": "opencode.default",  // 音效包
    "sounds": {
      "error": "./sounds/error.mp3",
      "question": "./sounds/question.mp3",
      "permission": "./sounds/permission.mp3",
      "done": "./sounds/done.mp3",
      "subagent_done": "./sounds/subagent_done.mp3"
    }
  }
}

• 内置音效包 opencode.default
• 所有音效支持自定义文件覆盖（绝对路径、file:// URL 或相对于 tui.json 的路径）
• 非子代理事件仅在终端窗口模糊时推送桌面通知

七、深度自定义

7.1 主题系统

内置主题

自定义主题

• JSON 格式，支持：
  • 16 进制色："#ffffff"
  • ANSI 色索引：3（0-255）
  • 颜色引用："primary" 引用自定义定义
  • 亮/暗双模式：{"dark": "#000", "light": "#fff"}
  • 透明色："none"（继承终端默认色）
• 主题加载优先级：内置 < 用户目录 < 项目根目录 < 当前目录
• 完整颜色定义覆盖：primary / secondary / accent / text / background / border / diff / markdown / syntax 等 40+ 色彩变量

主题目录结构

~/.config/opencode/themes/my-theme.json
.opencode/themes/my-theme.json

7.2 快捷键系统

完整的键盘快捷键系统，覆盖所有操作：

Leader 键系统：默认 Ctrl+X，按 Leader 键后再按功能键触发操作，避免终端快捷键冲突。可通过 leader_timeout 设置等待超时（默认 2000ms）。

分组快捷键一览：

快捷键支持禁用（设为 "none"）、多重绑定（数组对象），以及 preventDefault 等高级配置。

7.3 桌面端专用快捷键

桌面端输入框支持 Readline/Emacs 风格的编辑快捷键：

7.4 桌面端键盘快捷键

7.5 其他自定义

滚动设置：

• scroll_speed：滚动速度（默认 3，支持小数）
• scroll_acceleration：macOS 风格加速滚动（开启后覆盖 scroll_speed）

鼠标设置：

• mouse：启用/禁用鼠标捕获（默认 true，关闭后恢复终端原生选择）

Diff 显示：

• diff_style："auto"（自适应宽度）或 "stacked"（固定单列）

用户名显示：

• 通过命令面板切换聊天中用户名的显示/隐藏，持久化存储

八、LSP 语言服务器集成

OpenCode 自动加载 LSP 服务器，将诊断反馈传递给 AI 代理。

8.1 内置 LSP 支持

8.2 配置

{
  "lsp": true                     // 一键启用全部
}
{
  "lsp": {
    "typescript": { "disabled": true },  // 单独禁用
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"],
      "env": { "DEBUG": "1" },
      "initialization": { "preferences": {} }
    }
  }
}

LSP 默认关闭。建议在确实需要时启用，因为 LSP 可能消耗大量内存并拖慢代理工作流。更好的做法是在 AGENTS.md 中配置 lint/typecheck 命令让 AI 直接运行。

九、MCP 服务器（Model Context Protocol）

9.1 支持的 MCP 类型

9.2 配置

{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true,
      "environment": { "KEY": "value" },
      "timeout": 5000
    }
  }
}

9.3 MCP 工具管理

• 工具以 mcp-server-name_tool-name 格式注册
• 可在 tools 配置中全局启用/禁用
• 支持按 Agent 粒度控制 MCP 工具可见性
• 支持 Glob 模式批量禁用

9.4 OAuth 认证

• 自动动态客户端注册（RFC 7591）
• Token 安全存储于 ~/.local/share/opencode/mcp-auth.json
• 支持预注册 clientId/clientSecret
• CLI 管理命令：
  • opencode mcp auth <name>：手动触发 OAuth
  • opencode mcp list：列出所有 MCP 及认证状态
  • opencode mcp logout <name>：清除凭据
  • opencode mcp debug <name>：调试连接和 OAuth 流程

9.5 常用 MCP 示例

十、权限与安全系统

10.1 权限级别

• "allow"：自动执行
• "ask"：用户确认
• "deny"：阻止执行

10.2 可配置的权限项

10.3 精细权限控制

支持按命令模式匹配的细粒度权限：

{
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "rm *": "deny",
      "npm *": "allow"
    },
    "read": {
      "*": "allow",
      ".env": "deny",
      ".env.*": "deny",
      ".env.example": "allow"
    }
  }
}

通配符支持：*（任意多字符）、?（单个字符）、~ / $HOME 家目录展开。

10.4 权限提示 UI

当需要用户确认时，UI 提供三个选项：

• once：仅本次允许
• always：本次会话内自动允许匹配该模式的操作
• reject：拒绝

10.5 企业级托管配置

支持通过 MDM 和系统级配置强制执行：

十一、Web 服务器模式

桌面端也可作为 Web 服务器运行，提供浏览器内的 OpenCode 体验。

11.1 启动

opencode web --port 4096 --hostname 0.0.0.0

11.2 Web 功能

• 完整的会话管理（开始、查看、切换）
• 服务器状态查看
• 支持 mDNS 服务发现（opencode web --mdns，默认域名 opencode.local）
• 多实例支持（自定义 mDNS 域名）
• CORS 配置（自定义前端接入）
• 密码保护（OPENCODE_SERVER_PASSWORD）

11.3 终端附加

Web 服务器运行时可从终端附加 TUI：

opencode attach http://localhost:4096

Web 与终端共享同一组会话和状态。

十二、IDE 扩展

OpenCode 桌面端与主流 IDE 深度集成。

12.1 支持平台

12.2 快捷键操作

• Cmd+Esc（Mac）/ Ctrl+Esc（Windows/Linux）：在分栏终端中打开 OpenCode
• Cmd+Shift+Esc / Ctrl+Shift+Esc：新建会话
• Cmd+Option+K（Mac）/ Alt+Ctrl+K：插入文件引用（@File#L37-42）
• 自动共享当前选中代码和标签页文件上下文

12.3 自动安装

在 IDE 终端中直接运行 opencode，扩展自动安装。如果失败，确保 IDE 的 CLI 命令已加入 PATH。

十三、Agent 系统

13.1 内置 Agent

13.2 自定义 Agent

支持 JSON 和 Markdown 两种定义方式：

{
  "agent": {
    "code-reviewer": {
      "description": "代码审查",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security.",
      "tools": { "write": false, "edit": false }
    }
  }
}

Markdown 文件形式（~/.config/opencode/agents/review.md）：

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
---
Only analyze code and suggest changes.

13.3 默认 Agent

default_agent 配置可设置默认 Agent（"build" 或 "plan" 或自定义）。如果指定的 Agent 不存在，降级到 "build"。

13.4 子代理

• 支持子代理嵌套调用
• Ctrl+X ↓ 跳转/聚焦子代理会话
• ← / → 切换子代理
• ↑ 返回父会话
• 实验性：后台子代理，任务可继续运行而不阻塞主会话

13.5 Agent 预设

操作可通过 /agent 或 Tab 快速切换不同 Agent。

十四、自定义命令

在 opencode.json 中定义可复用的快捷命令：

{
  "command": {
    "test": {
      "template": "Run full test suite with coverage.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create new React component $ARGUMENTS with TypeScript.",
      "description": "Create new component"
    }
  }
}

• 支持 $ARGUMENTS 变量替换
• 可为命令指定不同的 Agent 和模型
• 支持 Markdown 文件方式定义

十五、Formatter 与 Lint 集成

15.1 内置格式化工具

15.2 配置

{
  "formatter": {
    "prettier": { "disabled": true },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "extensions": [".js", ".ts"]
    }
  }
}

十六、配置系统

16.1 配置文件

16.2 配置加载优先级

1. 远程配置（.well-known/opencode）
2. 全局配置（~/.config/opencode/opencode.json）
3. 自定义路径（OPENCODE_CONFIG 环境变量）
4. 项目配置（项目根目录 opencode.json）
5. .opencode 目录（agents, commands, plugins）
6. 内联配置（OPENCODE_CONFIG_CONTENT 环境变量）
7. 托管配置（系统级 managed config）
8. macOS MDM（优先级最高，不可被用户覆盖）

配置合并而非覆盖，不同来源的非冲突设置全部保留。

16.3 变量替换

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" }
    },
    "openai": {
      "options": { "apiKey": "{file:~/.secrets/openai-key}" }
    }
  }
}

• {env:NAME}：引用环境变量
• {file:path}：引用文件内容（支持相对路径、绝对路径、~ 家目录）

十七、日志与调试

• 桌面端日志导出：通过标题栏菜单导出
• 调试配置：opencode debug config 查看当前所有已合并配置
• MCP 调试：opencode mcp debug <name>
• 更新日志：
  • autoupdate: "notify" 在新版本可用时通知但不下自动安装
  • 更新操作入口集成在标题栏
  • 安装最新可用更新（避免重复下载）

十八、近期桌面端新增功能（v1.15.x）

小结

OpenCode 桌面端不仅仅是一个套壳的终端——它在完整保留 TUI 能力的基础上，叠加了原生窗口系统的多会话标签页、桌面通知、系统菜单、缩放手势、日志导出等能力。配合 75+ 供应商接入、30+ LSP 语言服务器、MCP 工具扩展、精细的权限控制、深度可定制的主题和快捷键系统，覆盖了从个人快速编码到企业安全合规的完整场景。

桌面端仍在 Beta 阶段，功能迭代速度极快（v1.15 系列几乎每日更新）。如果你想尝试开源编程 AI Agent 的原生桌面体验，现在就是最好的时机。

下载：opencode.ai/download GitHub：github.com/anomalyco/opencode 文档：opencode.ai/docs