摘要

• opencode官网

安装与升级

• Mac 安装可以使用 brew

# 安装
brew install anomalyco/tap/opencode

# 升级
brew upgrade anomalyco/tap/opencode

# 卸载
brew uninstall anomalyco/tap/opencode

• Windows

npm i -g opencode-ai

使用

• 启动

cd your-project
opencode

• 快速命令

快捷键	描述	注释
/（在开始）	命令或 skill	请参阅内置命令和 skills
!（在开始）	Bash 模式	直接运行命令并将执行输出添加到会话
@	文件路径提及	触发文件路径自动完成

配置文件

• 优先级顺序: 配置源按以下顺序加载（后面的源覆盖前面的源）

配置来源	位置 / 方式	作用范围	优先级	说明
远程配置	.well-known/opencode	组织级	6（最低）	组织默认配置，下发基础策略
全局配置	~/.config/opencode/opencode.json	当前用户	5	用户级偏好设置
项目配置	项目目录/opencode.json	当前项目	4	项目共享配置，可提交版本库
.opencode 目录	项目目录/.opencode/	当前项目	3	存放 agents / commands / plugins
自定义配置	OPENCODE_CONFIG 环境变量	运行环境	2	指定配置文件路径进行覆盖
内联配置	OPENCODE_CONFIG_CONTENT 环境变量	当前进程	1（最高）	直接注入配置内容，运行时覆盖

.opencode 和 ~/.config/opencode 目录的子目录使用复数名称：agents/、commands/、modes/、plugins/、skills/、tools/ 和 themes/。为了向后兼容，也支持单数名称（例如 agent/）。

Command

内置命令

命令	描述	备注
/agents	切换 agent
/connect	配置/连接 provider	—
/editor	打开外部编辑器	依赖环境变量 EDITOR
/exit	退出应用	—
/help	查看帮助	ctrl+p
/init	创建或更新 AGENTS.md	—
/mcps	启用/禁用 MCP servers	图中为复数形式
/models	切换模型	—
/variants	切换模型变体（需要模型支持变体）	low 低推理力度 (较低 token，简单任务) medium 中等推理力度 high/max 高推理力度 (较高 token，复杂任务)
/new	创建新会话	—
/review [commit|branch|pr]	审查代码变更	默认未提交内容
/sessions	切换会话	别名：/resume
/skills	查看 skills	—
/status	查看状态信息	—
/themes	切换主题	—
/compact	压缩上下文	别名：/summarize
/details	切换工具执行详情	—
/thinking	显示/隐藏推理过程	UI 控制
/undo	撤销上一操作	—
/share	分享会话	—
/unshare	取消分享	—

自定义命令

• 配置路径

全局(用户级)：~/.config/opencode/commands/
项目级：.opencode/commands/

内置Tools

工具	类型	描述	关键特点 / 备注
bash	执行类	执行 shell 命令	可运行任意终端命令（如 npm / git）
edit	文件修改	精确替换文本修改文件	核心代码修改工具
write	文件修改	创建或覆盖文件	受 edit 权限控制
patch	文件修改	应用 diff/补丁	适合批量或外部 patch
read	文件读取	读取文件内容	支持按行范围读取
grep	搜索	正则搜索文件内容	基于 ripgrep，性能高
glob	搜索	按模式查找文件	支持 **/*.ts 等
list	文件系统	列出目录内容	支持 glob 过滤
lsp（实验）	代码智能	调用 LSP 能力	需开启环境变量
skill	扩展	加载 SKILL.md 内容	用于复用能力
todowrite	状态管理	写入/更新任务列表	多步骤任务编排
todoread	状态管理	读取任务列表	与 todowrite 配套
webfetch	网络	获取网页内容	用于“已知 URL”
websearch	网络	搜索互联网信息	基于 Exa，无需 API Key
question	交互	向用户提问	支持选项/交互式输入

注意

• websearch：该工具仅在使用 OpenCode 提供商时，或当 OPENCODE_ENABLE_EXA 环境变量设置为任意真值（例如 true 或 1）时可用。
• lsp: OpenCode 内置了多种适用于主流语言的 LSP 服务器，该工具仅在设置环境变量 OPENCODE_EXPERIMENTAL_LSP_TOOL=true（或 OPENCODE_EXPERIMENTAL=true）时可用。
  • 一般情况下，lsp 功能在读取文件时会根据文件后缀自动匹配对应的 LSP 服务器，但是要满足特定的条件，比如.java，要求jdk21+

权限配置

• 规则

"allow" — 无需审批直接运行
"ask" — 提示审批
"deny" — 阻止该操作

• 示例:

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

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

Agents

• 可以使用 @ 进行关联

内置代理

• OpenCode 内置了两个主代理和两个子代理。

Agent	模式	描述	权限特点 / 适用场景
Build	primary	默认主代理，执行开发任务	✅ 全工具权限；适合代码编写、修改、执行命令
Plan	primary	用于规划与分析	⚠️ 默认全部为 ask（file edits + bash）；适合方案设计、代码审查
General	subagent	通用多步骤任务代理	✅ 几乎全工具（除 todo）；支持并行执行复杂任务
Explore	subagent	只读代码探索代理	❌ 无写权限；适合搜索代码、分析结构
Compaction	primary（系统）	压缩上下文	🔒 自动运行；不可手动选择
Title	primary（系统）	生成会话标题	🔒 自动运行；不可手动选择
Summary	primary（系统）	生成会话摘要	🔒 自动运行；不可手动选择

• 查看所有的 agent

opencode agent list

自定义代理

opencode agent create

# 此交互式命令将：
# 询问代理的保存位置——全局或项目级。
# 描述代理应该做什么。
# 生成合适的系统提示词和标识符。
# 让您选择代理可以访问哪些工具。
# 最后，创建一个包含代理配置的 Markdown 文件。

Plugin

• 插件加载顺序

顺序	来源	路径	作用域	优先级	说明
1	全局配置	~/.config/opencode/opencode.json	用户级	⭐ 最低	定义全局启用的 npm 插件
2	项目配置	./opencode.json	项目级	↑	覆盖或追加项目特定插件
3	全局插件目录(本地文件)	~/.config/opencode/plugins/	用户级	↑	本地开发/调试插件（全局生效）
4	项目插件目录(本地文件)	./.opencode/plugins/	项目级	⭐ 最高	项目私有插件，优先级最高

• 安装插件
  主要参考各个插件提供商官网(或Github)中说明的安装方式，比如这里以https://github.com/obra/superpowers 为例，在对话窗口中输入如下内容，则 opencode 会自动安装该插件，opencode会先检查当前目录中是否存在opencode.json文件，如果文件存在，则将插件安装到该文件中，否则将其安装到全局配置文件~/.config/opencode/opencode.json

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

安装后会在对应的 opencode.json 中看到

{
	"plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}

• npm 插件在启动时使用 Bun 自动安装。包及其依赖项会缓存在 ~/.cache/opencode/node_modules/ 中。
• 本地插件(本地文件) 直接从插件目录加载。
• 使用 plugin，可以通过 /skills 调用对应的 plugin 提供的 skill 来强制使用，也可以交由大模型自行决定

Skill

• 为每个技能名称创建一个文件夹，并在其中放入 SKILL.md。 OpenCode 会搜索以下位置：

顺序	类型	路径	作用域	来源体系	优先级	说明
1	项目配置	.opencode/skills/<name>/SKILL.md	项目级	OpenCode 原生	⭐ 最高	项目内定义的 Skills，优先级最高
2	全局配置	~/.config/opencode/skills/<name>/SKILL.md	用户级	OpenCode 原生	↑	全局通用 Skills
3	项目 Claude 兼容	.claude/skills/<name>/SKILL.md	项目级	Claude Code	↑	兼容 Claude Code 的 Skills
4	全局 Claude 兼容	~/.claude/skills/<name>/SKILL.md	用户级	Claude Code	↑	全局 Claude Skills
5	项目代理兼容	.agents/skills/<name>/SKILL.md	项目级	Agent 系统	↑	通用 Agent 技能目录
6	全局代理兼容	~/.agents/skills/<name>/SKILL.md	用户级	Agent 系统	⭐ 最低	最低优先级兜底

• 使用 skill，可以通过 /skills 调用对应的 skill 来强制使用，也可以交由大模型自行决定

MCP

• 添加mcp

opencode mcp add

┌  Add MCP server
│
◇  Location
│  Current project
│
◇  Enter MCP server name
│  amap
│
◇  Select MCP server type
│  Remote
│
◇  Enter MCP server URL
│  https://mcp.amap.com/mcp?key={env:AMAP_KEY}
│
◇  Does this server require OAuth authentication?
│  No
│
◆  MCP server "amap" added to /Users/hanqf/Desktop/abc/opencode.json
│
└  MCP server added successfully

• 查看mcp

opencode mcp list

┌  MCP Servers
│
●  ✓ amap connected
│      https://mcp.amap.com/mcp?key=xxxxxx
│
└  1 server(s)