CLI 设置仅控制终端客户端。它们与
opencode.json(c) 中的服务器和项目设置相互独立。按下
Ctrl+P，然后选择 Open settings，即可在 TUI 中修改常用设置。
配置文件
OpenCode 将 CLI 设置存储在一个全局文件中：
~/.config/opencode/cli.json
当设置了
$XDG_CONFIG_HOME 时，OpenCode 使用：$XDG_CONFIG_HOME/opencode/cli.json
不存在项目本地的 CLI 设置文件。可添加已发布的 JSON Schema 以获得校验与自动补全：
{
"$schema": "https://opencode.ai/v2/cli.json"
}
OpenCode 在创建或迁移该文件时会写入
$schema。有效的编辑会在 TUI 运行期间重新加载。未知设置会被忽略。保留
$schema，以便编辑器标记无效值。内联配置
设置
OPENCODE_CLI_CONFIG_CONTENT，即可通过内联 JSON 应用 CLI 设置：OPENCODE_CLI_CONFIG_CONTENT='{"tabs":{"mode":"off"}}' opencode
OpenCode 会将内联设置合并到全局
cli.json 之上。嵌套对象会被合并，而来自环境变量的数组和标量值会替换全局值。只要该变量被设置，内联设置始终优先。外观
选择主题、控制界面动效，并覆盖终端光标：
{
"theme": {
"name": "tokyonight",
"mode": "system"
},
"animations": true,
"cursor": {
"style": "block",
"blinking": true
}
}
| 设置 | 取值 | 说明 |
| --------------- | --------------------------------------- | -------------------------------------------------------- |
|
theme.name | string | 选择内置、自定义或从终端派生的主题。 |
| theme.mode | system、dark 或 light | 跟随终端外观，或将主题锁定为某一种颜色模式。 |
| animations | boolean | 启用界面动画。 |
| cursor.style | block、underline、line、default | 设置光标形状。default 保留终端的光标形状。 |
| cursor.blinking | boolean | 控制光标闪烁。当样式为 default 时无效。 |有关选择和创建主题，参见主题。
输入
配置鼠标捕获、滚动、编辑器上下文、粘贴以及提示输入的图片预览：
{
"mouse": true,
"scroll": {
"speed": 3,
"acceleration": false
},
"prompt": {
"editor": true,
"paste": "compact",
"image_preview": false
}
}
| 设置 | 取值 | 说明 |
| -------------------- | --------------------------- | -------------------------------------------------- |
|
mouse | boolean | 启用终端鼠标捕获。 |
| scroll.speed | number，至少 0.001 | 设置每次滚动输入的固定距离。 |
| scroll.acceleration | boolean | 加速连续滚动。启用时优先于 speed。 |
| prompt.editor | boolean | 将编辑器中当前活动的文件或选区作为提示上下文包含。 |
| prompt.paste | compact 或 full | 将大量粘贴内容显示为紧凑占位符或完整文本。 |
| prompt.image_preview | boolean | 在提示输入框上方显示图片附件预览。 |会话
配置全屏 TUI 会话的呈现方式以及新会话的起始位置：
{
"session": {
"sidebar": "auto",
"scrollbar": false,
"thinking": "hide",
"grouping": "auto",
"image_preview": false,
"tps": true,
"markdown": "rendered",
"new_location": "launch",
"permissions": "prompt"
}
}
| 设置 | 取值 | 说明 |
| --------------------- | ----------------------- | ------------------------------------------------ |
|
session.sidebar | auto 或 hide | 空间允许时显示侧边栏，或始终隐藏。 |
| session.scrollbar | boolean | 显示会话记录滚动条。 |
| session.thinking | show 或 hide | 默认显示或隐藏模型推理过程。 |
| session.grouping | auto 或 none | 将相关的会话记录条目分组，或分别渲染每个条目。 |
| session.image_preview | boolean | 在会话记录中显示用户附件和工具结果中的图片。 |
| session.tps | boolean | 在助手回复页脚显示每秒输出 token 数。 |
| session.markdown | source 或 rendered | 显示 Markdown 语法标记，或在渲染内容中隐藏它们。 |
| session.new_location | launch 或 inherit | 从 TUI 启动目录开始，或继承当前会话的位置。 |
| session.permissions | prompt 或 autoaccept | 对权限请求进行提示，或自动接受每个请求。 |标签页
配置持久化会话标签栏：
{
"tabs": {
"mode": "auto",
"scope": "cwd",
"layout": "horizontal",
"indicators": "status"
}
}
旧版布尔值设置
tabs.enabled 仍受支持：true 等同于 on，false 等同于 off。OpenCode 会读取它，但不会重写配置文件。| 设置 | 取值 | 说明 |
| ----------------- | --------------------------- | ------------------------------------------ |
|
tabs.mode | auto、on 或 off | 自动、始终或从不使用标签页。Auto 模式下会在 Herdr 内隐藏它们。 |
| tabs.scope | cwd 或 global | 按工作目录分别保留标签页，或全局共享。 |
| tabs.layout | horizontal 或 vertical | 将标签页放置在水平条或垂直侧边栏中。 |
| tabs.indicators | status 或 numbers | 显示状态图标，或始终显示标签页编号。 |数字指示器会保留状态颜色和背景动画。在任一指示器模式下，Ctrl+数字快捷键都可切换标签页。
差异
配置初始差异范围与呈现方式：
{
"diffs": {
"source": "branch",
"wrap": "word",
"tree": true,
"single": false,
"view": "auto"
}
}
| 设置 | 取值 | 说明 |
| -------------- | ------------------------------------------- | ---------------------------------------- |
|
diffs.source | branch、committed、working 或 turn | 设置初始审查范围。 |
| diffs.wrap | word 或 none | 按单词换行长行，或不换行。 |
| diffs.tree | boolean | 显示差异文件树。 |
| diffs.single | boolean | 仅显示所选文件的补丁。 |
| diffs.view | auto、split 或 unified | 设置布局。auto 根据可用宽度选择。 |branch 显示 All 的分支与本地更改，committed 仅显示分支提交，working 显示已暂存、未暂存和未跟踪的更改。turn 显示 Last turn，即会话在最新一轮中更改的文件；当会话完成一轮时它会刷新，若 /diff 并非从会话中打开则回退到 branch。在
/diff 中，按 d 可更改范围，或从 Base 选择比较分支。这些视图内的选择会持续到 TUI 退出为止，且不会修改 cli.json。提醒
可分别启用系统通知与提示音：
{
"attention": {
"notifications": true,
"sound": true,
"volume": 0.4,
"sound_pack": "opencode.default",
"sounds": {
"permission": "/home/me/sounds/permission.wav"
}
}
}
| 设置 | 取值 | 说明 |
| ------------------------ | -------------------- | -------------------------------------------------------------------------- |
|
attention.notifications | boolean | 显示系统通知，通常在终端未获得焦点时。 |
| attention.sound | boolean | 播放提示音。 |
| attention.volume | 0 到 1 的数字 | 设置音量。 |
| attention.sound_pack | string | 选择当前生效的音效包 ID。 |
| attention.sounds | object | 覆盖 default、question、permission、error、done 或 subagent_done 的音效文件。 |无效或不可读的覆盖文件会回退到该事件的内置音效。
更新后，TUI 会在主屏幕上一次性展示新版本的亮点。运行
/highlights 可再次查看，或关闭该对话框：{
"highlights": false
}
终端
配置终端集成：
{
"terminal": {
"title": true,
"copy": "select"
}
}
| 设置 | 取值 | 说明 |
| ---------------- | -------------------- | ---------------------------------------------------------------------------------------- |
|
terminal.title | boolean | 更新终端窗口标题。 |
| terminal.copy | manual 或 select | 手动复制，或在选中后立即复制。平台默认值：Windows 上为 manual，其他平台为 select。 |Mini
mini 设置组控制 opencode mini，即极简交互界面：{
"mini": {
"thinking": "show",
"tools": "hide",
"shell_output": "hide",
"turn_summary": "show",
"footer": "show",
"splash": "show",
"work_spinner": "block-soft-slide",
"mono": false,
"replay": true,
"replay_limit": 200
}
}
| 设置 | 取值 | 说明 |
| ------------------- | ------------------------ | ------------------------------------------------------------ |
|
mini.thinking | show 或 hide | 显示或隐藏模型推理过程。 |
| mini.tools | show 或 hide | 显示或隐藏工具调用及其之前的助手文本。 |
| mini.shell_output | show 或 hide | 显示或隐藏 shell 工具的原始输出。 |
| mini.turn_summary | show 或 hide | 在回滚记录中显示或隐藏智能体、模型和耗时摘要。 |
| mini.footer | show 或 hide | 显示或隐藏常驻的活动、模型、用量和上下文详情。 |
| mini.splash | show 或 hide | 显示或隐藏进入和退出时的启动画面。 |
| mini.work_spinner | spinner ID | 选择页脚中的工作动画。 |
| mini.mono | boolean | 使用单色 ASCII 输出。 |
| mini.replay | boolean | 在恢复会话和终端尺寸变化时重建会话历史。 |
| mini.replay_limit | 正整数 | 将回放限制为最新的消息。默认上限为 200。 |可用的 spinner ID 如下：
block-soft-slide block-soft-sweep block-low-comet block-low-duet
block-shuttle block-bridge block-squeeze small-toggle
square-toggle grow-shrink quadrant-orbit crosshatch
density-wave seed
命令行
mini 回放相关 flag 会在该次调用中覆盖这些设置。快捷键
覆盖命令绑定以及 leader 键超时时间：
{
"keybinds": {
"leader": "ctrl+x",
"app.exit": ["ctrl+c", "ctrl+d", "<leader>q"],
"prompt.paste": {
"key": "ctrl+v",
"event": "press",
"preventDefault": false,
"fallthrough": false
},
"help.show": false
},
"leader": {
"timeout": 2000
}
}
| 设置 | 取值 | 说明 |
| --------------------------- | --------------------------------------- | ------------------------------------------------ |
|
keybinds.leader | 绑定值 | 设置其他绑定中 <leader> 所引用的按键。 |
| keybinds.<command> | 绑定值 | 覆盖某个命令 ID 的绑定。 |
| keybinds.*.key | 按键字符串或描述符 | 为对象绑定选择按键。 |
| keybinds.*.event | press 或 release | 将对象绑定限定为某一种按键事件。 |
| keybinds.*.preventDefault | boolean | 控制是否阻止终端的默认按键行为。 |
| keybinds.*.fallthrough | boolean | 允许优先级更低的处理程序接收同一事件。 |
| leader.timeout | 正整数 | 设置在 leader 键之后等待的毫秒数。 |插件
按顺序加载仅限终端的插件：
{
"plugins": [
"-opencode.notifications",
{
"package": "./plugins/status",
"options": {
"compact": true
}
}
]
}
| 设置 | 取值 | 说明 |
| ------------------ | ------- | -------------------------------------- |
|
plugins | array | 声明有序的启用指令与外部插件。 |
| plugins[].package | string | 设置包名、本地路径或文件 URL。 |
| plugins[].options | object | 向该插件传递插件特定的选项。 |有关包的形式、本地发现、通配符和禁用指令，参见插件。
调试与实验性功能
启用诊断功能，或选择加入当前可用的实验特性：
{
"debug": {
"devtools": false,
"timing": false,
"turn_tokens": "verbose"
},
"experimental": {}
}
| 设置 | 取值 | 说明 |
| ------------------- | --------------------------------- | ---------------------------------------------------------------- |
|
debug.devtools | boolean | 显示 DevTools 调试栏。 |
| debug.timing | boolean | 在调试栏中显示首次绘制耗时诊断。 |
| debug.turn_tokens | boolean 或 verbose | 显示每轮的 token 用量；verbose 还会包含工具调用输入。 |
| experimental | 特性 ID 到布尔值的对象 | 启用或禁用可能变更或在无通知情况下移除的实验特性。 |仅使用 TUI Experiments 对话框中当前列出的特性 ID。未知 ID 不会产生任何效果。