OpenCode 学习文档
OpenCode is an open source AI coding agent. It's available as a terminal-based interface, desktop app, or IDE extension.
[!info] related notes opencode-tui-operation-guide autonomous-coding-agent claude-code quick-launch-opencode-knowledge-base mem0 AI Agent 配置文件路径参考
OpenCode 学习文档
基于 OpenCode 开源 AI 编程工具的结构化学习笔记，用于初学、回顾、扩展。
1. 概览（Overview）
- OpenCode 是什么？
- OpenCode 是一个开源的 AI 编程代理，帮助开发者在终端、IDE 或桌面环境中编写代码。
- 作用 / 适用场景
- 智能编码助手
- 代码调试和修复
- 项目重构和优化
- 多语言开发支持
- 一句话总结
- “OpenCode = 一个可以在终端中使用的开源 AI 编程助手，支持多种 AI 模型和编辑器。“
2. 关键概念（Core Concepts）
- AI Agent：智能编程代理
- LSP Integration：语言服务器协议集成
- Multi-session：多会话管理
- Tool Integration：工具集成（命令执行、文件搜索等）
- TUI：终端用户界面
- Privacy First：隐私优先设计
核心概念包括：
- AI Provider：AI 模型提供商（OpenAI、Claude、Gemini 等）
- Session Management：会话保存和管理
- Shell Integration：Shell 命令执行
- File Tracking：文件变更跟踪
- Custom Commands：自定义命令支持
3. 与 memory 的关系
OpenCode 更适合理解成 coding agent client，而不是原生 memory system。
它的价值主要在于：
- 作为终端 / 桌面 / IDE 的 agent 入口
- 连接外部模型和工具
- 通过 mcp 接入共享 memory backend
如果目标是跨多个工具共享长期记忆，OpenCode 通常扮演的是“使用同一套 memory 服务的客户端”，而不是主记忆库本身。
4. 规则文件与配置文件
规则文件
OpenCode 的原生规则文件是 AGENTS.md：
- 项目级：当前目录或父目录中的
AGENTS.md - 全局：
~/.config/opencode/AGENTS.md
同时它还兼容 Claude Code 的文件约定作为 fallback：
- 项目级：
CLAUDE.md - 全局：
~/.claude/CLAUDE.md
查找顺序是：
- 本地向上遍历
AGENTS.md/CLAUDE.md ~/.config/opencode/AGENTS.md~/.claude/CLAUDE.md
如果同目录内 AGENTS.md 和 CLAUDE.md 同时存在，优先用 AGENTS.md。
外部 instruction files
OpenCode 还支持在配置文件里通过 instructions 字段引用额外 Markdown 规则文件：
- 项目级：
opencode.json - 全局：
~/.config/opencode/opencode.json
这些 instruction files 会和 AGENTS.md 一起组合进上下文。
Prompt / agent 文件
如果你想给 OpenCode 做更明确的“提示词入口”，当前官方更推荐用自定义 agents：
- 全局：
~/.config/opencode/agents/*.md - 项目级：
.opencode/agents/*.md
也可以直接在 opencode.json 里给 agent 配 prompt，并引用外部 prompt 文件。
如果更偏“命令式 prompt”，OpenCode 还支持自定义 commands：
- 全局：
~/.config/opencode/commands/*.md - 项目级：
.opencode/commands/*.md
文件名会直接变成 /命令名，适合把高频分析、review、fix 流程固化成 prompt 模板。
配置文件
- 全局主配置：
~/.config/opencode/opencode.json - 项目主配置：
opencode.json - 全局 TUI 配置：
~/.config/opencode/tui.json - 项目 TUI 配置：
tui.json
OpenCode 配置是 merge 模式，不是整份替换。项目配置会覆盖冲突键，但会保留全局中不冲突的设置。