OpenCode 开源 AI 编程助手：安装与实战指南

输入 /connect 添加 Provider。以 OpenCode Zen 为例，访问授权页面获取 API 密钥并粘贴即可。其他 Provider 如 Anthropic 或 OpenAI 也可通过类似流程绑定。

初始化项目

运行 /init 命令，OpenCode 会分析项目结构并生成 AGENTS.md 文件。建议将此文件提交至 Git 仓库，以便后续迭代中保持上下文一致。

基础交互

• 询问代码问题：直接输入自然语言，例如'介绍一下这个代码库'。
• 引用文件：使用 @ 符号搜索并引用具体文件，如 @src/components/Button.tsx。
• 执行 Shell 命令：以 ! 开头，例如 !npm test。

Plan 与 Build 模式

按 Tab 键可在两种模式间切换：

• Build 模式：拥有完整权限，可修改文件，适合实际开发。
• Plan 模式：只读模式，仅分析不修改，适合代码审查或方案规划。

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

撤销与重做

使用 /undo 和 /redo 可管理操作历史。注意这依赖于 Git 仓库状态。

配置文件详解

OpenCode 支持 JSON 和 JSONC 格式的配置，优先级从低到高依次为：远程组织配置、全局用户配置、环境变量、项目专属配置、.opencode 目录内容。

典型配置示例如下：

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

变量替换功能允许使用 {env:VAR} 或 {file:path} 引用环境变量或文件内容，便于安全存储敏感信息。

Provider 配置

OpenCode 支持 75+ 个 LLM 提供商。常用选项包括 OpenCode Zen、Anthropic、OpenAI、Google Vertex AI、Ollama 等。

本地模型配置

对于 Ollama 或 LM Studio 等本地服务，需在配置文件中指定 baseURL 和模型名称。例如 Ollama 通常运行在 http://localhost:11434/v1。若遇到工具调用问题，尝试增加 num_ctx 参数至 16k-32k。

禁用或启用 Provider

可通过配置项控制可用 Provider 列表：

{
  "disabled_providers": ["openai", "gemini"],
  "enabled_providers": ["anthropic", "opencode"]
}

TUI 终端界面使用

基本操作

启动后直接输入文字发送消息。需换行时按 Shift+Enter 或 Ctrl+Enter。引用文件输入 @ 后模糊搜索，执行命令前加 !。

内置命令

导航与编辑器

滚动使用 PageUp/PageDown 或 Ctrl+Alt+b/f。设置 EDITOR 环境变量（如 code --wait）可启用 /editor 命令调用外部编辑器。

Agent 系统

Agent 类型

• 主 Agent：Build（默认）和 Plan（只读），通过 Tab 切换。
• 子 Agent：General（通用）和 Explore（探索），通过 @ 提及调用。

自定义 Agent

可通过 JSON 配置或 Markdown 文件定义新 Agent。Markdown 方式更直观，位于 .opencode/agents/ 目录下。

---
description: 代码审查专家
mode: subagent
model: anthropic/claude-sonnet-4-5
---
你是一个代码审查专家。请关注代码质量、潜在 bug 及安全考虑。

权限配置可精细控制编辑、Shell 执行等操作，确保安全性。

自定义命令

创建命令可封装常用工作流。支持 JSON 或 Markdown 格式，位于 .opencode/commands/。

模板语法支持 $ARGUMENTS 占位符及 Shell 命令输出插入。例如创建一个测试命令，自动运行套件并分析失败用例。

快捷键配置

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

完整列表涵盖会话管理、模型切换、主题调整及输入控制等功能。

MCP 服务器

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

常用示例

• Sentry：连接错误监控系统。
• Context7：文档搜索增强。
• Grep by Vercel：代码搜索能力。

认证类 MCP 服务器需运行 opencode mcp auth 进行 OAuth 登录。权限管理支持全局禁用或按 Agent 启用特定工具。

LSP 语言服务器

OpenCode 内置多种语言的 LSP 支持，包括 TypeScript、Python、Rust、Go 等。启动时根据文件扩展名自动加载对应服务器，反馈诊断信息给 LLM。

可在配置中自定义 LSP 命令或禁用特定语言支持。环境变量 OPENCODE_DISABLE_LSP_DOWNLOAD 可防止自动下载。

主题与个性化

终端需支持 Truecolor（24 位色）。内置主题包括 Tokyo Night、Catppuccin、Gruvbox 等。切换主题使用 /theme 命令或在配置中指定 theme 字段。

自定义主题需遵循 JSON Schema，定义背景、前景、强调色等属性，支持 Hex 颜色及深浅变体。

Rules 自定义指令

AGENTS.md 文件用于向 LLM 注入项目特定的编码规范和结构说明。位置在项目根目录或全局配置目录。

支持引用外部文件（如 CONTRIBUTING.md）或在线规则。Claude Code 的 CLAUDE.md 约定也被兼容作为回退。

最佳实践与进阶技巧

高效工作流

1. 先规划后执行：利用 Plan 模式梳理逻辑，再切 Build 模式落地。
2. 精准引用：使用 @ 锁定关键文件上下文。
3. 图片拖放：终端支持拖入设计稿供 LLM 参考。

性能与安全

• 轻量任务配置 small_model 降低成本。
• 启用 compaction 自动压缩上下文。
• 限制 MCP 数量以减少上下文负载。
• 敏感操作（如 rm *）设置为 ask 权限。

团队协作

将 opencode.json、AGENTS.md 及 .opencode 目录纳入版本控制，统一团队配置。会话可通过 /share 生成链接分享。

常见问题解答

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

Q: Shift+Enter 不工作？ 部分终端需配置按键映射，如 Windows Terminal 的 settings.json。

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

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

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

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

Q: Azure 报错 content filter？ 将资源的内容过滤器策略从 DefaultV2 改为 Default。