第十章：最佳实践、完整配置模板与排障
最后一章把前九章的知识落地：给出可直接套用的完整配置模板（个人版 / 团队版 / 省钱极致版），汇总日常最佳实践，并提供排障与企业管控、学习路线指引。
10.1 完整配置模板
以下模板均可直接复制、按需删改。务必保留 $schema 以获得编辑器校验与补全。
模板 A：个人通用（均衡型）
适合大多数日常开发，质量与成本兼顾。
```jsonc title=”~/.config/opencode/opencode.jsonc” { “$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 部分（主题、键位、提醒）：
```json title="~/.config/opencode/tui.json"
{
"$schema": "https://opencode.ai/tui.json",
"theme": "tokyonight",
"attention": { "enabled": true, "notifications": true, "sound": true, "volume": 0.4 }
}
模板 B：省钱极致（成本优先）
把第九章的策略开满，适合大量、可容错的杂活。
```jsonc title=”opencode.jsonc” { “$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 指向本地模型：
```json title="opencode.json（片段）"
{
"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，与全局配置自动合并。聚焦项目专属设置与安全边界。
```jsonc title=”opencode.jsonc（项目根，提交进 Git）” { “$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：
```json title="opencode.json"
{
"$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 的反馈不断微调，逐步打磨出最适合你和团队的那一套配置。