OpenCode 开源 AI 编程助手：从安装到高级配置实战

快速开始

首次配置 Provider

进入项目目录后启动 OpenCode，通过 /connect 命令连接服务。以 OpenCode Zen 为例，访问授权页面获取 API 密钥并粘贴即可。

初始化项目

运行 /init 命令，OpenCode 会分析项目结构并创建 AGENTS.md 文件，帮助其更好地理解上下文。建议将此文件提交到 Git 仓库。

基础交互示例

• 询问代码：直接输入自然语言问题。
• 引用文件：使用 @ 符号搜索并引用项目文件，例如 @src/components/Button.tsx。
• 添加功能：指定文件范围，如 请在 @src/api/auth.ts 中添加用户登录功能。
• 执行 Shell 命令：以 ! 前缀执行，如 !npm test。

Plan 与 Build 模式

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

建议先用 Plan 模式确认方案，再切换到 Build 模式执行。

撤销与重做

使用 /undo 和 /redo 命令回滚操作。注意：此功能依赖 Git 仓库环境。

配置文件详解

格式与位置

OpenCode 支持 JSON 和 JSONC 格式。配置加载优先级如下：

1. .well-known/opencode（远程组织配置）
2. ~/.config/opencode/opencode.json（全局用户配置）
3. OPENCODE_CONFIG 环境变量
4. 项目根目录 opencode.json
5. .opencode 目录
6. OPENCODE_CONFIG_CONTENT 环境变量

完整配置示例

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "tokyonight",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": true,
  "tui": {
    "scroll_speed": 3,
    "diff_style": "auto"
  },
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true
  },
  "permission": {
    "edit": "allow",
    "bash": "ask"
  },
  "compaction": {
    "auto": true,
    "prune": true
  }
}

变量替换

支持环境变量 {env:VAR} 和文件内容 {file:path} 注入，便于安全存储敏感信息。

Provider 配置

OpenCode 支持 75+ 个 LLM 提供商。常用配置包括：

• Anthropic / OpenAI：支持订阅认证或手动输入 API Key。
• OpenCode Zen：官方推荐的经过验证模型列表。
• 本地模型：Ollama 或 LM Studio 需配置 baseURL 和 models。
• Amazon Bedrock：支持 AWS 访问密钥或命名配置文件。
• OpenRouter：聚合多个提供商，可配置 fallback 策略。

若需禁用特定 Provider，可在配置中设置 disabled_providers 数组。

TUI 终端界面使用

启动与基本操作

直接运行 opencode 或在指定目录下启动。发送消息按 Enter，换行使用 Shift+Enter 或 Ctrl+Enter。

内置命令

导航与编辑器

滚动使用 PageUp/PageDown，跳转顶部/底部用 Ctrl+g/End。配置 EDITOR 环境变量可启用 /editor 命令调用外部编辑器（VS Code 需加 --wait 参数）。

Agent 系统

主 Agent 与子 Agent

• 主 Agent：通过 Tab 在 Build 和 Plan 间切换。
• 子 Agent：使用 @general 或 @explore 调用，适合复杂任务或只读探索。

自定义 Agent

支持 JSON 配置或 Markdown 文件定义。例如创建代码审查专家 Agent，限制其仅能读取不能修改文件：

{
  "agent": {
    "code-reviewer": {
      "description": "代码审查专家",
      "mode": "subagent",
      "tools": { "write": false, "edit": false }
    }
  }
}

自定义命令

通过 JSON 或 Markdown 文件定义快捷指令。支持参数替换 $ARGUMENTS、Shell 命令输出 !`command` 及文件引用。

示例：创建 React 组件命令，模板中包含 TypeScript 类型定义。

快捷键配置

默认 Leader 键为 Ctrl+x。可在配置中自定义快捷键映射，例如将退出设为 <leader>q。禁用某项快捷键可设为 "none"。

常用快捷键包括：

• 新建会话：<leader>n
• 中断响应：Escape
• 压缩会话：<leader>c
• 复制消息：<leader>y

MCP 服务器

Model Context Protocol (MCP) 允许集成外部工具。配置分为本地（Local）和远程（Remote）两种类型。

常用示例

• Sentry：错误监控，需 OAuth 认证。
• Context7：文档搜索。
• Grep by Vercel：代码搜索。

权限管理支持全局禁用或按 Agent 单独启用特定 MCP 工具。

LSP 语言服务器

OpenCode 内置多种语言的 LSP 支持，如 TypeScript (typescript)、Python (pyright)、Rust (rust-analyzer) 等。打开文件时会自动启动对应服务器获取诊断信息。

可自定义 LSP 命令或禁用特定语言的服务。环境变量 OPENCODE_DISABLE_LSP_DOWNLOAD 可防止自动下载。

主题与个性化

终端需支持 Truecolor 才能正确显示主题。内置主题包括 tokyonight、catppuccin、gruvbox 等。

切换主题使用 /theme 命令或修改配置中的 theme 字段。自定义主题需遵循 JSON Schema 定义颜色变量。

Rules 自定义指令

AGENTS.md 文件用于定义给 LLM 的自定义指令，类似 Cursor 的 rules。支持自动生成或手动编写，包含项目结构、编码规范及 Monorepo 约定。

也可在配置中引用外部文件作为指令集，实现团队规范共享。

最佳实践与进阶技巧

高效工作流

1. 先规划后执行：利用 Plan 模式确认方案。
2. 精准引用：使用 @ 锁定上下文文件。
3. 拖放图片：终端中拖入设计稿供 LLM 参考。

性能优化

• 配置 small_model 处理轻量任务降低成本。
• 启用自动压缩 (compaction) 管理上下文长度。
• 避免加载过多 MCP 服务器。

安全建议

• 敏感命令（如 rm *, git push）设置为 ask 权限。
• 团队协作时共享 opencode.json 和 AGENTS.md。

常见问题解答

Q: 如何更换模型？ A: 使用 /models 命令或在配置文件中设置 model 字段。

Q: Shift+Enter 不工作？ A: 部分终端（如 Windows Terminal）需在 settings.json 中配置按键映射。

Q: 撤销操作无效？ A: 确保项目已初始化为 Git 仓库。

Q: API 密钥存储位置？ A: ~/.local/share/opencode/auth.json。

Q: 如何重置 OpenCode？ A: 删除 ~/.config/opencode 和 ~/.local/share/opencode 目录。

Q: Azure 遇到 content filter 错误？ A: 将资源的内容过滤器从 DefaultV2 改为 Default。

Q: 如何使用代理？ A: 设置 HTTPS_PROXY 和 HTTP_PROXY 环境变量。

更多资源

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