在 VS Code 中安装 OpenCode 插件并配置本地 AI 代码补全的方法。通过 Docker 部署 vLLM 服务运行 Qwen3-4B-Instruct 模型，实现离线推理与隐私保护。内容包括环境准备、插件安装、配置文件编写及实际代码生成演示，支持终端原生体验与多模型接入，适合追求数据安全与高效编码的开发者。
随着 AI 编程助手的快速发展，开发者对高效、安全、可定制化工具的需求日益增长。OpenCode 作为开源的 AI 编程框架，凭借其'终端优先、多模型支持、隐私安全'的设计理念，迅速在开发者社区中获得关注。它不仅支持主流云端大模型如 GPT、Claude、Gemini，还允许接入本地运行的模型（如通过 Ollama 部署的 Qwen3-4B-Instruct），真正实现离线可用、代码不外泄。
本文将重点介绍如何在 VS Code 中安装并配置 OpenCode 插件，并结合 vLLM 部署本地推理服务，启用基于 Qwen3-4B-Instruct 的智能代码补全功能。
OpenCode 采用典型的 C/S 架构，核心 Agent 运行于本地或远程服务器，VS Code 等 IDE 通过插件与其通信。这种设计带来三大优势：
OpenCode 内置基于 Terminal UI（TUI）的交互界面，使用 Tab 键即可在 build（代码生成）和 plan（项目规划）两种 Agent 模式间切换。其亮点包括：
/refactor 触发代码重构建议；OpenCode 最大的灵活性体现在模型接入能力上：
对于重视数据安全的团队和个人，OpenCode 提供了强有力的保障：
社区已贡献超过 40 个高质量插件，涵盖：
所有插件均可通过命令一键安装，极大扩展了功能边界。
首先确保系统已安装以下工具：
# Ubuntu/Debian 示例
sudo apt update && sudo apt install -y docker.io docker-compose git
启动 Docker 服务并添加当前用户至 docker 组：
sudo systemctl start docker
sudo usermod -aG docker $USER
注意：执行完后需重新登录终端以使权限生效。
拉取 vLLM 镜像并运行 Qwen3-4B 模型服务：
docker run -d --gpus all --shm-size="1g" \
-p 8000:8000 \
-e MODEL="Qwen/Qwen3-4B-Instruct" \
vllm/vllm-openai:latest \
--host 0.0.0.0 \
--port 8000 \
--dtype auto \
--max-model-len 32768
该命令将在本地启动一个 OpenAI 兼容的 API 服务，地址为 http://localhost:8000/v1，可用于后续 OpenCode 配置。
验证服务是否正常运行：
curl http://localhost:8000/v1/models
预期返回包含 Qwen3-4B-Instruct 模型信息的 JSON 响应。
打开 VS Code，进入扩展市场（Extensions Marketplace），搜索关键词 OpenCode，找到官方插件（Publisher: opencode-ai）并点击安装。
或者使用命令行方式安装：
code --install-extension opencode-ai.opencode
安装完成后重启 VS Code。
首次使用时，插件会提示初始化 Agent。选择'Local Server'模式，系统将自动下载并运行 OpenCode 服务容器：
docker run -d --name opencode-server \
-p 3000:3000 \
-v ~/.opencode:/root/.opencode \
opencode-ai/opencode:latest
等待容器启动后，插件将连接至本地 Agent 服务，默认监听端口为 3000。
在目标项目的根目录下创建 opencode.json 配置文件，内容如下：
{
"$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"
}
}
}
}
}
此配置指定了模型提供者为本地 vLLM 服务，Base URL 指向 http://localhost:8000/v1，确保 OpenCode 能正确调用 Qwen3-4B 模型进行推理。
保存配置后，在任意代码文件中输入部分函数名或注释描述，例如：
# 实现一个快速排序算法
def quicksort(arr):
稍等片刻，OpenCode 将自动弹出补全建议，点击接受即可插入完整实现。你也可以手动触发补全操作：
Ctrl + EnterOpenCode: Generate Code from Context此外，右键菜单中也集成了多项 AI 辅助功能，如'解释代码'、'生成单元测试'、'重构选中代码'等。
在一个 Python 项目中输入以下注释：
# 创建一个 Flask 应用，提供/users GET 和 POST 接口，用户数据包含 id, name, email 字段
调用 OpenCode 生成代码后，输出示例：
from flask import Flask, request, jsonify
app = Flask(__name__)
users = []
@app.route('/users', methods=['GET'])
def get_users():
return jsonify(users)
@app.route('/users', methods=['POST'])
def create_user():
data = request.get_json()
user = {
'id': len(users) + 1,
'name': data['name'],
'email': data['email']
}
users.append(user)
return jsonify(user), 201
if __name__ == '__main__':
app.run(debug=True)
整个过程无需联网调用公有云模型，全部在本地完成，保障了业务逻辑的安全性。
当代码存在潜在错误时，OpenCode 可通过静态分析提出改进建议。例如：
def divide(a, b):
return a / b
Agent 会提示：'检测到除法操作未处理 b=0 的情况，建议添加异常捕获。'并给出修复方案：
def divide(a, b):
try:
return a / b
except ZeroDivisionError:
raise ValueError("除数不能为零")
| 问题 | 解决方案 |
|---|---|
| 插件无法连接 Agent | 检查 Docker 容器是否运行，确认端口 3000 未被占用 |
| 补全响应缓慢 | 确保 GPU 驱动正常，vLLM 容器已正确挂载 GPU |
| 模型返回格式错误 | 检查 baseURL 是否正确指向 vLLM 的 /v1 接口 |
| Token 超限 | 调整 vLLM 启动参数 --max-model-len 至更高值 |
--enable-prefix-caching 提升长上下文处理效率；--max-num-seqs 避免内存溢出；本文详细介绍了如何在 VS Code 中集成 OpenCode 插件，并结合 vLLM 本地部署 Qwen3-4B-Instruct 模型，打造一个安全、高效、可定制的 AI 编程环境。OpenCode 的核心优势在于：
opencode.json 文件，实现精细化模型管理；
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online