OpenCode 完全使用指南：开源 AI 编程助手入门到精通

AI2天前发布 beixibaobao

1 0 0

OpenCode 完全使用指南：开源 AI 编程助手入门到精通

本教程基于 OpenCode 官方文档（https://opencode.ai/docs）和 GitHub 仓库（https://github.com/anomalyco/opencode）编写，适合零基础新手入门。

📚 目录

什么是 OpenCode
安装指南
快速开始
配置文件详解
Provider 配置
TUI 终端界面使用
Agent 系统
自定义命令
快捷键配置
MCP 服务器
LSP 语言服务器
主题与个性化
Rules 自定义指令
最佳实践与进阶技巧
常见问题解答

1. 什么是 OpenCode

1.1 概述

OpenCode 是一个 100% 开源的 AI 编程代理（Coding Agent），提供终端界面（TUI）、桌面应用和 IDE 扩展多种使用方式。它可以帮助开发者：

🤖 与 AI 对话编写代码
📝 分析和理解代码库
🔧 自动修改和重构代码
🐛 调试和修复问题
📚 生成文档和测试

1.2 核心特点

特点	说明
100% 开源	MIT 许可证，代码完全开放
多 Provider 支持	支持 Claude、OpenAI、Google、本地模型等 75+ 提供商
开箱即用的 LSP	内置语言服务器支持，提供智能诊断
TUI 优先设计	由 Neovim 用户打造，极致终端体验
客户端/服务器架构	支持远程控制，可从手机驱动桌面上的 OpenCode
MCP 协议支持	可扩展外部工具和服务

1.3 与 Claude Code 的区别

对比项	OpenCode	Claude Code
开源性	✅ 100% 开源	❌ 闭源
Provider	✅ 不绑定任何提供商	❌ 仅限 Anthropic (但可以改配置用三方)
LSP 支持	✅ 开箱即用	❌ 无
扩展性	✅ 插件/MCP/自定义工具	有限

2. 安装指南

2.1 前置要求

现代终端模拟器（推荐）：
- WezTerm – 跨平台
- Alacritty – 跨平台
- Ghostty – Linux/macOS
- Kitty – Linux/macOS
- Windows Terminal – Windows
LLM Provider 的 API 密钥（至少需要一个）

2.2 通用安装（推荐）

最简单的安装方式，适用于 macOS 和 Linux：

curl -fsSL https://opencode.ai/install | bash

2.3 macOS 安装

使用 Homebrew（推荐）

# 官方 tap（更新更快）
brew install anomalyco/tap/opencode
# 或者使用官方 formula（更新较慢）
brew install opencode

2.4 Linux 安装

Debian/Ubuntu

# 使用 npm
npm install -g opencode-ai
# 或使用安装脚本
curl -fsSL https://opencode.ai/install | bash

Arch Linux

paru -S opencode-bin

2.5 Windows 安装

使用 Chocolatey

choco install opencode

使用 Scoop

scoop install opencode

使用 npm

npm install -g opencode-ai

2.6 使用包管理器

npm / Bun / pnpm / Yarn

# npm
npm install -g opencode-ai
# Bun
bun install -g opencode-ai
# pnpm
pnpm install -g opencode-ai
# Yarn
yarn global add opencode-ai

2.7 使用 Docker

docker run -it --rm ghcr.io/anomalyco/opencode

2.8 使用 Nix

# 使用 nixpkgs
nix run nixpkgs#opencode
# 使用最新开发版
nix run github:anomalyco/opencode

2.9 桌面应用（Beta）

OpenCode 还提供桌面应用程序，可从 Releases 页面或 opencode.ai/download 下载。

平台	下载文件
macOS (Apple Silicon)	`opencode-desktop-darwin-aarch64.dmg`
macOS (Intel)	`opencode-desktop-darwin-x64.dmg`
Windows	`opencode-desktop-windows-x64.exe`
Linux	`.deb`, `.rpm`, 或 AppImage

# macOS 使用 Homebrew
brew install --cask opencode-desktop
# Windows 使用 Scoop
scoop bucket add extras
scoop install extras/opencode-desktop

2.10 自定义安装目录

安装脚本支持以下优先级顺序的安装路径：

$OPENCODE_INSTALL_DIR – 自定义安装目录
$XDG_BIN_DIR – XDG 规范路径
$HOME/bin – 标准用户目录
$HOME/.opencode/bin – 默认回退

# 自定义安装目录示例
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

3. 快速开始

3.1 首次配置 Provider

cd /path/to/your/project

启动 OpenCode：

opencode

配置 Provider（以 OpenCode Zen 为例）：

/connect

选择 opencode，然后访问 opencode.ai/auth 获取 API 密钥
粘贴你的 API 密钥

3.2 初始化项目

运行初始化命令，让 OpenCode 分析你的项目：

/init

这会创建一个 AGENTS.md 文件，帮助 OpenCode 更好地理解你的项目结构。

💡 提示：建议将 AGENTS.md 提交到 Git 仓库

3.3 基础使用示例

询问代码问题

给我简单介绍一下这个代码库

引用文件

使用 @ 符号引用项目中的文件：

@src/components/Button.tsx 这个组件是如何工作的？

添加新功能

请在 @src/api/auth.ts 中添加用户登录功能

执行 Shell 命令

使用 ! 前缀执行命令：

!npm test

3.4 Plan 与 Build 模式

OpenCode 提供两种主要模式，使用 Tab 键切换：

模式	说明	适用场景
Build	完整权限，可修改文件	实际开发工作
Plan	只读模式，只分析不修改	代码审查、规划方案

# 先用 Plan 模式规划
<Tab 切换到 Plan>
实现一个用户删除功能，要求软删除，并提供恢复界面
# 确认方案后切换到 Build 模式执行
<Tab 切换到 Build>
按照刚才的计划开始实现

3.5 撤销与重做

/undo   # 撤销上一个操作（包括文件修改）
/redo   # 重做已撤销的操作

⚠️ 注意：撤销/重做功能需要项目是 Git 仓库

4. 配置文件详解

4.1 配置文件格式

OpenCode 支持 JSON 和 JSONC（带注释的 JSON）格式：

{
  "$schema": "https://opencode.ai/config.json",
  // 主题配置
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

4.2 配置文件位置

配置文件按以下优先级加载（后面的覆盖前面的）：

优先级	位置	说明
1	`.well-known/opencode`	远程组织配置
2	`~/.config/opencode/opencode.json`	全局用户配置
3	`OPENCODE_CONFIG` 环境变量	自定义配置路径
4	项目根目录 `opencode.json`	项目专属配置
5	`.opencode` 目录	agents、commands 等
6	`OPENCODE_CONFIG_CONTENT` 环境变量	运行时覆盖

4.3 完整配置示例

{
  "$schema": "https://opencode.ai/config.json",
  // 主题设置
  "theme": "tokyonight",
  // 模型设置
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  // 自动更新
  "autoupdate": true,
  // TUI 设置
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  },
  // 服务器设置
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true
  },
  // 工具权限
  "permission": {
    "edit": "allow",
    "bash": "ask"
  },
  // 自动压缩
  "compaction": {
    "auto": true,
    "prune": true
  },
  // 指令文件
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md"
  ]
}

4.4 变量替换

环境变量

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

文件内容

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

5. Provider 配置

5.1 支持的 Provider

OpenCode 支持 75+ LLM 提供商，以下是常用的：

Provider	说明
OpenCode Zen	官方推荐，经过验证的模型列表
Anthropic	Claude 系列模型
OpenAI	GPT 系列模型
Google Vertex AI	Gemini 系列
Amazon Bedrock	AWS 托管的多种模型
OpenRouter	聚合多个提供商
Ollama	本地运行模型
LM Studio	本地模型管理
DeepSeek	DeepSeek 模型
Groq	高速推理

5.2 配置 Anthropic

使用 Claude Pro/Max 订阅

/connect

选择 Anthropic → Claude Pro/Max，浏览器会自动打开进行认证。

使用 API 密钥

/connect

选择 Anthropic → Manually enter API Key，然后输入密钥。

5.3 配置 OpenAI

使用 ChatGPT Plus/Pro 订阅

/connect

选择 OpenAI → ChatGPT Plus/Pro，浏览器会自动打开进行认证。

5.4 配置 OpenCode Zen（推荐新手）

OpenCode Zen 是官方提供的经过测试验证的模型列表：

访问 opencode.ai/auth 创建 API 密钥
运行 /connect，选择 opencode
粘贴 API 密钥
运行 /models 查看可用模型

5.5 配置本地模型（Ollama）

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        },
        "codellama": {
          "name": "Code Llama"
        }
      }
    }
  }
}

💡 提示：如果工具调用不工作，尝试在 Ollama 中增加 num_ctx 到 16k-32k

5.6 配置 LM Studio

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "google/gemma-3n-e4b": {
          "name": "Gemma 3n-e4b (local)"
        }
      }
    }
  }
}

5.7 配置 Amazon Bedrock

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile"
      }
    }
  }
}

或使用环境变量：

# 使用 AWS 访问密钥
AWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY opencode
# 使用命名配置文件
AWS_PROFILE=my-profile opencode

5.8 配置 OpenRouter

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "moonshotai/kimi-k2": {
          "options": {
            "provider": {
              "order": ["baseten"],
              "allow_fallbacks": false
            }
          }
        }
      }
    }
  }
}

5.9 禁用/启用特定 Provider

{
  "$schema": "https://opencode.ai/config.json",
  // 禁用特定 provider
  "disabled_providers": ["openai", "gemini"],
  // 或只启用特定 provider
  "enabled_providers": ["anthropic", "opencode"]
}

6. TUI 终端界面使用

6.1 启动 TUI

# 当前目录
opencode
# 指定目录
opencode /path/to/project

6.2 基本操作

发送消息

直接输入文字后按 Enter 发送。

换行输入

Shift+Enter – 插入换行
Ctrl+Enter – 插入换行
Alt+Enter – 插入换行

引用文件

输入 @ 然后模糊搜索文件名：

@src/api/  → 选择文件

执行 Shell 命令

以 ! 开头：

!git status
!npm run build

6.3 内置命令

命令	快捷键	说明
`/connect`	–	添加 Provider
`/models`	`Ctrl+x m`	选择模型
`/new`	`Ctrl+x n`	新建会话
`/sessions`	`Ctrl+x l`	会话列表
`/undo`	`Ctrl+x u`	撤销操作
`/redo`	`Ctrl+x r`	重做操作
`/compact`	`Ctrl+x c`	压缩上下文
`/share`	`Ctrl+x s`	分享会话
`/init`	`Ctrl+x i`	初始化项目
`/theme`	`Ctrl+x t`	选择主题
`/editor`	`Ctrl+x e`	打开外部编辑器
`/export`	`Ctrl+x x`	导出会话为 Markdown
`/help`	`Ctrl+x h`	显示帮助
`/exit`	`Ctrl+x q`	退出
`/details`	`Ctrl+x d`	切换工具执行详情
`/thinking`	–	切换思考过程显示

6.4 导航操作

操作	快捷键
向上滚动一页	`PageUp` / `Ctrl+Alt+b`
向下滚动一页	`PageDown` / `Ctrl+Alt+f`
向上滚动半页	`Ctrl+Alt+u`
向下滚动半页	`Ctrl+Alt+d`
跳到顶部	`Ctrl+g` / `Home`
跳到底部	`Ctrl+Alt+g` / `End`
切换 Agent	`Tab`
反向切换 Agent	`Shift+Tab`
中断响应	`Escape`

6.5 编辑器设置

配置 EDITOR 环境变量以使用 /editor 和 /export 命令：

# Linux/macOS - 添加到 ~/.bashrc 或 ~/.zshrc
export EDITOR="code --wait"  # VS Code
export EDITOR=vim            # Vim
export EDITOR=nvim           # Neovim

# Windows PowerShell
$env:EDITOR = "code --wait"

⚠️ 注意：VS Code 等 GUI 编辑器需要 --wait 参数

7. Agent 系统

7.1 Agent 类型

主 Agent（Primary）

直接交互的主要 Agent，使用 Tab 键切换：

Agent	说明
Build	默认 Agent，完整权限
Plan	只读模式，用于分析和规划

子 Agent（Subagent）

由主 Agent 调用或使用 @ 手动调用：

Agent	说明
General	通用 Agent，适合复杂任务
Explore	快速只读探索代码库

7.2 使用 Agent

切换主 Agent

按 Tab 键在 Build 和 Plan 之间切换。

调用子 Agent

使用 @ 提及：

@general 帮我搜索这个函数的所有调用位置
@explore 分析一下项目结构

7.3 自定义 Agent

JSON 配置方式

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "代码审查专家",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一个代码审查专家，专注于安全性、性能和可维护性。",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown 文件方式

创建 .opencode/agents/reviewer.md 或 ~/.config/opencode/agents/reviewer.md：

---
description: 代码审查专家
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
你是一个代码审查专家。请关注：
- 代码质量和最佳实践
- 潜在的 bug 和边界情况
- 性能影响
- 安全考虑
提供建设性的反馈，不要直接修改代码。

7.4 Agent 配置选项

选项	类型	说明
`description`	string	Agent 描述（必需）
`mode`	string	`primary`、`subagent` 或 `all`
`model`	string	使用的模型
`prompt`	string	系统提示词
`temperature`	number	创造性（0-1）
`maxSteps`	number	最大迭代次数
`tools`	object	工具权限
`permission`	object	详细权限配置
`hidden`	boolean	从 @ 菜单隐藏
`disable`	boolean	禁用此 Agent

7.5 Agent 权限配置

{
  "agent": {
    "safe-build": {
      "mode": "primary",
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git diff *": "allow"
        }
      }
    }
  }
}

8. 自定义命令

8.1 创建命令

JSON 配置方式

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "运行完整的测试套件并显示覆盖率报告。n关注失败的测试并提供修复建议。",
      "description": "运行测试并分析结果",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "创建一个名为 $ARGUMENTS 的 React 组件。n包含 TypeScript 类型定义和基本结构。",
      "description": "创建新组件"
    }
  }
}

Markdown 文件方式

创建 .opencode/commands/test.md：

---
description: 运行测试并分析覆盖率
agent: build
model: anthropic/claude-haiku-4-5
---
运行完整的测试套件并显示覆盖率报告。
关注失败的测试并提供修复建议。

8.2 使用命令

/test
/component Button

8.3 命令模板语法

参数替换

$ARGUMENTS – 所有参数
$1, $2, $3 – 位置参数

---
description: 创建文件
---
在目录 $2 中创建名为 $1 的文件，内容为：$3

使用：

/create-file config.json src "{ "key": "value" }"

Shell 命令输出

使用 !`command` 语法：

---
description: 分析测试覆盖率
---
当前测试结果：
!`npm test`
基于这些结果，建议如何提高覆盖率。

文件引用

---
description: 审查组件
---
审查 @src/components/Button.tsx 组件，检查性能问题并提供改进建议。

8.4 命令选项

选项	说明
`template`	命令模板（必需）
`description`	命令描述
`agent`	执行的 Agent
`model`	使用的模型
`subtask`	是否作为子任务执行

9. 快捷键配置

9.1 Leader 键

OpenCode 使用 Leader 键避免与终端快捷键冲突。默认 Leader 键是 Ctrl+x。

例如，新建会话：先按 Ctrl+x，再按 n。

9.2 自定义快捷键

{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": {
    "leader": "ctrl+x",
    "app_exit": "ctrl+c,ctrl+d,<leader>q",
    "session_new": "<leader>n",
    "session_list": "<leader>l",
    "model_list": "<leader>m",
    "agent_cycle": "tab",
    "input_submit": "return",
    "input_newline": "shift+return,ctrl+return",
    "session_interrupt": "escape"
  }
}

9.3 禁用快捷键

设置为 "none" 禁用：

{
  "keybinds": {
    "session_compact": "none"
  }
}

9.4 完整快捷键列表

功能	默认快捷键
退出	`Ctrl+c`, `Ctrl+d`, `<leader>q`
打开编辑器	`<leader>e`
主题列表	`<leader>t`
侧边栏切换	`<leader>b`
状态视图	`<leader>s`
导出会话	`<leader>x`
新建会话	`<leader>n`
会话列表	`<leader>l`
时间线	`<leader>g`
中断会话	`Escape`
压缩会话	`<leader>c`
向上翻页	`PageUp`, `Ctrl+Alt+b`
向下翻页	`PageDown`, `Ctrl+Alt+f`
复制消息	`<leader>y`
撤销	`<leader>u`
重做	`<leader>r`
模型列表	`<leader>m`
切换模型变体	`Ctrl+t`
命令列表	`Ctrl+p`
Agent 列表	`<leader>a`
切换 Agent	`Tab`
反向切换	`Shift+Tab`
清空输入	`Ctrl+c`
粘贴	`Ctrl+v`
提交	`Return`
换行	`Shift+Return`

10. MCP 服务器

10.1 什么是 MCP

Model Context Protocol (MCP) 是一种协议，允许 OpenCode 集成外部工具和服务。通过 MCP，你可以：

连接数据库
集成 API
使用第三方服务
扩展 AI 能力

10.2 配置本地 MCP 服务器

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "value"
      }
    }
  }
}

10.3 配置远程 MCP 服务器

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

10.4 常用 MCP 示例

Sentry（错误监控）

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

然后运行认证：

opencode mcp auth sentry

使用：

显示我项目中最新的未解决问题。use sentry

Context7（文档搜索）

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

使用：

如何配置 Cloudflare Worker 来缓存 JSON API 响应？use context7

Grep by Vercel（代码搜索）

{
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

使用：

搜索 React hooks 的最佳实践示例。use the gh_grep tool

10.5 OAuth 认证

对于需要认证的 MCP 服务器：

# 认证
opencode mcp auth my-oauth-server
# 查看状态
opencode mcp list
# 登出
opencode mcp logout my-oauth-server

10.6 MCP 权限管理

全局禁用

{
  "tools": {
    "my-mcp*": false
  }
}

按 Agent 启用

{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

11. LSP 语言服务器

11.1 内置 LSP 支持

OpenCode 内置多种语言的 LSP 服务器支持：

语言	LSP 服务器	要求
TypeScript/JavaScript	typescript	项目有 `typescript` 依赖
Python	pyright	安装 `pyright`
Rust	rust-analyzer	安装 `rust-analyzer`
Go	gopls	安装 `go`
Java	jdtls	Java SDK 21+
C/C++	clangd	自动安装
PHP	intelephense	自动安装
Ruby	ruby-lsp	安装 `ruby` 和 `gem`
Bash	bash-language-server	自动安装
Vue	vue-language-server	自动安装
Svelte	svelte-language-server	自动安装
Astro	@astrojs/language-server	自动安装
Lua	lua-language-server	自动安装
Kotlin	kotlin-language-server	自动安装
Swift	sourcekit-lsp	安装 Xcode
Zig	zls	安装 `zig`
Terraform	terraform-ls	自动安装
YAML	yaml-language-server	自动安装

11.2 LSP 如何工作

当 OpenCode 打开文件时：

检查文件扩展名
启动对应的 LSP 服务器
获取诊断信息（错误、警告）
将诊断反馈给 LLM

11.3 自定义 LSP 配置

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"]
    }
  }
}

11.4 禁用 LSP

禁用所有 LSP

{
  "lsp": false
}

禁用特定 LSP

{
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

11.5 禁用自动下载

export OPENCODE_DISABLE_LSP_DOWNLOAD=true

12. 主题与个性化

12.1 终端要求

为了正确显示主题，你的终端需要支持 truecolor（24位色）：

# 检查支持
echo $COLORTERM  # 应输出 truecolor 或 24bit
# 启用 truecolor
export COLORTERM=truecolor

12.2 内置主题

主题名	说明
`opencode`	默认主题
`system`	自动适应终端颜色
`tokyonight`	Tokyo Night 风格
`catppuccin`	Catppuccin 风格
`catppuccin-macchiato`	Catppuccin Macchiato
`gruvbox`	Gruvbox 风格
`nord`	Nord 风格
`kanagawa`	Kanagawa 风格
`everforest`	Everforest 风格
`ayu`	Ayu Dark 风格
`one-dark`	Atom One Dark
`matrix`	黑客风格绿色

12.3 切换主题

使用命令

/theme

配置文件

{
  "theme": "tokyonight"
}

12.4 自定义主题

创建 ~/.config/opencode/themes/my-theme.json 或 .opencode/themes/my-theme.json：

{
  "$schema": "https://opencode.ai/theme.json",
  "defs": {
    "bg": "#1a1b26",
    "fg": "#c0caf5",
    "accent": "#7aa2f7",
    "error": "#f7768e",
    "warning": "#e0af68",
    "success": "#9ece6a"
  },
  "theme": {
    "primary": {
      "dark": "accent",
      "light": "accent"
    },
    "text": {
      "dark": "fg",
      "light": "#1a1b26"
    },
    "background": {
      "dark": "bg",
      "light": "#ffffff"
    },
    "error": {
      "dark": "error",
      "light": "error"
    },
    "warning": {
      "dark": "warning",
      "light": "warning"
    },
    "success": {
      "dark": "success",
      "light": "success"
    }
  }
}

12.5 颜色格式

Hex 颜色: "#ffffff"
ANSI 颜色: 3（0-255）
引用定义: "primary"
深浅变体: {"dark": "#000", "light": "#fff"}
无颜色: "none"（使用终端默认）

13. Rules 自定义指令

13.1 什么是 AGENTS.md

AGENTS.md 是一个特殊文件，包含给 LLM 的自定义指令，类似于 Cursor 的 rules。它帮助 OpenCode 理解你的项目结构和编码规范。

13.2 创建 AGENTS.md

自动生成

/init

这会扫描项目并自动生成 AGENTS.md。

手动创建

# 我的 TypeScript 项目
这是一个使用 bun workspaces 的 SST v3 monorepo 项目。
## 项目结构
- `packages/` - 所有工作区包（functions, core, web 等）
- `infra/` - 基础设施定义（storage.ts, api.ts, web.ts）
- `sst.config.ts` - 主 SST 配置
## 代码规范
- 使用 TypeScript 严格模式
- 共享代码放在 `packages/core/`
- 函数代码放在 `packages/functions/`
- 基础设施按逻辑拆分到 `infra/` 目录
## Monorepo 约定
- 使用工作区名称导入共享模块：`@my-app/core/example`

13.3 文件位置

类型	位置	作用域
项目级	项目根目录 `AGENTS.md`	仅当前项目
全局级	`~/.config/opencode/AGENTS.md`	所有项目

13.4 Claude Code 兼容性

OpenCode 支持 Claude Code 的文件约定作为回退：

CLAUDE.md → 用作 AGENTS.md
~/.claude/CLAUDE.md → 用作全局指令

禁用兼容性：

export OPENCODE_DISABLE_CLAUDE_CODE=1

13.5 引用外部文件

使用配置文件

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md",
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

在 AGENTS.md 中引用

# 项目规则
## 外部文件加载
重要：当遇到文件引用（如 @rules/general.md）时，使用 Read 工具按需加载。
## 开发指南
TypeScript 代码风格：@docs/typescript-guidelines.md
React 组件架构：@docs/react-patterns.md
API 设计规范：@docs/api-standards.md

14. 最佳实践与进阶技巧

14.1 高效工作流

1. 先规划后执行

<Tab 切换到 Plan 模式>
我需要实现用户认证功能，包括登录、注册、密码重置
<分析完成后>
<Tab 切换到 Build 模式>
按照计划开始实现

2. 使用 @ 引用上下文

参考 @src/auth/login.ts 的实现方式，在 @src/auth/register.ts 中添加注册功能

3. 拖放图片

在终端中拖放图片，可以让 LLM 参考设计稿：

按照这个设计稿实现登录界面
[拖入设计稿图片]

14.2 项目设置建议

创建项目专属配置

// opencode.json（放在项目根目录）
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/DEVELOPMENT.md"
  ],
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"]
    }
  }
}

设置完善的 AGENTS.md

# 项目名称
## 技术栈
- 前端：React + TypeScript + Tailwind
- 后端：Node.js + Express
- 数据库：PostgreSQL
## 目录结构
...
## 编码规范
...
## 常见任务
- 创建新组件：使用 `packages/ui` 目录
- 添加 API：在 `packages/api/src/routes` 创建

14.3 性能优化

1. 使用 small_model

为轻量任务（如生成标题）配置更便宜的模型：

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

2. 启用自动压缩

{
  "compaction": {
    "auto": true,
    "prune": true
  }
}

3. 合理配置 MCP

避免添加太多 MCP 服务器，每个都会增加上下文：

{
  "tools": {
    "heavy-mcp*": false
  }
}

14.4 团队协作

1. 共享配置

将以下文件提交到 Git：

opencode.json
AGENTS.md
.opencode/ 目录

2. 分享会话

/share

获取可分享的链接。

14.5 安全最佳实践

1. 使用权限控制

{
  "permission": {
    "bash": "ask",
    "edit": "allow"
  }
}

2. 敏感命令需要确认

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "allow",
          "rm *": "ask",
          "git push*": "ask",
          "npm publish": "ask"
        }
      }
    }
  }
}

14.6 调试技巧

1. 查看工具执行详情

/details

2. 查看思考过程

/thinking

3. 导出会话进行分析

/export

15. 常见问题解答

Q1: 如何更换模型？

/models

或在配置文件中设置：

{
  "model": "openai/gpt-4o"
}

Q2: Shift+Enter 不工作怎么办？

某些终端需要特殊配置。Windows Terminal 用户需在 settings.json 中添加：

{
  "actions": [
    {
      "command": {
        "action": "sendInput",
        "input": "u001b[13;2u"
      },
      "id": "User.sendInput.ShiftEnterCustom"
    }
  ],
  "keybindings": [
    {
      "keys": "shift+enter",
      "id": "User.sendInput.ShiftEnterCustom"
    }
  ]
}

Q3: 如何使用本地模型？

配置 Ollama 或 LM Studio：

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": { "name": "Llama 2" }
      }
    }
  }
}

Q4: 撤销操作不工作？

确保项目是 Git 仓库。撤销功能依赖 Git 来恢复文件更改。

Q5: 如何禁用自动更新？

{
  "autoupdate": false
}

或只通知不更新：

{
  "autoupdate": "notify"
}

Q6: API 密钥存储在哪里？

~/.local/share/opencode/auth.json

Q7: 如何完全重置 OpenCode？

# 删除配置
rm -rf ~/.config/opencode
# 删除数据
rm -rf ~/.local/share/opencode

Q8: 遇到 “content filter” 错误（Azure）？

将 Azure 资源的内容过滤器从 DefaultV2 改为 Default。

Q9: 如何查看可用的 Provider？

/connect

然后搜索或滚动查看所有可用的 Provider。

Q10: 如何使用代理？

设置环境变量：

export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080

📖 更多资源

官方文档: https://opencode.ai/docs
GitHub 仓库: https://github.com/anomalyco/opencode

本教程由 Sisyphus AI 助手编写，人工审核，参考 OpenCode 官方文档。如有问题或建议，欢迎反馈！

AI # kimi

文章版权归作者所有，未经允许请勿转载。

【AIGC】COT思维链：让AI学会拆解问题，像人一样思考

AI # Langchain

1周前

如何利用AI Coding提效？从工具到思维的全面升级

2周前

【超音速专利 CN118134841A】一种光伏产品缺陷检测AI深度学习算法

1周前

Tavo语音TTS功能设置教程:让AI角色真正“开口说话“!

3天前