上篇讲的是脑子里那层壳。 下篇讲怎么把它装到机器上。 这不是终极配置。只是新手村门口那把木剑。木剑不帅，但能让你活着走到第二张地图。
# 开始之前：别把这篇当万能答案
先把话说死。
这篇不是“我的 OpenCode 神级配置”。
神级配置这种说法，一听就是卖课味。真正跑过生产系统的人都知道，配置没有神级，只有适配。你的机器、模型额度、项目类型、风险边界、写作习惯、代码库大小、公司规矩，全都不一样。把别人的配置原样复制过去，短期看像省事，长期看就是埋雷。
所以这篇只做一件事：给新手一个能站稳的起点。
起点的标准很朴素：
- OpenCode 能启动。
- 规则能被读到。
- OMO 能体检。
- MCP 能看见。
- 模型路由知道去哪查。
- 失败以后知道先看哪里。
- 不会因为一个“帮我清理一下”把自己的东西搞没。
能做到这些，你才配谈“出神入化”。
很多人顺序反了。他们一上来就问最强模型、最猛 agent、最多 MCP、Team Mode 怎么开。像一个一级小号刚出村，第一句话问屠龙刀哪里爆。
先别屠龙。
先别死。
# 第一章：确认你正在摸的是哪台机器
OpenCode 不是一个单独按钮。你要把它看成四件套：进程、配置、插件、数据库。
进程，是你正在跑的 opencode。CLI 是一个进程，Desktop 里面也会起一个 sidecar server。不要同时开一堆。它们可能共用同一个 SQLite 数据库，抢写锁的时候，你会得到一种很玄学的卡死。
配置，是 opencode.jsonc 和 OMO 自己的配置。它们不是摆设。OpenCode 官方文档讲得很清楚：配置有全局、项目、环境变量、内联等多层来源，会合并，会覆盖，坏字段会让启动失败。改完配置以后要完全退出重启。不要幻想热加载。
插件，是 oh-my-openagent 这类东西。它在启动时加载 hooks、agent、skills、MCP 增强。运行中的会话不会因为你磁盘上改了配置就突然变聪明。
数据库，是 ~/.local/share/opencode/opencode.db 这类状态。会话、消息、事件都可能在里面。它不是垃圾桶，也不是你随便 cp 的普通文本。需要维护时先备份。
新手第一天，只做体检。
opencode --version
opencode mcp list
opencode debug config
bunx oh-my-openagent doctor如果你本机跟我的运维快照一致，OpenCode 是 1.18.3，CLI 和 Desktop 版本对齐；有效 MCP 有 7 个，状态 connected；OMO 是 4.19.0，doctor 通过。你的机器未必一样，所以不要抄数字，抄动作。
动作是：先确认版本，再看 MCP，再看合并后的配置，再跑 OMO 体检。
这四步做完，才知道自己摸的是马、骡子，还是一台没插电的木马。
# 第二章：先写 AGENTS.md，不要先写提示词
新手最常见的错误，是把所有规则写在当前会话里。
“以后你要注意……”“接下来你必须……”“记住不要……”
这类话短期有效，长期没用。会话结束就没了。上下文一长就稀释了。换个 agent 又忘了。
正确动作是把稳定规则写进 AGENTS.md。
OpenCode 支持项目根目录的 AGENTS.md，也支持全局规则。官方规则文档说，OpenCode 会从当前目录向上找项目规则，也会读全局规则；同目录 AGENTS.md 优先于 CLAUDE.md；它不会自动向下读取子目录规则，monorepo 要用 instructions 显式补。
新手的第一份 AGENTS.md，不需要宏大。
写这几段就够了：
# Project Rules
## Purpose
This repository is for <一句话说明项目用途>.
## Commands
- Install: `<命令>`
- Test: `<命令>`
- Build: `<命令>`
## Safety
- Never commit secrets.
- Never run destructive commands without explicit approval.
- Read files before editing them.
- After editing, run the nearest validation command.
## Style
- Follow existing patterns before inventing new ones.
- Keep changes scoped to the user request.
## Verification
For every code change, report what was changed and what command proved it works.这份东西很土。
但土的东西救命。
你以后再加复杂规则：目录结构、日志原则、部署流程、数据库迁移、权限边界、发布清单。不要第一天就写一本圣经。第一天先把刹车装上。
写完以后，重启 OpenCode，开一个新会话，让它复述项目规则。它能复述，说明读到了。它复述不了，不要继续写代码。先修规则加载。
# 第三章：权限不是信任问题，是事故半径问题
OpenCode 的 agent 可以配置 permission。read、edit、bash、webfetch、websearch、lsp、skill、task 这些能力，不应该一股脑全开。
新手第一套权限，原则很简单：读可以宽，写要窄，bash 要问，不可逆操作必须人工确认。
不要把这件事道德化。
不是“我相不相信 AI”。你相信它也没用。事故发生时，文件系统不关心你们关系好不好。数据库不关心它是不是态度诚恳。生产环境不接受道歉。
你要按事故半径分级：
- 读文件：低风险，通常允许。
- 改项目文件：中风险，看工作目录和任务类型。
- 跑测试、构建：低到中风险，通常允许或询问。
- 删除、移动、大规模格式化、数据库写入、网络发布：高风险，必须问。
- 凭据、生产服务、共享基础设施：默认不让 agent 自己碰。
这就是 Harness 的第一层。不是让马听话，是让马就算发疯也冲不出围栏。
# 第四章：装 OMO 以后，先理解 11 个 agent 和 8 个 category
OMO 的价值在于编排，不在于多几个名字。
你需要先记住两套东西。
第一套是 agent。它们像固定角色：
- Sisyphus：主编排者，判断意图，决定路线。
- Prometheus：计划，把模糊需求问清楚。
- Atlas：按计划推进执行。
- Oracle：高难架构、调试、审查，只读顾问。
- Librarian：查官方文档、开源实现、外部资料。
- Explore：查本地代码库。
- Metis：找计划里的隐藏歧义。
- Momus：挑计划和结果的刺。
- Multimodal-looker：看图、PDF、视觉资料。
- Hephaestus：深度自主执行。
- Sisyphus-Junior：按类别干具体活。
第二套是 category。它们像兵种路线：
visual-engineering：UI、视觉、前端。ultrabrain：高难逻辑、架构。deep：自主深度执行。artistry：创意和非常规方案。quick：小修小补。unspecified-low/unspecified-high：通用低/高强度。writing：文档和长文。
新手不要急着自定义所有 agent。
先学会问自己一句：这件事到底是什么活？
问库怎么用，是 Librarian。问项目里哪里实现了某功能，是 Explore。让它改一个小配置，是 quick。让它做 UI，是 visual-engineering。让它做复杂架构判断，是 ultrabrain 或 Oracle。让它写长文，是 writing，但最终你要亲自审。
路由先对，模型才有意义。
# 第五章：模型路由先用默认，不要第一天就炼丹
OMO 支持给 agent 和 category 配模型，也支持 fallback_models。听起来很好玩，但新手很容易玩成事故。
第一天不要炼丹。
你只需要知道三件事。
第一，模型必须带 provider 前缀。不要写一个裸名字然后期待系统猜。
第二，fallback_models 是候选列表，不是自动切换本身。要运行时真的切，得配置 runtime_fallback.enabled，还要重启。我的本机知识库里专门记了这件事：声明不等于激活；激活也要有候选。
第三，当前会话用什么模型，不一定等于路由表默认值。用户手动切换、配置覆盖、category 默认、fallback 链，都可能影响结果。遇到“它怎么不是我想的模型”，先查合并配置和运行时注册，不要猜。
新手最稳的策略是：
- 先跑默认路由。
- 只在某个 agent 明显不合适时改它。
- 每次只改一处。
- 改完重启。
- 跑 doctor。
- 记录改动原因。
这比网上抄一份“全模型最优配置”强一百倍。
# 第六章：MCP 先接三根神经就够了
MCP 可以让 OpenCode 调外部工具。官方文档说，OpenCode 支持 local 和 remote MCP；配置在 mcp 字段下；local 用 command 和 environment，remote 用 url、headers、oauth；MCP 工具会和内置工具一起出现在 agent 可用工具里。
新手不要贪多。
先接三类：
第一，文档神经。比如 Context7。你问库、框架、SDK、CLI 的用法，优先查当前文档，不要让模型凭训练记忆瞎答。
第二，代码神经。比如 LSP 或 CodeGraph。你改代码前要知道定义、引用、调用路径、诊断结果。别靠肉眼在文件树里乱翻。
第三，搜索神经。比如 Exa 或 GitHub 代码搜索。你需要看真实世界怎么写，而不是只看教程。
视觉、多模态、浏览器、数据库、公司内部系统，可以以后再接。每多接一个工具，就多一个权限面，也多一个失败点。感官不是越多越好。感官要服务于验收。
凭据只放配置文件，mode 600，知识库只记录字段名，不记录值。
这条不要讨论。
# 第七章：skills 和 commands 是可复用动作，不是收藏夹
OpenCode 支持 commands，OMO 也注入很多 skills。很多人把它们当快捷方式。
不够。
它们真正的价值，是把一套成熟动作固化下来。
比如你经常做代码审查，就不该每次手写“请帮我 review 一下”。你应该有一个 review skill 或命令，里面写清楚：先看 diff，再找 bug，再看测试，再按严重级别输出，没发现问题就说没有，不要凑数。
比如你经常做调试，就应该有一个 debugging workflow：先复现，列假设，验证假设，锁最小失败用例，修最小根因，跑验证，不许靠猜。
比如你经常写文章，就应该有一个写作 skill：读取作者人设，读取参考作品，列禁忌，先提结构，再写正文，再做风格审查。
可复用动作越多，你越不像在跟 AI 聊天，越像在操作一台机器。
聊天依赖临场发挥。
机器依赖标准流程。
# 第八章：你的第一条工作流：研究、计划、执行、验收
新手最稳的 OpenCode 工作流，四步就够。
第一步，研究。
让 Explore 查本地代码，让 Librarian 查外部文档。不要一上来就实现。你还没看地形就冲锋，只是死得比较有激情。
第二步，计划。
让 Plan/Prometheus 把任务拆开。多文件、多步骤、有歧义的需求，不要直接动手。计划不需要漂亮，需要可执行：改哪些文件，为什么改，怎么验证，什么不能碰。
第三步，执行。
按任务类型派 category。小任务 quick，复杂任务 deep，视觉任务 visual-engineering。一次只做一个明确目标。不要让一个 agent 同时“顺便优化一下”。顺便，是 AI 工程里的脏字。
第四步，验收。
读改过的文件。跑诊断。跑测试。能启动就启动，能请求就请求，能截图就截图。最后再让审查 agent 挑刺。
每次都这样，会慢一点。
但慢的是开头。等这套动作变成肌肉记忆，你会比那些裸奔的人快得多。因为他们把省下的五分钟，全赔在事故里。
# 第九章：Team Mode 等你会单刷以后再开
Team Mode 很强。它能建队、发消息、共享任务、成员 claim 工作、必要时配 tmux 看每个成员怎么跑。官方文档也写得很清楚：默认关闭；配置 team_mode.enabled；重启后才有 12 个 team_* 工具；最多成员、并发、消息大小、wall clock 都有边界。
新手不要第一天开。
你先满足三个条件：
- 你能用单 agent 完成一次研究、修改、测试、验收。
- 你能写出明确任务边界，不让两个成员改同一块。
- 你能看懂成员报告，知道谁真的完成了，谁只是在说漂亮话。
满足以后，再开团。
第一次开团，只做研究型任务。比如：一个成员看官方文档，一个成员看本地配置，一个成员看公开案例，一个成员当反方挑错。不要第一次就让四个 agent 同时改代码。
队伍越多，越需要军法。
没有军法的团队，只是并行的噪音。
# 第十章：失败时按这个顺序排，不要乱拜神
OpenCode/OMO 出问题时，新手很容易乱改配置。今天删缓存，明天换模型，后天重装，最后把问题从一个变成五个。
按顺序来。
第一，看你在哪个目录。这个目录有没有自己的 AGENTS.md、opencode.json、.opencode。很多“为什么规则没生效”，其实是工作目录错了。
第二，看进程。CLI、Desktop、web server 有没有同时跑。只留一个。
第三，看版本。CLI 和 Desktop 是否一致。插件版本是否是你以为的那个。
第四，看合并配置。
opencode debug config你看到的是运行时会读的最终形态，不是你脑子里那份。
第五，看 MCP。
opencode mcp list
opencode mcp debug <name>第六，看 OMO doctor。
bunx oh-my-openagent doctor第七，看日志。OpenCode 日志、Desktop 日志、OMO 日志。不要只看 UI 上那句红字。
第八，回滚最近一处变更。不是重装。不是全删。是回滚最近一处。
这套顺序很笨，但能救命。
排障最怕的不是问题复杂。排障最怕的是你同时改五个变量，然后永远不知道是哪一个变量让系统坏了。
# 第十一章：三周新手村路线
如果你真想把 OpenCode 用到出神入化，不要收藏这篇就完了。
照着跑三周。
第一周，只练“壳”。
第一天，跑体检四件套。第二天，写 AGENTS.md。第三天，配置最小权限。第四天，接三根 MCP。第五天，跑一次 OMO doctor。第六天，用一个小任务完整走研究、计划、执行、验收。第七天，把所有踩坑写进 knowledge.md 或项目笔记。
第二周，练“分工”。
每天挑一个真实任务，先判断它是什么活，再派不同 agent/category。至少做一次外部文档查询，至少做一次本地代码探索，至少做一次只读 Oracle/Momus 审查。你的目标不是多快，而是让每个角色只干它该干的事。
第三周，练“验收”。
每次改动必须留下证据：改了什么，跑了什么，结果是什么，还有什么没验证。能写测试就写测试，能跑构建就跑构建，能手动走一遍就手动走一遍。第三周结束时，你应该能看着一份 agent 报告，分辨它是在交付，还是在表演。
三周以后，你再考虑 Team Mode。
那时候开团，才不是热闹。
是调兵。
# 最后一页：十二条铁律
一，配置改完不重启，等于没改。
二，AGENTS.md 不是文档，是法。
三，权限按事故半径设计，不按信任程度设计。
四，先本地，后外部。项目自己的知识库永远优先于互联网平均值。
五，凭据只进安全配置，不进文章，不进日志，不进仓库。
六，模型路由按任务类型，不按虚荣心。
七，fallback_models 只是候选；runtime_fallback 才是运行时动作。
八，MCP 是感官，不是玩具。接一根，就要知道它负责什么判定。
九，能让便宜判定拦住的问题，不要交给昂贵模型和人工。
十，多 agent 先分边界，再谈并行。
十一，Team Mode 默认关闭是美德，不是缺陷。
十二，任何交付，没有验证证据，就只是模型说了一段好听的话。
这十二条背下来，足够你走出新手村。
后面的路，没有标准答案。你会有自己的项目，自己的军团，自己的路由，自己的法典，自己的薄壳。
到那时候，你就会明白：所谓高手，不是工具比别人多。
是他让每一个工具，都站在了该站的位置上。