OpenCode 多界面交互指南：TUI、CLI、Web 与 IDE

OpenCode 不只是一个终端里的 AI 助手——它同时提供了 TUI、CLI、Web 界面、IDE 扩展和 ACP 协议五种交互方式。不同场景下，最趁手的入口可能完全不同。这篇指南把五种方式的核心操作和配置要点梳理清楚，帮你快速选到合适的界面。

终端交互：TUI 核心操作

TUI 是 OpenCode 最常用的交互界面。在项目目录下运行 opencode 就会进入终端用户界面。

文件引用、Bash 命令与斜杠命令

TUI 里有三个高频操作前缀：

• @ 文件引用：输入 @ 触发模糊文件搜索，选中文件后内容自动注入对话。比如 @packages/functions/src/api/index.ts。
• ! Bash 命令：以 ! 开头的消息作为 shell 命令执行，输出自动加入对话。例如 !ls -la。
• / 斜杠命令：输入 / 后跟命令名快速执行操作。大多数命令有快捷键，默认前导键 ctrl+x。

常用斜杠命令：

/undo 和 /redo 底层依赖 Git 管理文件变更，项目必须是 Git 仓库才能用。/thinking 只控制思考块是否显示，不改变推理能力——切换推理模式用 ctrl+t。

编辑器设置与 TUI 配置

/editor 和 /export 都依赖 EDITOR 环境变量。GUI 编辑器需加 --wait：

export EDITOR=vim
export EDITOR="code --wait"  # GUI 编辑器必须加 --wait

常用选项：code、cursor、windsurf、nvim、vim、nano、subl。永久生效写进 ~/.bashrc 或 ~/.zshrc。

TUI 本身也支持配置：

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": { "enabled": true }
  }
}

scroll_speed 默认 3（最小 1），启用 scroll_acceleration 后会覆盖它，实现自然滚动加速。

命令行工具：CLI 命令全览

CLI 适合脚本化、自动化和无需交互的场景。所有命令以 opencode 开头。

核心命令

• agent：管理代理。opencode agent list 列出所有代理，opencode agent create 引导创建自定义代理。
• attach：将 TUI 连接到已运行的 OpenCode 后端。比如服务器上跑着 opencode web，另一台机器用 opencode attach http://10.20.30.40:4096 接入同一后端。支持 --dir 和 --session（-s）标志。
• auth：管理提供商凭据。opencode auth login 交互式配置 API 密钥，密钥存于 ~/.local/share/opencode/auth.json。opencode auth list（简写 ls）查看已认证提供商，opencode auth logout 清除凭据。
• github：管理 GitHub 代理。opencode github install 在仓库中安装 GitHub Actions 工作流，opencode github run 在 Actions 中运行代理。
• mcp：管理 MCP 服务器。opencode mcp add 引导添加本地或远程 MCP 服务器，opencode mcp list（简写 ls）查看连接状态，opencode mcp auth 对支持 OAuth 的服务器认证，opencode mcp debug 调试连接问题。
• models：列出可用模型，格式为 provider/model。可按提供商筛选（如 opencode models anthropic），--refresh 更新缓存，--verbose 显示详情。
• run：非交互模式，直接传入提示词。适合脚本和自动化。支持 --model（-m）、--agent、--file（-f）、--format、--share、--attach 等标志。配合 opencode serve 使用可避免 MCP 冷启动。
• serve：启动无界面 HTTP 服务器，提供 API 访问。不打开浏览器。设置 OPENCODE_SERVER_PASSWORD 启用 HTTP 基本认证。
• session：管理会话。opencode session list 列出所有会话，支持 --max-count（-n）和 --format。
• stats：显示 Token 用量和费用统计。支持 --days、--tools、--models、--project 标志。
• export / import：opencode export [sessionID] 导出会话为 JSON，opencode import <file> 从 JSON 文件或分享链接导入。
• web：启动带 Web 界面的服务器，自动打开浏览器。配置与 serve 类似。
• acp：启动 ACP 服务器，通过 stdin/stdout 使用 nd-JSON 通信。

全局标志与环境变量

CLI 接受的全局标志：--help（-h）、--version（-v）、--print-logs、--log-level。

关键环境变量：

实验性功能通过 OPENCODE_EXPERIMENTAL 全局启用，也可单独控制：OPENCODE_EXPERIMENTAL_PLAN_MODE（计划模式）、OPENCODE_EXPERIMENTAL_LSP_TOOL（LSP 工具）、OPENCODE_EXPERIMENTAL_FILEWATCHER（文件监听）等。这些功能可能会变更或移除。

浏览器访问：Web 界面配置与使用

运行 opencode web 就能在浏览器中使用 OpenCode。它会在 127.0.0.1 上启动本地服务器，选一个随机可用端口，并自动打开默认浏览器。

端口、主机名与网络访问

默认情况下服务器只监听本地。如果需要局域网或远程访问，调整主机名：

# 指定端口
opencode web --port 4096

# 允许网络访问
opencode web --hostname 0.0.0.0

使用 0.0.0.0 时，OpenCode 会同时显示本地地址和网络地址，方便你从其他设备连接。

mDNS 发现

启用 mDNS 可以让服务器在局域网内被自动发现：

opencode web --mdns

这会自动将主机名设为 0.0.0.0，并将服务广播为 opencode.local。如果同一网络跑多个实例，可以自定义域名：

opencode web --mdns --mdns-domain myproject.local

CORS 与认证

自定义前端需要跨域访问时，添加 CORS 允许域名：

opencode web --cors https://example.com

安全方面，未设置密码时服务器没有任何保护，本地使用没问题，但对外暴露时务必设置密码：

OPENCODE_SERVER_PASSWORD=secret opencode web

用户名默认为 opencode，可通过 OPENCODE_SERVER_USERNAME 修改。

会话管理与连接终端

Web 界面主页可以查看和管理会话，点击 "See Servers" 能看到已连接的服务器状态。

更有意思的是，Web 和 TUI 可以同时使用。在一个终端启动 Web 服务器，另一个终端用 opencode attach 连接，两者共享会话和状态：

# 终端 1：启动 Web 服务器
opencode web --port 4096

# 终端 2：连接 TUI
opencode attach http://localhost:4096

服务器选项也可以写在 opencode.json 中，命令行标志优先级更高：

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "cors": ["https://example.com"]
  }
}

Windows 用户建议从 WSL 而非 PowerShell 运行 opencode web，以确保文件系统访问和终端集成正常工作。

IDE 集成：VS Code 与 Cursor

OpenCode 提供了 VS Code 及其分支的扩展，支持 VS Code、Cursor、Windsurf 和 VSCodium。

安装与使用

安装方式非常简单：打开 VS Code 的集成终端，运行 opencode，扩展会自动安装。也可以在扩展商店搜索 "OpenCode" 手动安装。

安装后几个快捷键值得记住：

文件引用快捷键会插入类似 @File#L37-42 的格式，精确到行范围。同时，扩展会自动将当前选中内容或标签页共享给 OpenCode，省去手动粘贴的步骤。

如果希望在 TUI 中用 /editor 或 /export 时调用自己的 IDE，需要设置 EDITOR 环境变量：

export EDITOR="code --wait"

故障排除

扩展未能自动安装时，检查以下几点：

1. 确保是在集成终端中运行的 opencode，不是外部终端。
2. 确认 IDE 对应的 CLI 命令已安装：VS Code 需要 code，Cursor 需要 cursor，Windsurf 需要 windsurf，VSCodium 需要 codium。如果命令不在 PATH 中，按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows/Linux），搜索 "Shell Command: Install 'code' command in PATH"（或对应 IDE 的命令）。
3. 确保 VS Code 有权限安装扩展。

ACP 生态：Zed、JetBrains 与 Neovim

ACP（Agent Client Protocol）让 OpenCode 可以作为子进程嵌入任何兼容 ACP 的编辑器。运行 opencode acp 会启动一个通过 stdio 上的 nd-JSON 进行 JSON-RPC 通信的服务。配置好后，OpenCode 在编辑器里的体验和在终端中基本一致——内置工具、自定义工具、MCP 服务器、AGENTS.md 规则、代理和权限系统都正常工作。不过 /undo 和 /redo 在 ACP 模式下暂不支持。

Zed

在 ~/.config/zed/settings.json 中添加：

{
  "agent_servers": {
    "OpenCode": {
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

打开方式：命令面板执行 agent: new thread。也可以在 keymap.json 中绑定快捷键，比如 cmd-alt-o。

JetBrains IDEs

在 JetBrains IDE 的 acp.json 中添加。注意这里必须使用 opencode 的绝对路径：

{
  "agent_servers": {
    "OpenCode": {
      "command": "/absolute/path/bin/opencode",
      "args": ["acp"]
    }
  }
}

打开方式：在 AI Chat 代理选择器中选择 "OpenCode"。

Avante.nvim

在 Avante.nvim 配置中添加：

{
  acp_providers = {
    ["opencode"] = {
      command = "opencode",
      args = { "acp" }
    }
  }
}

如果需要传递环境变量，在 env 字段中设置。

CodeCompanion.nvim

在 Neovim 配置中：

require("codecompanion").setup({
  interactions = {
    chat = {
      adapter = {
        name = "opencode",
        model = "claude-sonnet-4",
      },
    },
  },
})

这会将 CodeCompanion 设置为使用 OpenCode 作为聊天的 ACP 代理。环境变量配置可参考 CodeCompanion.nvim 文档。

五种界面对比与选择建议

选择建议很直接：

• 日常编码用 TUI，功能最完整，快捷键操作效率高。
• CI/CD 或脚本用 CLI 的 opencode run，一条命令拿到结果。
• 远程或移动设备用 Web，浏览器打开就能用，配合 attach 还能和 TUI 共享会话。
• VS Code / Cursor 用户装 IDE 扩展，编辑器里随时唤出 OpenCode，上下文自动共享。
• Zed / JetBrains / Neovim 用户走 ACP 路线，配置一次就能在熟悉的编辑器里用上 OpenCode 的全部能力。

五种界面不是互斥的——你可以同时用 Web 做远程访问、TUI 做本地操作、IDE 扩展做编辑器集成，它们共享同一个后端和会话数据。