还在古法编程？免费使用AI编程助手OpenCode 与完全本地化配置

OpenCode 是 Claude Code 的平替------完全开源、免费(白嫖)Token、支持本地模型，无需依赖昂贵的云端 API。开发者终于可以摆脱天价 Token 费用，在保障数据隐私的同时，享受高效、灵活的 AI 编程体验。

---

目录

• 前言
• LLM大模型配置
• [Docker 部署 Web UI / CLI 服务](#Docker 部署 Web UI / CLI 服务)
• [终端 CLI 与 VS Code 插件集成](#终端 CLI 与 VS Code 插件集成)
• [方案对比：Web UI vs 终端 CLI](#方案对比：Web UI vs 终端 CLI)
• 常见问题与安全建议
• 总结与最佳实践

---

前言

✨ OpenCode 核心特点

✅ 完全开源 --- MIT 许可，GitHub 超 109k Stars

✅ 零成本模型接入 --- 官方提供免费模型，也支持任意本地或云模型

✅ 纯本地运行 --- 数据不出内网，满足企业级安全合规要求

✅ 现代化 Web UI --- 无需命令行，开箱即用

✅ 广泛兼容性 --- 支持 llama.cpp、Ollama、vLLM、LM Studio 及所有 OpenAI 兼容 API

✅ 全周期开发能力 --- 深度集成代码生成、调试、测试、重构、回溯等场景

📌 核心理念：你的代码，只属于你。AI 能力，尽在掌控。

🔗 官方资源

• 官网：https://opencode.ai
• GitHub：https://github.com/anomalyco/opencode
• 配置文档：https://opencode.ai/docs/config

---

LLM大模型配置

OpenCode 支持大多 LLM 提供商，可根据需求灵活选择：

1. 官方免费模型（OpenCode Zen）

OpenCode 官方提供 Zen 模型服务，包含经过严格测试与优化的免费编码模型，无需配置即可使用：

✅ 适合快速上手、无本地 GPU 资源的用户

❌ 需联网，不适用于完全离线环境

---

2. 部署本地 LLM 服务

如果注重隐私或希望完全离线运行，推荐部署本地大模型。参考此前的文章《性能干翻235B，单卡私有化部署OpenClaw》，典型配置如下：

• 模型 ：Qwen3.5-35B-A3B-UD-Q4_K_M.gguf
  （MoE 架构，激活参数仅 3B，推理性能超越 Qwen3-235B）
• 推理后端 ：llama.cpp（以 server 模式运行）
• API 地址 ：http://10.0.0.10:8001/v1

验证服务是否正常：

curl http://10.0.0.10:8001/v1/models

预期返回包含模型 ID 的 JSON 列表。

⚠️ 注意：该地址需能被 OpenCode 容器访问。

---

3. 接入 OpenAI / Claude / Gemini 等云 API

OpenCode 同样支持主流云模型，只需提供 API Key：

💡 支持 75+ 模型提供商（通过 Models.dev），包括 Anthropic、Google、Mistral、DeepSeek 等。

---

Docker 部署 Web UI / CLI 服务

快速体验

docker run -d \
  --name opencode-quick \
  --restart unless-stopped \
  --entrypoint opencode \
  -p 3000:3000 \
  -v ./config:/root/.config/opencode \
  -v ./data:/root/.local/share/opencode \
  -v ./workspace:/workspace \
  -e WORKDIR=/workspace \
  ghcr.io/anomalyco/opencode:latest \
  web --hostname 0.0.0.0 --port 3000

• ./workspace：挂载项目代码（AI 可读写此目录）
• ./config：配置文件路径，存放 opencode.json 配置文件
• ./data：存储会话、缓存等运行时数据
• 🌐 访问：http://{宿主机ip}:3000

---

完整部署（推荐用于生产或长期使用）

1. 编写 Dockerfile

# --- Stage 1: Extraction ---
# Use the official uv image to provide the binaries.
FROM ghcr.io/astral-sh/uv:latest AS uv_bin

# --- Stage 2: Runtime Environment ---
# Using debian:bookworm-slim instead of full Ubuntu to significantly reduce image size
# while maintaining full compatibility with Python wheels and C-extensions.
FROM ubuntu:24.04

ARG LOCAL_TOOLS="curl ca-certificates git"

# Consolidate environment variables to reduce layers.
# UV_PYTHON_INSTALL_DIR: Ensures Python toolchains are stored in the persistent cache volume.
# UV_LINK_MODE: Set to 'copy' to avoid performance warnings on different filesystems.
# UV_PYTHON_PREFERENCE: Ensures uv respects .python-version from your workspace.
ENV DEBIAN_FRONTEND=noninteractive \
    HOME=/home/opencode \
    UV_PROJECT_ENVIRONMENT=/home/opencode/.venv \
    UV_CACHE_DIR=/home/opencode/.cache/uv \
    UV_PYTHON_INSTALL_DIR=/home/opencode/.cache/uv/python \
    UV_LINK_MODE=copy \
    UV_PYTHON_PREFERENCE=managed \
    PATH="/home/opencode/.opencode/bin:/home/opencode/.venv/bin:$PATH"

# Combine system update, dependency installation, user creation, and directory prep.
# This single RUN command reduces the number of intermediate image layers.
RUN apt-get update && apt-get install -y --no-install-recommends $LOCAL_TOOLS \
    && useradd -m -s /bin/bash opencode \
    && mkdir -p /home/opencode/.local/share/opencode \
                /home/opencode/.config/opencode \
                /home/opencode/.cache/uv \
                /home/opencode/.venv \
                /workspace \
    && chown -R opencode:opencode /home/opencode /workspace \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*



# Copy uv binaries from the extraction stage.
COPY --from=uv_bin /uv /uvx /bin/

# Copy the entrypoint script and set correct permissions
COPY --chown=opencode:opencode ./entrypoint.sh /home/opencode/entrypoint.sh
RUN chmod +x /home/opencode/entrypoint.sh

# Install the OpenCode CLI (before switching to non-root user)
# The installer automatically places the binary into $HOME/.opencode/bin.
RUN curl -fsSL https://opencode.ai/install | bash || \
    (echo "⚠️ OpenCode install failed, trying alternative method..." && \
    curl -fsSL https://github.com/opencode-ai/opencode/releases/latest/download/opencode-linux-x64 -o /home/opencode/.opencode/bin/opencode && \
    chmod +x /home/opencode/.opencode/bin/opencode)

# Run as root to allow apt-get and dpkg commands without sudo
USER root
WORKDIR /workspace

# Define the entrypoint script as the default execution path
ENTRYPOINT ["/home/opencode/entrypoint.sh"]

2. 编写 entrypoint.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status
set -e

# ============================================
# .NET 8 SDK 安装逻辑 (通过环境变量控制)
# ============================================
if [ "$INSTALL_DOTNET" = "true" ]; then
    echo "🛠️ [Entrypoint] .NET 8 SDK 安装模式已启用。"
    
    # 检查是否已安装 .NET SDK
    if command -v dotnet &> /dev/null; then
        echo "✅ [Entrypoint] .NET SDK 已安装，跳过安装。"
    else
        echo "📥 [Entrypoint] 开始安装 .NET 8 SDK..."
        
        # 安装依赖
        apt-get update
        apt-get install -y wget
        
        # 下载并安装 Microsoft APT 仓库配置
        wget https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
        dpkg -i packages-microsoft-prod.deb
        rm packages-microsoft-prod.deb
        
        # 安装 .NET SDK 8.0
        apt-get update
        apt-get install -y dotnet-sdk-8.0
        
        # 清理缓存
        apt-get clean
        rm -rf /var/lib/apt/lists/*
        
        echo "✅ [Entrypoint] .NET 8 SDK 安装完成！"
        echo "📌 版本信息："
        dotnet --version
    fi
else
    echo "⏭️ [Entrypoint] INSTALL_DOTNET 为 false。跳过 .NET SDK 安装。"
fi

# ============================================
# Python 依赖安装逻辑
# ============================================
if [ "$INSTALL_DEPS" = "true" ]; then
    echo "🛠️ [Entrypoint] 完整设置模式已启用。"

    # 初始化虚拟环境
    uv venv -q /home/opencode/.venv

    if [ -f "requirements.txt" ]; then
        echo "📦 [Entrypoint] 从 requirements.txt 安装依赖..."
        uv pip install -q -r requirements.txt
    elif [ -f "pyproject.toml" ]; then
        echo "📦 [Entrypoint] 从 pyproject.toml 同步依赖..."
        uv sync -q
    else
        echo "ℹ️ [Entrypoint] 未找到依赖文件，但已创建虚拟环境。"
    fi
else
    echo "⏭️ [Entrypoint] INSTALL_DEPS 为 false。跳过虚拟环境和依赖安装。"
fi

# ============================================
# 启动主应用
# ============================================
echo "🚀 [Entrypoint] 启动 OpenCode..."

# opencode
opencode web --hostname 0.0.0.0 --port 3000

3. 编写 docker-compose.yml

version: '3.8'

services:
  opencode:
    image: opencode-net:latest
    container_name: opencode-net
    restart: unless-stopped
    ports:
      - "3005:3000"
    volumes:
      - ./opencode/config:/home/opencode/.config/opencode
      - ./opencode/data:/home/opencode/.local/share/opencode
      - /data/ai/workspace:/workspace
    environment:
      - WORKDIR=/workspace
      # 设置 Git 用户信息，防止 AI 提交代码时报错
      - GIT_AUTHOR_NAME=opencode
      - GIT_AUTHOR_EMAIL=bot@opencode.ai
      # 如果 NAS 需要代理访问 OpenAI/Google，请取消注释以下行
      # - HTTP_PROXY=http://192.168.x.x:7890
      # - HTTPS_PROXY=http://192.168.x.x:7890
      #安装 requirements.txt 依赖
      - INSTALL_DEPS=false
      # 安装 .net sdk
      - INSTALL_DOTNET=false
    networks:
      - opencode_net

networks:
  opencode_net:
    driver: bridge

4. 打包镜像

docker build -t opencode-net:latest .

5. 启动服务

docker compose up -d

6. 配置模型接入（config/opencode.json）

{ 
  "$schema": "https://opencode.ai/config.json", 
  "provider": {
    "local-llama-cpp": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Llama.cpp Model Runner",
      "options": {
        "baseURL": "http://192.168.1.10:8001/v1",
        "apiKey": "not-needed"
      },
      "models": {
        "Qwen3.5-35B-A3B-UD-Q4_K_M": { 
          "name": "Qwen3.5-35B-A3B-UD-Q4_K_M",
          "limit": { "contextWindow": 128000, "maxOutputTokens": 64000, "context": 0, "output": 64000 }
        }
      }
    }
  }
}

7. 访问 Web 界面

打开浏览器访问：

👉 http://{宿主机ip}:3005

首次加载完成后，即可开始与 AI 协作编程

---

终端 CLI 与 VS Code 插件集成

CLI 安装与配置

## 在终端安装 cli
npm install -g opencode-ai

## 查看安装版本
opencode --version

## 运行
opecode

## 选择模型
/models

配置文件路径：

• Linux / macOS : ~/.config/opencode/opencode.json
• Windows : %USERPROFILE%\.config\opencode\opencode.json

💡 配置内容与上面config/opencode.json 完全一致，可直接复用。

VS Code 插件

安装插件 ：OpenCode

, 配置文件也是：~/.config/opencode/opencode.json

---

方案对比：Web UI vs 终端 CLI

使用方式	适用人群	特点
Web UI	非终端用户、教学演示	图形化界面，操作直观，支持文件浏览、聊天历史、权限确认弹窗
终端 CLI	高级用户、自动化脚本、CI/CD	命令行驱动，可嵌入工作流，支持管道输入输出
VS Code 插件	日常 IDE 用户	无缝集成编辑器，支持内联补全、右键操作、快捷指令

---

常见问题与安全建议

问题	原因	解决方案
模型连接失败	容器无法解析 localhost	Linux 下使用宿主机内网 IP（如 10.0.0.10）；检查防火墙
页面空白/加载慢	首次启动需安装依赖	查看日志：docker logs -f opencode，等待 2--5 分钟
上下文超限	输入代码过大	在 opencode.json 中设置 context，output， 等
AI 无法修改文件	权限未授权	Web UI 会弹出操作确认框，点击 "Allow"；切勿全局关闭权限校验

🔒 安全最佳实践

• 对外提供服务，添加服务验证，避免直接暴露 3000 端口（避免直接暴露 3000 端口）
• 限制 workspace 挂载范围，禁止挂载 /、/home 等系统目录
• 生产环境 Dockerfile 使用非root 用户

---

✅ 现在，打开浏览器，即可享受安全、高效、完全自主的 AI 编程体验！

如需进一步定制（如多模型切换、自定义 Agent、技能插件扩展），请参考 OpenCode 官方文档。