OpenCode 使用说明

Posted on Mar 31, 2026

这份文档基于 OpenCode 官方文档整理，偏向本机 show-help 的速查用法。

它是什么

  • OpenCode 是一个开源 coding agent。
  • 默认进入 TUI，也支持非交互、HTTP server、Web UI、ACP、GitHub agent。
  • 配置使用 JSON / JSONC，而不是 TOML。

安装

npm i -g opencode-ai

升级：

opencode upgrade

官方使用入口

启动 TUI

opencode
opencode /path/to/project

非交互模式

opencode run "Explain how closures work in JavaScript"

远程 / Headless

opencode serve
opencode web
opencode acp
opencode attach <http://localhost:4096>

常用 CLI 命令

会话与执行

  • opencode：启动 TUI
  • opencode run ...：非交互执行
  • opencode session list：列出会话
  • opencode export [sessionID]：导出会话 JSON
  • opencode import <file|share-url>：导入会话
  • opencode stats：看 token / cost 统计

Agent / Model / Auth

  • opencode agent list
  • opencode agent create
  • opencode auth login
  • opencode auth list
  • opencode auth logout
  • opencode models
  • opencode models anthropic
  • opencode models --refresh

MCP

  • opencode mcp add
  • opencode mcp list
  • opencode mcp auth [name]
  • opencode mcp auth list
  • opencode mcp logout [name]
  • opencode mcp debug <name>

GitHub / 运维

  • opencode github install
  • opencode github run
  • opencode upgrade
  • opencode uninstall

TUI 内常用能力

文件引用

在消息里用 @ 引文件：

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

直接跑 shell

以 ! 开头运行 shell 命令：

!ls -la

常用 slash commands

  • /connect：添加 provider
  • /compact：压缩上下文
  • /details：切换工具执行细节
  • /editor：外部编辑器
  • /help：帮助
  • /init：创建或更新 AGENTS.md
  • /models：列模型
  • /new / /clear：新会话
  • /sessions / /resume / /continue：切会话
  • /share / /unshare：分享会话
  • /themes：切主题
  • /thinking：显示/隐藏 reasoning
  • /undo / /redo：回滚 / 重做
  • /exit / /quit / /q：退出

配置文件

OpenCode 使用 JSON / JSONC 配置。

主要位置

配置按以下顺序合并，后者覆盖前者冲突字段：

  1. 远端组织配置 .well-known/opencode
  2. 全局配置 ~/.config/opencode/opencode.json
  3. OPENCODE_CONFIG
  4. 项目配置 opencode.json
  5. .opencode/ 目录里的 agents / commands / plugins
  6. OPENCODE_CONFIG_CONTENT

TUI 配置单独放：

  • ~/.config/opencode/tui.json
  • 项目下 tui.json
  • 也可用 OPENCODE_TUI_CONFIG

最小配置示例

{
  "$schema": "<https://opencode.ai/config.json>",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096
  }
}

常见配置项

  • model
  • small_model
  • provider
  • permission
  • mcp
  • agent
  • default_agent
  • command
  • formatter
  • share
  • plugins
  • instructions
  • enabled_providers
  • disabled_providers
  • compaction
  • watcher.ignore