opencode JSON配置文件详解：opencode.json参数设置说明
1. OpenCode 是什么：终端里的编程搭档
你有没有试过在写代码时，突然卡在某个函数调用上，翻文档、查 Stack Overflow、反复调试，一晃半小时过去了？OpenCode 就是为解决这种“卡点时刻”而生的——它不是另一个网页版 AI 编程工具，而是一个真正扎根在你终端里的、可随身携带的编程搭档。
它用 Go 写成，轻量、快、稳，启动只要 0.3 秒；不依赖浏览器，不上传代码，不联网也能跑；支持你在 VS Code 里调用，也能在 iTerm 里直接敲命令启动。更关键的是，它不绑定某一家大厂模型——你可以今天用本地跑的 Qwen3-4B-Instruct-2507，明天切到 Ollama 的 Llama-3.2-3B，后天换成远程的 Claude Sonnet，全程只需改一个 JSON 文件，不用重装、不用重启、不丢上下文。
一句话说透它的定位：不是“AI 写代码”，而是“你写代码时，背后站着一个懂你项目、守你隐私、随时待命的资深结对程序员”。
它没有花哨的 UI，但 Tab 切换间就能在「代码构建模式」和「项目规划模式」自由切换；它不收集你的 repo，但能基于你当前目录结构，精准理解 import 链路和函数依赖；它不存聊天记录，但每个会话的上下文都隔离在内存里，关掉终端就彻底清空。
这就是 OpenCode —— 不喧哗，但有回响；不取巧，但够实在。
2. 为什么需要 opencode.json：配置即能力
OpenCode 本身是个“空壳”——它不自带模型，也不硬编码任何 API 密钥或服务地址。所有智能能力，都来自你亲手写的opencode.json。这个文件，就是你给 OpenCode 下达的“作战指令集”。
它不像.env那样只填几个变量，也不像docker-compose.yml那样堆砌服务定义。它是一份面向开发者意图的声明式配置：你告诉 OpenCode “我要用哪个模型供应商”、“它叫什么名字”、“从哪访问”、“支持哪些具体模型”，它就自动完成 SDK 加载、连接初始化、路由分发、错误降级等全部底层工作。
换句话说：
没有opencode.json→ OpenCode 启动后只能显示欢迎页，无法调用任何模型；
有opencode.json但格式错 → 启动报错，提示缺失字段或类型不符；
配置正确但 baseURL 不通 → 自动 fallback 到离线提示，不崩溃、不卡死；
多个 provider 并存 → 可在 TUI 界面中实时切换，不同会话可绑定不同模型。
所以，别把它当成“可选配置”，它是 OpenCode 的能力开关、模型入口、安全边界——写对了，它默默干活；写错了，它立刻提醒；删掉了，它干脆不启动核心功能。
3. opencode.json 核心结构逐层解析
3.1 整体骨架：schema + provider 是唯二必需字段
一个合法的opencode.json至少包含两个顶层字段：$schema和provider。其他字段全可省略，但这两个缺一不可。
{ "$schema": "https://opencode.ai/config.json", "provider": { "myprovider": { "npm": "@ai-sdk/openai-compatible", "name": "qwen3-4b", "options": { "baseURL": "http://localhost:8000/v1" }, "models": { "Qwen3-4B-Instruct-2507": { "name": "Qwen3-4B-Instruct-2507" } } } } }$schema：不是校验用的摆设。OpenCode 启动时会主动 fetch 这个 URL，获取最新版 JSON Schema 定义，用于实时校验配置合法性。如果你离线，它会使用内置缓存版本，不影响使用。provider：必须是非空对象。键名（如"myprovider"）是你自定义的供应商代号，后续在 TUI 或 CLI 中切换模型时就用它；值对象才是真正的配置主体。
小技巧：键名建议用小写字母+短横线，比如
local-qwen、ollama-coder、remote-claude，避免空格和特殊字符，方便命令行识别。
3.2 provider 内部字段详解：npm、name、options、models 四要素
每个 provider 对象必须包含以下四个字段，它们共同构成一个“可运行的模型接入单元”：
| 字段 | 类型 | 是否必需 | 说明 | 常见值示例 |
|---|---|---|---|---|
npm | string | 指定使用的 AI SDK 包名。OpenCode 通过它动态加载对应适配器 | "@ai-sdk/openai-compatible","@ai-sdk/anthropic","@ai-sdk/google" | |
name | string | 该 provider 的显示名称，在 TUI 界面顶部状态栏可见 | "Qwen Local","Claude Pro","Gemini Flash" | |
options | object | 传递给 SDK 的初始化参数。不同 npm 包支持的字段不同 | { "baseURL": "http://localhost:8000/v1", "apiKey": "sk-..." } | |
models | object | 声明该 provider 支持的具体模型列表。键为模型 ID（供 CLI 调用），值为模型配置对象 | { "Qwen3-4B-Instruct-2507": { "name": "Qwen3-4B-Instruct-2507" } } |
重点说明options和models：
options中的baseURL是 vLLM、Ollama、LM Studio 等本地推理服务的通用入口。只要服务暴露/v1/chat/completions接口，OpenCode 就能对接。models的键（如"Qwen3-4B-Instruct-2507"）就是你在终端里执行opencode --model Qwen3-4B-Instruct-2507时用的名字；其值对象中的name字段，则是实际发送给后端的model=参数值——二者可以不同，实现“别名映射”。
3.3 models 配置进阶：支持别名、温度、最大输出长度
models下每个模型对象，除了必填的name，还支持多个可选字段，用于精细化控制生成行为：
"Qwen3-4B-Instruct-2507": { "name": "Qwen3-4B-Instruct-2507", "temperature": 0.3, "maxTokens": 2048, "topP": 0.9, "presencePenalty": 0.1, "frequencyPenalty": 0.1 }temperature：控制随机性。0.0 = 最确定（适合代码补全），0.7 = 较平衡（适合解释代码），1.0 = 最发散（适合创意提示）。默认为 0.5。maxTokens：单次响应最大 token 数。Qwen3-4B 默认上下文窗口为 32K，但本地显存有限，建议设为 1024–4096 之间，避免 OOM。topP：核采样阈值。0.9 是较稳妥的选择，兼顾多样性与合理性。presencePenalty/frequencyPenalty：抑制重复词。写文档或注释时设为 0.2–0.5，写代码时建议保持 0.0–0.1，避免误罚合法变量名。
注意：这些参数只影响当前模型实例。你可以为同一个
baseURL配置多个模型条目，各自设不同温度，比如："qwen-coding": { "name": "Qwen3-4B-Instruct-2507", "temperature": 0.1 }, "qwen-explain": { "name": "Qwen3-4B-Instruct-2507", "temperature": 0.7 }在 TUI 中就能一键切换“专注写码”和“耐心讲解”两种模式。
4. 实战配置：vLLM + OpenCode 打造本地 AI Coding 环境
4.1 环境准备：三步启动 vLLM 服务
要让 OpenCode 调用 Qwen3-4B-Instruct-2507，先得让它“活”起来。推荐用 vLLM —— 启动快、显存省、吞吐高，且原生兼容 OpenAI API 格式。
# 1. 拉取模型（需 HuggingFace Token） huggingface-cli download --token YOUR_HF_TOKEN \ Qwen/Qwen3-4B-Instruct-2507 \ --local-dir ./qwen3-4b-instruct # 2. 启动 vLLM（假设 24G 显存，启用 PagedAttention） CUDA_VISIBLE_DEVICES=0 vllm serve \ --model ./qwen3-4b-instruct \ --host 0.0.0.0 \ --port 8000 \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.95 \ --enable-prefix-caching # 3. 测试接口（终端另开） curl http://localhost:8000/v1/models # 返回 {"object":"list","data":[{"id":"Qwen3-4B-Instruct-2507","object":"model"}]}成功标志：访问http://localhost:8000/v1/models返回模型列表，且Qwen3-4B-Instruct-2507在其中。
4.2 opencode.json 完整配置（含注释）
把下面这段保存为项目根目录下的opencode.json，即可开箱即用：
{ "$schema": "https://opencode.ai/config.json", "provider": { "local-qwen": { "npm": "@ai-sdk/openai-compatible", "name": "Qwen3-4B Local", "options": { "baseURL": "http://localhost:8000/v1", "apiKey": "EMPTY" }, "models": { "qwen-coding": { "name": "Qwen3-4B-Instruct-2507", "temperature": 0.1, "maxTokens": 1536, "topP": 0.85 }, "qwen-debug": { "name": "Qwen3-4B-Instruct-2507", "temperature": 0.3, "maxTokens": 2048, "topP": 0.9, "presencePenalty": 0.2 } } } } }关键细节说明：
"apiKey": "EMPTY"是 vLLM 的固定占位符，不填或填错会导致 401 错误；qwen-coding温度低、输出短，适合函数补全、变量命名、语法纠错；qwen-debug温度稍高、输出长，适合生成错误分析、修复建议、单元测试用例；- 所有字段名严格区分大小写，
"maxTokens"不能写成"max_tokens"。
4.3 启动与验证：从命令行到 TUI 全流程
配置好后，进入项目目录，执行：
# 启动 OpenCode（自动读取当前目录 opencode.json） opencode # 或指定模型启动（跳过 TUI，直接进入对话） opencode --model qwen-coding # 查看当前可用模型列表 opencode --list-models # 输出： # local-qwen/qwen-coding Qwen3-4B Local (Qwen3-4B-Instruct-2507) # local-qwen/qwen-debug Qwen3-4B Local (Qwen3-4B-Instruct-2507)在 TUI 界面中：
- 按
Tab切换「Build」（代码构建）和「Plan」（项目规划）Agent； - 按
Ctrl+P弹出模型选择菜单，输入qwen-debug即可切换； - 输入
/help查看所有快捷指令，如/file path/to/main.py让它读取并分析文件。
验证成功标志：输入请帮我把这段 Python 函数改成异步版本，它能准确识别def关键字，添加async/await，保留原有 docstring 和类型注解，并给出修改说明。
5. 常见问题与避坑指南
5.1 启动报错：“Failed to load provider: invalid schema”
原因：$schema字段缺失、拼写错误（如写成$schma），或网络不通导致无法获取 Schema。
解决：
- 检查是否漏掉
$符号； - 确保值是完整 URL，不是相对路径；
- 若离线使用，可临时注释
$schema行（仅限调试，生产环境务必保留）。
5.2 模型列表为空，TUI 中看不到模型选项
原因：provider下的键名是空对象{}，或models字段缺失/为空。
解决：
- 运行
opencode --list-models，确认输出是否为空； - 检查
models是否为{}或null； - 确认
models的键名是否符合正则^[a-zA-Z0-9_-]+$（不能含空格、中文、点号）。
5.3 调用时卡住，日志显示 “connection refused”
原因：baseURL地址错误，或 vLLM 服务未启动/端口被占。
解决：
- 用
curl -v http://localhost:8000/v1/models手动测试； - 检查 vLLM 日志是否有
INFO: Uvicorn running on http://0.0.0.0:8000； - 若用 Docker 启动 vLLM，确保
--network host或正确映射-p 8000:8000。
5.4 生成结果乱码、截断、不相关
原因：maxTokens设置过小，或temperature过高导致失控。
解决：
- 先将
maxTokens提高到 3072，观察是否仍截断； - 将
temperature降至 0.1，测试基础补全是否稳定； - 检查 vLLM 启动参数是否加了
--enforce-eager（某些显卡需开启）。
5.5 想同时用本地 Qwen 和远程 Claude，怎么配？
答案：provider是对象，天然支持多供应商。只需在provider下增加第二个键：
"provider": { "local-qwen": { ... }, "remote-claude": { "npm": "@ai-sdk/anthropic", "name": "Claude Sonnet", "options": { "apiKey": "your-anthropic-key" }, "models": { "claude-3-5-sonnet": { "name": "claude-3-5-sonnet-20241022" } } } }启动后，opencode --model claude-3-5-sonnet即可调用远程模型，无需重启服务。
6. 总结：一份配置，三种掌控力
写完这篇，你应该已经清楚：opencode.json远不止是一个“填参数的表单”。它是一份开发者主权声明——
- 掌控模型选择权：不再被平台绑定，Qwen、Llama、Claude、Gemini，按需切换，成本透明；
- 掌控数据主权：代码永远留在本地，上下文不上传，
baseURL指向自己机器，安全由自己定义； - 掌控体验定制权：温度、长度、采样策略，每个模型可独立调优，让 AI 更贴合你的编码节奏。
它没有炫酷的图形界面，但每行 JSON 都是你对开发流的重新设计；它不承诺“100% 正确”，但保证“100% 可控”。当你在深夜调试一个棘手 bug，敲下opencode --model qwen-debug，看到它精准定位到那行少写的await，并附上三行修复建议——那一刻，你会明白：所谓 AI 编程助手，不是替代你思考，而是把思考的带宽，还给你自己。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
