第十章：最佳实践、完整配置模板与排障

第十章：最佳实践、完整配置模板与排障

最后一章把前九章的知识落地：给出可直接套用的完整配置模板（个人版 / 团队版 / 省钱极致版），汇总日常最佳实践，并提供排障与企业管控、学习路线指引。

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 的反馈不断微调，逐步打磨出最适合你和团队的那一套配置。

posted @ 2026-06-04 07:25  我才是银古  阅读(11)  评论(0)    收藏  举报