叶云梦天

OpenCode 模型提供商配置与自定义 Agent 实战指南

在上一篇文章中，我们介绍了 OpenCode 的安装方法。安装只是第一步，真正让 OpenCode 发挥威力的关键在于模型提供商的选择和自定义 Agent 的配置。OpenCode 支持 75+ 个 LLM 提供商，并允许你创建高度定制化的 Agent 来应对不同场景。本文将从实际使用角度出发，带你一步步完成配置。

一、模型提供商配置

OpenCode 的提供商系统非常灵活，支持云端 API、本地模型、企业级部署等多种方式。

1.1 使用 `/connect` 快速配置

最简便的方式是在 TUI 中输入 /connect 命令，然后从列表中选择你想要的提供商。目前支持的主流提供商包括：

OpenAI — 支持 ChatGPT Plus/Pro 订阅和 API Key 两种方式
Anthropic — 支持 Claude Pro/Max 订阅
GitHub Copilot — 用你的 Copilot 订阅直接使用
DeepSeek — 国内开发者常用的高性价比选择
OpenRouter — 聚合多个模型，灵活切换

选择后按提示完成认证即可。

1.2 通过配置文件管理提供商

对于需要精细控制的项目，推荐直接在 opencode.json 中配置：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000
      }
    }
  },
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

small_model 用于标题生成等轻量任务，能有效节约 API 费用。

1.3 本地模型配置

如果你想完全离线使用，可以配置 Ollama、LM Studio 或 llama.cpp 等本地推理引擎：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:a3b": {
          "name": "Qwen3-Coder"
        }
      }
    }
  }
}

本地模型适合处理敏感代码或节省服务器费用，但需要注意模型对工具调用的支持能力。推荐使用 Qwen-Coder 或 DeepSeek-Coder 系列，它们在结构化输出方面表现较好。

1.4 模型筛选与白名单

当某个提供商暴露了太多模型，你可以用 whitelist 或 blacklist 来精简列表：

{
  "provider": {
    "anthropic": {
      "whitelist": ["claude-sonnet-4-20250514"]
    }
  }
}

这在团队环境中特别有用，可以避免开发者选错模型。

1.5 模型配置与变体

OpenCode 支持对同一模型配置不同参数变体：

{
  "provider": {
    "openai": {
      "models": {
        "gpt-5": {
          "options": {
            "reasoningEffort": "high",
            "textVerbosity": "low"
          },
          "variants": {
            "fast": {
              "reasoningEffort": "low"
            },
            "deep": {
              "reasoningEffort": "high",
              "reasoningSummary": "auto"
            }
          }
        }
      }
    }
  }
}

通过快捷键可以在不同变体间快速切换，灵活应对不同任务。

二、自定义 Agent 实战

Agent 是 OpenCode 最强大的功能之一。你可以为代码审查、文档编写、安全审计等特定任务创建专门的 Agent。

2.1 内置 Agent 概览

OpenCode 内置了多种 Agent：

| Agent | 类型 | 用途 |
|-------|------|------|
| Build | primary | 默认开发 Agent，拥有全部工具权限 |
| Plan | primary | 计划和分析模式，只读不写 |
| General | subagent | 通用子 Agent，可执行多步任务 |
| Explore | subagent | 快速只读探索代码库 |
| Scout | subagent | 只读查阅外部文档和依赖 |

通过 Tab 键在主 Agent 之间切换，通过 @ 提及来调用子 Agent。

2.2 创建自定义 Agent

#### 方式一：JSON 配置

在 opencode.json 中直接定义：

{
  "agent": {
    "code-reviewer": {
      "description": "代码审查，关注安全性和性能",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.1,
      "prompt": "你是一名资深的代码审查专家。请重点关注：\n1. 安全漏洞和输入验证\n2. 性能瓶颈和潜在问题\n3. 代码可维护性和最佳实践\n4. 边界条件和错误处理",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

#### 方式二：Markdown 文件

在 .opencode/agents/ 或 ~/.config/opencode/agents/ 目录下创建 .md 文件：

.opencode/agents/debug.md

---
description: 调试助手，专注于问题排查
mode: subagent
model: anthropic/claude-haiku-4-5
permission:
  bash:
    "*": "ask"
  edit: "deny"
---

你是一名调试专家。分析错误信息，定位问题根源，提供修复建议。
首先使用 bash 工具查看日志和运行时状态，然后给出排查步骤。

文件名即为 Agent 名称，在会话中可通过 @debug 调用。

2.3 细粒度权限控制

OpenCode 的权限系统非常灵活，支持按工具类型甚至具体命令进行控制：

{
  "agent": {
    "safe-build": {
      "mode": "primary",
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "npm test": "allow",
          "git diff": "allow",
          "git status": "allow"
        }
      }
    }
  }
}

上面的配置让 Agent 在执行 npm test、git diff 等安全命令时无需确认，而其他 bash 命令则需要手动批准。

2.4 使用 `opencode agent create` 命令

OpenCode 还提供了交互式命令来创建 Agent：

opencode agent create

它会依次询问：

保存位置（全局或项目级）

Agent 的描述

自动生成合适的 system prompt

选择允许的权限

输出 Markdown 配置文件

这是新手入门的最佳方式。

三、多模型协作策略

在实际开发中，不同任务适合不同的模型。你可以通过 Agent 配置实现多模型协作：

规划阶段：使用低成本模型（如 Claude Haiku）进行快速分析和计划
编码阶段：切换到高性能模型（如 Claude Sonnet 或 GPT-5）生成代码
审查阶段：使用专门的审查 Agent，配合低温度参数确保严谨性
文档阶段：使用创造性稍高的模型参数，生成更自然的技术文档

通过 subagent_depth 配置可以控制子 Agent 的嵌套深度：

{
  "subagent_depth": 2
}

默认值为 1，允许主 Agent 调用子 Agent，但不允许子 Agent 再嵌套调用。

四、实用技巧

4.1 环境变量注入

在配置文件中引用环境变量，避免硬编码敏感信息：

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

4.2 关闭不需要的提供商

如果你配置了多个提供商但只想用其中几个，可以用 enabled_providers 进行限制：

{
  "enabled_providers": ["anthropic", "openai"]
}

4.3 自定义提示词文件

将 Agent 的 prompt 放在独立文件中管理：

{
  "agent": {
    "code-reviewer": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

保持配置文件的整洁，也方便团队共享和版本控制。

总结

本文从模型提供商配置和自定义 Agent 两个核心维度，介绍了 OpenCode 的高级用法。通过灵活配置提供商、精心设计 Agent，你可以把 OpenCode 打造成真正适配自己工作流的 AI 编程助手。

关键要点回顾：

用 /connect 快速添加提供商，用 opencode.json 精细管理
内置 Agent 满足常见需求，自定义 Agent 覆盖特定场景
权限控制支持从粗粒度到细粒度的灵活配置
多模型协作策略能兼顾效率和质量

下一篇文章将介绍 OpenCode 的 MCP 服务器集成与自定义工具开发，敬请期待。

OpenCode 模型提供商配置与自定义 Agent 实战指南

OpenCode 模型提供商配置与自定义 Agent 实战指南

一、模型提供商配置

1.1 使用 /connect 快速配置

1.2 通过配置文件管理提供商

1.3 本地模型配置

1.4 模型筛选与白名单

1.5 模型配置与变体

二、自定义 Agent 实战

2.1 内置 Agent 概览

2.2 创建自定义 Agent

2.3 细粒度权限控制

2.4 使用 opencode agent create 命令

三、多模型协作策略

四、实用技巧

4.1 环境变量注入

4.2 关闭不需要的提供商

4.3 自定义提示词文件

总结

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客

1.1 使用 `/connect` 快速配置

2.4 使用 `opencode agent create` 命令