个性化设置

目标：让 OpenCode 符合你的使用习惯

配置层级图

规则：后面的配置覆盖前面的配置。即项目配置 > 全局配置，环境变量 > 项目配置。

OpenCode 配置架构图

主题设置

OpenCode 支持多种主题，在 TUI 中按默认快捷键切换（通常是 Ctrl+T 或配置中设置）。

查看可用主题

/themes

或查看配置文件：

cat ~/.config/opencode/themes/

切换主题

在 opencode.json 中设置：

{
  "theme": "opencode"
}

内置主题：

主题	风格	适用场景
`opencode`	官方主题，深色	日常使用
`light`	浅色主题	明亮环境
`high-contrast`	高对比度	视力辅助

主题自定义代码

创建自定义主题文件：

mkdir -p ~/.config/opencode/themes
cat > ~/.config/opencode/themes/my-theme.json << 'EOF'
{
  "name": "my-theme",
  "type": "dark",
  "colors": {
    "background": "#1a1b26",
    "foreground": "#a9b1d6",
    "primary": "#7aa2f7",
    "secondary": "#bb9af7",
    "success": "#9ece6a",
    "warning": "#e0af68",
    "error": "#f7768e",
    "muted": "#565f89",
    "border": "#24283b"
  },
  "syntax": {
    "comment": "#565f89",
    "keyword": "#bb9af7",
    "string": "#9ece6a",
    "function": "#7aa2f7",
    "number": "#ff9e64"
  }
}
EOF

启用自定义主题：

// ~/.config/opencode/opencode.json
{
  "theme": "my-theme"
}

快捷键配置

快捷键配置文件位置：

~/.config/opencode/keybinds.json

查看当前快捷键

/keybinds

自定义示例

{
  "send": "ctrl+enter",
  "newLine": "enter",
  "toggleMode": "tab",
  "clear": "ctrl+l",
  "quit": "ctrl+q",
  "scrollUp": "pageup",
  "scrollDown": "pagedown",
  "top": "home",
  "bottom": "end"
}

常用可配置快捷键：

动作	默认	说明
`send`	Enter	发送消息
`newLine`	Shift+Enter	换行
`toggleMode`	Tab	切换计划/构建
`clear`	Ctrl+L	清屏
`quit`	Ctrl+C	退出
`scrollUp`	↑	向上滚动
`scrollDown`	↓	向下滚动

代码格式化工具

OpenCode 可以在编辑文件后自动运行格式化工具。

配置格式化

在 opencode.json 中：

{
  "formatters": {
    "*.ts": "prettier --write",
    "*.tsx": "prettier --write",
    "*.js": "prettier --write",
    "*.jsx": "prettier --write",
    "*.rs": "rustfmt",
    "*.py": "black",
    "*.go": "gofmt -w",
    "*.sh": "shfmt -w"
  }
}

格式化工具配置矩阵

语言	格式化工具	配置示例	安装方式
TypeScript	Prettier	`"*.ts": "prettier --write"`	`npm i -g prettier`
Python	Black	`"*.py": "black"`	`pip install black`
Go	gofmt	`"*.go": "gofmt -w"`	内置
Rust	rustfmt	`"*.rs": "rustfmt"`	`rustup component add rustfmt`
Shell	shfmt	`"*.sh": "shfmt -w"`	`brew install shfmt`
Lua	stylua	`"*.lua": "stylua"`	`cargo install stylua`

工作流程

AI 修改文件
OpenCode 自动检测文件类型
运行对应的格式化命令
显示格式化后的 diff

禁用格式化

{
  "formatters": false
}

按项目配置格式化

// ./opencode.json（项目级）
{
  "formatters": {
    "*.ts": "prettier --write --config .prettierrc",
    "*.py": "black --line-length 88"
  }
}

自定义命令

你可以创建自己的斜杠命令！

创建自定义命令

在项目或全局的 .opencode/commands/ 目录创建：

mkdir -p ~/.config/opencode/commands

示例 1：运行测试

创建文件 test.json：

{
  "name": "test",
  "description": "运行测试套件",
  "prompt": "运行项目的测试套件，报告结果。如果失败，分析失败原因并指出相关代码。"
}

使用：

/test

AI 会执行你定义的 prompt 中的内容。

示例 2：代码审查

{
  "name": "review",
  "description": "审查当前变更",
  "prompt": "请审查当前工作目录中未提交的 Git 变更（运行 git diff），关注：1) 潜在 Bug 2) 性能问题 3) 安全问题 4) 代码规范"
}

使用：

/review

示例 3：带参数的自定义命令

{
  "name": "lint",
  "description": "对指定文件运行 lint",
  "prompt": "对文件 {{file}} 运行 eslint，修复所有可自动修复的问题。报告剩余问题。"
}

使用：

/lint src/components/Button.tsx

示例 4：复杂自定义命令（多步骤）

{
  "name": "ship",
  "description": "准备代码提交：格式化、测试、生成 commit message",
  "prompt": "1. 运行格式化工具格式化所有修改的文件\n2. 运行测试套件\n3. 如果测试通过，运行 git diff --stat 查看变更概览\n4. 根据变更生成符合 Conventional Commits 规范的提交信息"
}

自定义命令完整示例

项目级自定义命令目录结构：

my-project/
├── .opencode/
│   └── commands/
│       ├── test.json
│       ├── review.json
│       ├── lint.json
│       └── ship.json
├── src/
└── opencode.json

全局自定义命令：

mkdir -p ~/.config/opencode/commands
 
# 通用测试命令
cat > ~/.config/opencode/commands/test.json << 'EOF'
{
  "name": "test",
  "description": "运行项目测试",
  "prompt": "检测项目类型并运行对应的测试命令（npm test / pytest / cargo test / go test 等），报告结果。"
}
EOF
 
# 安全扫描命令
cat > ~/.config/opencode/commands/security.json << 'EOF'
{
  "name": "security",
  "description": "扫描常见安全问题",
  "prompt": "扫描代码库中的常见安全问题：1) 硬编码密钥 2) SQL 注入风险 3) XSS 风险 4) 不安全的反序列化。列出发现的问题和修复建议。"
}
EOF
 
# 文档生成命令
cat > ~/.config/opencode/commands/docs.json << 'EOF'
{
  "name": "docs",
  "description": "生成函数文档",
  "prompt": "为项目中缺少文档的公共函数生成 JSDoc / docstring。保持与现有文档风格一致。"
}
EOF

配置优先级详解

OpenCode 的配置有多层，后面覆盖前面：

远程配置（组织默认）
全局配置 ~/.config/opencode/opencode.json
环境变量 OPENCODE_CONFIG
项目配置 ./opencode.json
.opencode/ 目录内容
内联配置 OPENCODE_CONFIG_CONTENT

建议：

个人偏好 → 全局配置
团队规范 → 项目配置
临时覆盖 → 环境变量

配置合并示例

// ~/.config/opencode/opencode.json（全局）
{
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "formatters": {
    "*.ts": "prettier --write"
  }
}

// ./opencode.json（项目级，覆盖全局）
{
  "theme": "light",
  "formatters": {
    "*.ts": "prettier --write --tab-width 4",
    "*.py": "black"
  }
}

最终生效配置：

theme: light（项目覆盖全局）
model: anthropic/claude-sonnet-4-5（继承全局）
formatters: 项目配置完全覆盖全局

环境变量临时覆盖

# 临时使用另一个模型
OPENCODE_MODEL=anthropic/claude-opus-4 opencode
 
# 临时禁用格式化
OPENCODE_FORMATTERS=false opencode

避坑清单

⚠️ 坑点	说明	解决方案
配置写错位置	全局和项目配置混淆	记住优先级规则，用 `--debug` 查看生效配置
格式化命令不存在	配置了 prettier 但没安装	确保工具已全局安装或在项目依赖中
自定义命令冲突	与内置命令同名	自定义命令会覆盖内置命令，避免冲突
主题 JSON 格式错误	颜色值写错导致崩溃	使用在线 JSON 验证器检查
快捷键绑定冲突	与终端快捷键冲突	测试后再保存，冲突时终端优先

常见问题

Q: 配置修改后需要重启吗？ A: 大部分配置需要重启 OpenCode 生效。部分运行时配置（如模型切换）可通过 /models 热切换。

Q: 自定义命令可以执行 shell 脚本吗？ A: 自定义命令通过 prompt 让 AI 执行操作，AI 会决定使用哪些工具。不能直接在 JSON 中写 shell 脚本。

Q: 团队如何共享配置？ A: 将 opencode.json 和 .opencode/ 目录提交到 Git，团队成员拉取后自动生效。

Q: 如何查看当前生效的配置？ A: 运行 opencode --show-config 或查看日志输出。

真实场景案例

案例 1：团队统一的代码风格

场景：团队 8 人使用 OpenCode，需要统一的格式化规则和自定义命令。

项目配置 opencode.json：

{
  "formatters": {
    "*.ts": "prettier --write --config .prettierrc",
    "*.tsx": "prettier --write --config .prettierrc"
  },
  "commands": {
    "test": {
      "description": "运行测试",
      "prompt": "运行 npm test，如果失败分析原因"
    },
    "ci-check": {
      "description": "CI 前置检查",
      "prompt": "1. 运行 prettier 检查\n2. 运行 eslint\n3. 运行 npm test\n4. 报告所有问题"
    }
  }
}

提交到 Git 后，所有团队成员自动获得相同配置。

案例 2：个人效率工具箱

场景：个人开发者想要快速执行常用操作。