OpenCode 开源 AI 编程代理实战与配置

然后输入 /connect 添加 Provider。以 OpenCode Zen 为例，按它的授权流程拿到 API 密钥，再粘贴进去就行。Anthropic、OpenAI 这类 Provider 也是类似的接法。

初始化项目上下文

运行 /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 用来给模型注入项目级编码规范和结构说明，可以放在项目根目录，也可以放在全局配置目录。

它还支持引用外部文件，比如 CONTRIBUTING.md，或者在线规则。Claude Code 的 CLAUDE.md 也能作为回退兼容。

使用体会和进阶设置

工作流

• 先用 Plan 模式把思路和边界理顺，再切 Build 落地。
• 需要上下文时，尽量用 @ 精准引用文件，别把整个仓库都扔给模型。
• 终端支持拖入图片，设计稿也能直接给 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。