第十章：最佳实践、完整配置模板与排障
最后一章把前九章的知识落地：给出可直接套用的完整配置模板（个人版 / 团队版 / 省钱极致版），汇总日常最佳实践，并提供排障与企业管控、学习路线指引。
10.1 完整配置模板
以下模板均可直接复制、按需删改。务必保留 $schema 以获得编辑器校验与补全。
模板 A：个人通用（均衡型）
适合大多数日常开发，质量与成本兼顾。
{"$schema": "https://opencode.ai/config.json",// 模型：主力 Sonnet，轻量任务用 Haiku"model": "anthropic/claude-sonnet-4-5","small_model": "anthropic/claude-haiku-4-5",// 默认从规划开始，避免乱改"default_agent": "plan",// 上下文压缩与裁剪（省 Token 底座）"compaction": { "auto": true, "prune": true, "reserved": 10000 },// 提示缓存"provider": {"anthropic": { "options": { "setCacheKey": true } }},// 启用 LSP 与格式化，减少返工"lsp": true,"formatter": true,// 自动更新"autoupdate": true
}
TUI 部分（主题、键位、提醒）：
{"$schema": "https://opencode.ai/tui.json","theme": "tokyonight","attention": { "enabled": true, "notifications": true, "sound": true, "volume": 0.4 }
}
模板 B：省钱极致（成本优先）
把第九章的策略开满，适合大量、可容错的杂活。
{"$schema": "https://opencode.ai/config.json","model": "anthropic/claude-sonnet-4-5","small_model": "anthropic/claude-haiku-4-5","default_agent": "plan","compaction": { "auto": true, "prune": true, "reserved": 12000 },"provider": {"anthropic": {"options": { "setCacheKey": true },"models": {"claude-sonnet-4-5-20250929": {"options": { "thinking": { "type": "enabled", "budgetTokens": 8000 } }}}}},// 关掉不常用、又费 Token 的能力"permission": {"websearch": "deny"},// 分层用模：规划/审查/检索走便宜模型，实现走强模型"agent": {"plan": { "model": "anthropic/claude-haiku-4-5", "steps": 15 },"build": { "model": "anthropic/claude-sonnet-4-5", "steps": 25 },"review": {"description": "只读代码审查","mode": "subagent","model": "anthropic/claude-haiku-4-5","permission": { "edit": "deny" }}},// 大仓库降噪"watcher": { "ignore": ["node_modules/**", "dist/**", ".git/**"] }
}
如需进一步归零费用，把杂活 Agent 指向本地模型：
{"provider": {"ollama": {"npm": "@ai-sdk/openai-compatible","name": "Ollama (local)","options": { "baseURL": "http://localhost:11434/v1" },"models": { "qwen2.5-coder": { "name": "Qwen2.5 Coder (local)" } }}},"agent": {"docs": { "mode": "subagent", "model": "ollama/qwen2.5-coder", "permission": { "bash": "deny" } }}
}
模板 C：团队 / 项目级（提交进 Git）
放在项目根 opencode.json，与全局配置自动合并。聚焦项目专属设置与安全边界。
{"$schema": "https://opencode.ai/config.json",// 项目统一模型（团队一致）"model": "anthropic/claude-sonnet-4-5",// 复用既有规则文件"instructions": ["CONTRIBUTING.md", "docs/guidelines.md", "packages/*/AGENTS.md"],// 安全边界：危险命令禁止，常规命令放行"permission": {"bash": {"*": "ask","git *": "allow","npm *": "allow","git push *": "deny","rm -rf *": "deny"},"read": { "*": "allow", "*.env": "deny", "*.env.*": "deny" }},// 项目需要的 MCP（按需开启，注意 Token 成本）"mcp": {},// 团队不希望误开自动分享"share": "manual"
}
配合项目根的
AGENTS.md（用/init生成并提交）与.opencode/commands/、.opencode/agents/，整个团队就拥有了一致、可版本化的 OpenCode 工作台。
10.2 日常最佳实践
工作流
- 先规划后实现：
plan模式确认方案 →build模式落地，减少昂贵返工。 - 一个任务一个会话：完成即
/new；里程碑后/compact收敛上下文。 - 精准上下文：用
@文件引用相关文件，用@explore/@scout隔离检索调研。 - 善用撤销：结果不对就
/undo，调整提示再来；可连续多次回退。
配置
- 全局放偏好，项目放专属：利用「合并而非替换」，避免重复。
- 密钥与大段提示词外置：用
{env:...}/{file:...}变量替换，避免泄露与杂乱。 - 配置改完先验证：
opencode debug config看最终合并结果。 - 保留
$schema：获得实时校验与补全。
成本
- 分层用模 + 变体调档：杂活便宜模型、难题强模型，
ctrl+t临时升降推理强度。 - 开启压缩、裁剪与缓存：
compaction与setCacheKey是默认底座。 - 克制 MCP 与工具：只开必需，其余禁用，避免常驻上下文成本。
- 定期复盘：
opencode stats数据驱动持续优化（见第九章清单）。
10.3 排障速查
日志与数据位置
- 日志：macOS/Linux 在
~/.local/share/opencode/log/；Windows 在%USERPROFILE%\.local\share\opencode\log。保留最近 10 个日志文件。 - 详细日志：
opencode --log-level DEBUG，或opencode --print-logs在终端看输出。 - 数据存储：
~/.local/share/opencode/，含auth.json（密钥/令牌）、log/、project/（会话与消息）。
常见问题
| 现象 | 排查步骤 |
|---|---|
| 启动失败 | 看日志；opencode --print-logs；opencode upgrade 升级到最新版 |
| 认证失败 | 用 /connect 重新认证；确认密钥有效；确认网络可达 Provider API |
模型不可用 / ProviderModelNotFoundError |
确认已认证；核对模型名格式为 providerId/modelId；opencode models 看可用模型 |
ProviderInitError |
配置可能损坏；按 providers 文档重配；必要时 rm -rf ~/.local/share/opencode 后重新 /connect |
AI_APICallError / provider 包问题 |
清缓存 rm -rf ~/.cache/opencode 后重启，强制重装最新 provider 包 |
| Linux 复制粘贴失效 | 安装剪贴板工具（X11 装 xclip，Wayland 装 wl-clipboard） |
| 本地模型工具调用不工作 | 增大 Ollama 的 num_ctx（16k–32k 起步） |
清理
~/.local/share/opencode会删除会话与认证数据，属较重操作，确认后再执行。
10.4 企业级管控（了解）
组织可通过以下机制下发不可被用户覆盖的配置（优先级最高）：
- 远程配置：
.well-known/opencode端点提供组织默认值（最底层，可被覆盖）。 - 托管配置文件：放在系统目录（macOS
/Library/Application Support/opencode/、Linux/etc/opencode/、Windows%ProgramData%\opencode），需管理员权限。 - macOS 托管偏好：通过 MDM（Jamf / Kandji / FleetDM）下发
.mobileconfig，读取ai.opencode.managed偏好域，用户不可覆盖。 - 策略（policies）：
experimental.policies可允许/禁止某些动作，例如禁止使用某个 Provider：
{"$schema": "https://opencode.ai/config.json","experimental": {"policies": [{ "effect": "deny", "action": "provider.use", "resource": "openai" }]}
}
用 opencode debug config 可验证哪些托管键已生效。
10.5 学习路线回顾
- 入门（1–3 章）：理解定位 → 安装接入 → 熟悉界面与会话。
- 配置基础（4–5 章）：吃透配置体系与优先级 → 掌握模型与 Provider。
- 深度定制（6–8 章）：自定义 Agent → 命令/规则/Skill → 工具/权限/MCP。
- 最优化（9–10 章）：系统化 Token 优化 → 套用完整模板与最佳实践。
若你的核心诉求是「更省、更快」，主线是第 4 → 5 → 6 → 9 → 10 章；其中第九章的清单与本章的模板可直接落地到你的 opencode.json。
10.6 结语
OpenCode 把「模型自由、配置即代码、成本可控」三件事做成了可组合的显式能力。掌握了本教程的配置体系与优化策略后，你不仅能让它更懂你的项目，还能以更省 Token、更高效的方式持续使用它。建议把第十章的模板作为起点，结合 opencode stats 的反馈不断微调，逐步打磨出最适合你和团队的那一套配置。