OpenCode 高级功能中文教程

本文基于 OpenCode 官方文档整理，帮助你快速掌握 LSP、MCP、Agent Skills、ACP、自定义工具和工具管理等高级能力。
最后更新时间：2026年1月23日

1. LSP 服务器集成（代码智能）

LSP（Language Server Protocol） 是一种标准协议，用于为编辑器提供代码补全、跳转定义、错误诊断等功能。OpenCode 可以利用 LSP 获取项目上下文，让 AI 更理解你的代码。

✅ 内置支持的语言

OpenCode 自动识别以下语言并启动对应的 LSP 服务（需满足依赖条件）：

语言	文件扩展名	依赖要求
TypeScript/JavaScript	`.ts`, `.js` 等	项目含 `typescript`
Python	`.py`	安装 `pyright`
Go	`.go`	安装 `go`
Rust	`.rs`	安装 `rust-analyzer`
PHP	`.php`	自动安装 Intelephense
Vue/Svelte/Astro	`.vue`, `.svelte`, `.astro`	自动安装对应 LSP
…	…	…（详见官方表格）

💡 提示：若不想自动下载 LSP 服务，设置环境变量：
1
export OPENCODE_DISABLE_LSP_DOWNLOAD=true

🔧 配置方式

在 opencode.json 中配置：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    // 禁用 TypeScript LSP
    "typescript": { "disabled": true },
    
    // 自定义 LSP（示例）
    "my-custom-lsp": {
      "command": ["my-lsp-server", "--stdio"],
      "extensions": [".myext"]
    }
  }
}

⚠️ 注意事项

LSP 启动后会向 AI 提供代码诊断信息（如错误、警告），帮助 AI 更准确地修改代码。

实验性 LSP 工具（如

1	goToDefinition

）需开启环境变量：

1	export OPENCODE_EXPERIMENTAL_LSP_TOOL=true

2. MCP 服务器（扩展外部工具）

MCP（Model Context Protocol） 允许 OpenCode 接入外部工具服务（本地或远程），如数据库查询、API 调用、文档搜索等。

📌 两种类型

1) 本地 MCP 服务

{
  "mcp": {
    "my-local-tool": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-server"],
      "environment": {
        "API_KEY": "your-key"
      },
      "enabled": true
    }
  }
}

2) 远程 MCP 服务

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

✅ 支持从环境变量读取值：{env:VAR_NAME}

🛠 常用 MCP 示例

搜索技术文档（Context7）

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

使用时在提示词中写：

“使用 context7 查找如何配置 Cloudflare Worker 缓存”

搜索 GitHub 代码（Grep by Vercel）

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

提示词示例：

“使用 gh_grep 查找 SST Astro 组件设置自定义域名的方法”

⚠️ 注意事项

MCP 工具会增加上下文长度（token），可能导致超出模型限制。
建议按需启用，避免加载过多工具。

3. Agent 技能（SKILL.md 复用逻辑）

Agent Skills 是一种通过 SKILL.md 文件定义可复用行为的方式。AI 在需要时会自动加载这些技能。

📂 文件位置

项目级：.opencode/skill/<名字>/SKILL.md
全局级：~/.config/opencode/skill/<名字>/SKILL.md
也兼容 Claude 格式：.claude/skills/...

📝 文件格式（必须包含 YAML Frontmatter）

---
name: git-release
description: 创建一致的版本发布和更新日志
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
---

## 我能做什么
- 根据合并的 PR 草拟发布说明
- 建议版本号升级
- 生成 `gh release create` 命令

## 何时使用我
当你准备打 tag 发布新版本时。

🔒 权限控制

在 opencode.json 中配置技能访问权限：

{
  "permission": {
    "skill": {
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask",
      "*": "allow"
    }
  }
}

allow：直接加载
deny：隐藏且拒绝
ask：询问用户是否允许

❌ 禁用技能工具

{
  "tools": {
    "skill": false
  }
}

4. ACP 支持（在编辑器中使用 OpenCode）

ACP（Agent Client Protocol） 是一个开放协议，允许编辑器与 AI 代理通信。OpenCode 支持 ACP，可在 Zed、JetBrains、Neovim 等编辑器中使用。

🛠 配置方法

Zed 编辑器

~/.config/zed/settings.json：

{
  "agent_servers": {
    "OpenCode": {
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

快捷键（可选）：

{
  "bindings": {
    "cmd-alt-o": ["agent::NewExternalAgentThread", {
      "agent": { "custom": { "name": "OpenCode", "command": { "command": "opencode", "args": ["acp"] } } }
    }]
  }
}

JetBrains IDE

在项目根目录创建 acp.json：

{
  "agent_servers": {
    "OpenCode": {
      "command": "/绝对路径/bin/opencode",
      "args": ["acp"]
    }
  }
}

然后在 AI Chat 中选择 “OpenCode” 代理。

Neovim（Avante.nvim）

{
  acp_providers = {
    ["opencode"] = {
      command = "opencode",
      args = { "acp" },
      env = { OPENCODE_API_KEY = os.getenv("OPENCODE_API_KEY") }
    }
  }
}

Neovim（CodeCompanion.nvim）

require("codecompanion").setup({
  interactions = {
    chat = {
      adapter = {
        name = "opencode",
        model = "claude-sonnet-4",
      },
    },
  },
})

✅ 所有功能均支持（除 /undo /redo 等少数命令）

5. 自定义工具（让 AI 调用你的脚本）

你可以编写自己的工具，让 AI 在对话中调用它们。

📁 存放位置

项目级：.opencode/tools/
全局级：~/.config/opencode/tools/

🧩 工具定义（TypeScript/JavaScript）

单个工具

.opencode/tools/database.ts：

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "查询项目数据库",
  args: {
    query: tool.schema.string().describe("SQL 查询语句")
  },
  async execute(args) {
    // 你的数据库逻辑
    return `执行了查询: ${args.query}`
  }
})

工具名 = 文件名（database）

多个工具（一个文件）

.opencode/tools/math.ts：

1 2	export const add = tool({ ... }) // 工具名：math_add export const multiply = tool({ ... }) // 工具名：math_multiply

🐍 调用其他语言（如 Python）

创建 Python 脚本 .opencode/tools/add.py：

import sys
a = int(sys.argv[1])
b = int(sys.argv[2])
print(a + b)

创建 TS 封装 .opencode/tools/python-add.ts：

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "用 Python 加两个数",
  args: {
    a: tool.schema.number(),
    b: tool.schema.number()
  },
  async execute(args) {
    const result = await Bun.$`python3 .opencode/tools/add.py ${args.a} ${args.b}`.text()
    return result.trim()
  }
})

✅ 支持任何语言，只要能通过命令行调用

6. 工具管理（精细控制 AI 能做什么）

OpenCode 默认启用所有内置工具，但你可以精确控制哪些工具可用。

🔌 内置工具列表

工具	功能
`read`	读取文件内容
`write`	创建/覆盖文件
`edit`	精确替换文件内容
`bash`	执行 shell 命令
`grep`	正则搜索代码
`glob`	匹配文件路径（如 `*/.ts`）
`list`	列出目录内容
`webfetch`	抓取网页
`skill`	加载 SKILL.md
`todowrite` / `todoread`	管理待办任务
`patch`	应用补丁
`lsp`	（实验性）调用 LSP 功能

🌐 全局禁用

opencode.json：

{
  "tools": {
    "write": false,
    "bash": false,
    "webfetch": true,
    "mymcp_*": false  // 禁用某 MCP 的所有工具
  }
}

👤 按 Agent 禁用

{
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

或在 Markdown Agent 中：

--- 
description: 只读分析助手
tools:
  write: false
  edit: false
  bash: false
---

🚫 忽略文件处理

默认情况下，grep/glob/list 会遵守 .gitignore。

若想包含被忽略的文件（如 node_modules），创建 .ignore 文件：

1 2	!node_modules/ !dist/

总结

功能	用途	关键文件/配置
LSP	代码智能	`opencode.json` → `lsp`
MCP	接入外部服务	`opencode.json` → `mcp`
Skills	复用行为模板	`SKILL.md`
ACP	编辑器集成	各编辑器配置文件
Custom Tools	自定义 AI 能力	`.opencode/tools/*.ts`
Tools 管理	权限控制	`opencode.json` → `tools` / `permission`