opencode的安装和使用

发表于 更新于 分类于 置顶 精品
阅读次数： 0 本文字数： 2.2k 阅读时长 ≈ 8 分钟

摘要

安装与升级

  • Mac 安装可以使用 brew

1
2
3
4
5
6
7
8
9
# 安装
brew install anomalyco/tap/opencode

# 升级
brew upgrade anomalyco/tap/opencode

# 卸载
brew uninstall anomalyco/tap/opencode

  • Windows

1
npm i -g opencode-ai

使用

  • 启动

1
2
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 取消分享 —

自定义命令

  • 配置路径

1
2
全局(用户级)：~/.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+

权限配置

  • 规则

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

  • 示例:

1
2
全局：~/.config/opencode/opencode.json
项目级：opencode.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "$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

1
opencode agent list

自定义代理

1
2
3
4
5
6
7
8
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

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

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

1
2
3
{
	"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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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

1
2
3
4
5
6
7
8
opencode mcp list

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