OpenCode 笔记
约 2130 字大约 7 分钟
2026-01-16
npm install opencode-ai -g/compact 用于压缩之前对话的上下文,把之前的对话提炼为一个简洁的摘要,释放模型的上下文窗口
除了内置的 / 命令,还可以自定义命令,在配置文件夹中创建一个command 文件夹,在其中以 md 文件的形式定义自己的命令,元字段查看官方
在配置文件夹中,创建一个 agent 文件夹,用于自定义智能体,在其中创建相关的 md 文件
mode 字段可以是 subagent ,表示它由主智能体来自动调度,在后台运行
还可以是 primary ,也就是主智能体,可以直接 tap 按键显式的切换智能体
全局配置:~/.config/opencode/opencode.json
创建项目级别 opencode.json 配置文件
进入项目目录(最好是项目根目录),创建/编辑 opencode.json
opencode 会从当前目录往上找 opencode.json,直到最近的 Git 目录为止;找到就用,能覆盖全局配置。
所以最稳的放置位置是:项目根目录(git root)。
AGENTS.md 是 opencode 的“项目级指令文件”。
- 它不是聊天记忆
- 也不是 AI 自动学习产生的东西
- 而是:你明确写给 agent 的规则和背景说明
只要 agent 在这个项目中运行:
- 每一次执行都会读取 AGENTS.md
- 把它当成“必须遵守的前提条件”
所以它表现得像记忆,但本质是固定说明书
没有 AGENTS.md 时,agent 往往会:不知道项目结构,随意选技术方案,改你不想动的代码,忽略测试 / 规范 / 约束
配置文件:opencode 在启动时会先在当前目录找配置文件,找不到就一路向上遍历目录,最多遍历到最近的 Git 目录(通常就是 repo root)为止
所以它的行为更像:“以 Git 仓库为边界,找最近的项目配置”,而不是无限向上找。
OpenCode 支持 JSON 和 JSONC(带注释) 格式。
合并机制:是 merge,不是 replace,配置会合并在一起:不冲突的键都会保留,冲突的键按优先级覆盖。
优先级顺序
标准顺序是:
- Remote(组织默认)(最低)
- Global:
~/.config/opencode/opencode.json(覆盖 remote) - Custom path:
OPENCODE_CONFIG=/path/to/xxx.json(夹在 global 和 project 之间) - Project:项目根目录的
opencode.json(最高,覆盖 global/remote)
SKILL
为每个技能名称创建一个文件夹,并在其中放置一个 SKILL.md。OpenCode 会搜索以下位置:
项目配置:.opencode/skill/<name>/SKILL.md
每个 SKILL.md 必须以 YAML frontmatter 开头。只识别以下字段:
name(必需)description(必需)license(可选)compatibility(可选)metadata(可选,字符串到字符串的映射)
未知的 frontmatter 字段会被忽略。
在 timeline 中选中任意的对话记录后:
Revert undo messages and file
Copy message text to clipboard
Fork create a new sessionRevert undo messages and file 相当于 回滚/撤销,会把会话状态回到“这条记录之前/对应的那个时刻”,不止回滚聊天消息,还会把 当时 agent 对文件做的修改也一起撤回(所以叫 messages and file)
适合场景:agent 改飞了、改多了,想回到某个“干净”的节点重新来
注意点:回滚后,后面的那段历史通常就等于被你“作废/覆盖”了
Copy message text to clipboard 就是 复制这条消息文本 到剪贴板,只复制“消息内容”(通常不包含文件 diff、附件、工具输出的完整结构)
适合:把某条 prompt / 输出贴到 PR、文档、群里,抽取一段命令/总结复用
Fork create a new session 相当于 从这里分叉一个新会话,新 session 会继承你在这条记录时的上下文/状态,但之后的对话会走新的分支,不影响原来的 session
适合:想尝试另一种方案,但不想破坏当前会话,同一个问题做 A/B 路线:比如“重构方案 A”和“方案 B”,这通常是最安全的“试错方式”:原 session 保底,新 session 放开试。
为重复任务创建自定义命令,自定义命令让你指定在 TUI 中执行该命令时要运行的提示,内置的命令如 /init、/undo、/redo、/share、/help等
创建 .opencode/command/test.md:
<!-- .opencode/command/test.md -->
---
description: 运行带覆盖率的测试
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---
运行完整的测试套件并生成覆盖率报告,显示任何失败。
专注于失败的测试并建议修复。frontmatter 定义命令属性,内容成为模板,通过输入 / 后跟命令名称来使用命令。
可以通过 OpenCode 配置或在 command/ 目录中创建 markdown 文件来添加自定义命令。
{
"$schema": "https://opencode.ai/config.json",
"command": {
// 这成为命令的名称
"test": {
// 这是将发送给 LLM 的提示
"template": "运行完整的测试套件并生成覆盖率报告,显示任何失败。\n专注于失败的测试并建议修复。",
// 这在 TUI 中显示为描述
"description": "运行带覆盖率的测试",
"agent": "build",
"model": "anthropic/claude-3-5-sonnet-20241022"
}
}
}使用 $ARGUMENTS 占位符向命令传递参数。
<!-- .opencode/command/component.md -->
---
description: 创建新组件
---
创建一个名为 $ARGUMENTS 的新 React 组件,支持 TypeScript。
包含适当的类型和基本结构。/component Button$ARGUMENTS 将被替换为 Button。
也可以使用位置参数访问单个参数:
$1- 第一个参数$2- 第二个参数$3- 第三个参数- 以此类推…
当 markdown 提示文件的内容需要执行命令后才知道,可以使用 ! command 将 bash 命令 输出注入到提示中。
例如,创建一个分析测试覆盖率的自定义命令:
复制
<!-- .opencode/command/analyze-coverage.md -->
---
description: 分析测试覆盖率
---
以下是当前的测试结果:
!`npm test`
根据这些结果,建议改进以提高覆盖率。或者审查最近的更改:
<!-- .opencode/command/review-changes.md -->
---
description: 审查最近的更改
---
最近的 git 提交:
!`git log --oneline -10`
审查这些更改并建议任何改进。命令在项目的根目录运行,其输出成为提示的一部分。
使用 @ 后跟文件名在命令中包含文件。
<!-- .opencode/command/review-component.md -->
---
description: 审查组件
---
审查 @src/components/Button.tsx 中的组件。
检查性能问题并建议改进。文件内容会自动包含在提示中。
opencode.json
{
"$schema": "https://opencode.ai/config.json",
"model": "claude-opus-4-5",
"provider": {
"anthropic": {
"options": {
"baseURL": "https://api.jiekou.ai/anthropic",
"apiKey": ""
}
},
"openai": {
"options": {
"baseURL": "https://api.jiekou.ai/openai/v1",
"apiKey": ""
}
},
"gemini": {
"options": {
"baseURL": "https://api.jiekou.ai/openai/v1",
"apiKey": "",
},
"models": {
"antigravity-claude-opus-4-5-thinking": {
"name": "Claude Opus 4.5 Thinking (Antigravity)",
"limit": { "context": 200000, "output": 64000 },
"modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
"variants": {
"low": { "thinkingConfig": { "thinkingBudget": 8192 } },
"max": { "thinkingConfig": { "thinkingBudget": 32768 } }
}
},
"gemini-2.5-flash": {
"name": "Gemini 2.5 Flash (Gemini CLI)",
"limit": { "context": 1048576, "output": 65536 },
"modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
},
"gemini-2.5-pro": {
"name": "Gemini 2.5 Pro (Gemini CLI)",
"limit": { "context": 1048576, "output": 65536 },
"modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
},
"gemini-3-flash-preview": {
"name": "Gemini 3 Flash Preview (Gemini CLI)",
"limit": { "context": 1048576, "output": 65536 },
"modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
},
"gemini-3-pro-preview": {
"name": "Gemini 3 Pro Preview (Gemini CLI)",
"limit": { "context": 1048576, "output": 65535 },
"modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
}
}
}
},
// "plugin": ["oh-my-opencode", "opencode-antigravity-auth@beta"]
}{
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
"agents": {
"librarian": {
"model": "opencode/glm-4.7-free"
},
"explore": {
"model": "opencode/grok-code"
},
"oracle": {
"model": "openai/gpt-5.2"
},
"frontend-ui-ux-engineer": {
"model": "gemini/gemini-3-pro-preview"
},
"document-writer": {
"model": "gemini/gemini-3-flash"
},
"multimodal-looker": {
"model": "gemini/gemini-3-flash"
}
}
}可以输入@ 然后选择智能体开始干活
在提示词内加上 ulw ,它会在干活的时候尽可能的调用它一切的潜能,把任务分配给几个智能体,并且并行运行
输入 /ralph-loop ,这个模式可以强制 AI 长时间的循环,对一个非常难的任务进行持续的工作
MCP 加得越多 ≠ 一定越聪明;过多 MCP 很容易烧钱 + 吃上下文 + 降稳定性。
在 opencode CLI 里,每一个 MCP server,本质都会做几件事之一(或多件):
- 注入 system / tool 级别的说明
- 暴露 工具 schema(JSON)
- 在调用时返回 结构化 or 非结构化内容
- 有些 MCP 还会在 启动或对话初期主动提供背景信息
这些东西都会进入:
- prompt tokens
- tool call tokens
- tool response tokens
全都算钱,也全都占上下文窗口。
AI API 中转商/提供商,在 OpenCode 的配置
只要它是 OpenAI 协议兼容(最常见),就按 openai-compatible 的方式配。
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"myrelay": {
"npm": "@ai-sdk/openai-compatible",
"name": "My Relay",
"options": {
"baseURL": "https://YOUR-RELAY-DOMAIN/v1",
"apiKey": "YOUR_KEY_HERE"
},
"models": {
"gpt-4o": { "name": "GPT-4o via relay" },
"gpt-4o-mini": { "name": "GPT-4o-mini via relay" }
}
}
}
}