1. 为什么我要把 OpenCode 塞进 Docker ComposeOpenCode 是一款开源的 AI 编程助手能做的事和你在用的商业补全插件差不多代码补全、对话式改代码、解释一段看不懂的遗留逻辑、批量生成单元测试。它适合谁适合那些不想把公司代码往第三方云端送、又希望成本可控的团队和个人开发者。你可以把它理解成「自己家里搭一个代码助手」模型跑在你自己的机器上数据不出内网。但真动手部署时麻烦往往不在 OpenCode 本身而在「模型从哪来」。本地跑 vLLM 要显卡、要下几十 GB 权重、要调显存参数直接接商业 API 又得在每台机器上散落一堆 Key换个人就得重新配一遍。我试过把两者混着用结果配置文件里三套 base_url、四把 Key维护起来头大。这篇的做法是OpenCode 用 Docker Compose 编排模型通道统一走 TaoToken 的 API 网关。TaoToken 在这里的角色是「统一 Key / API 通道」——你只需要在 config.toml 里填一个 base_url 和一把 Key背后接的是本地 vLLM 还是别的模型对 OpenCode 来说都是同一个 OpenAI 兼容接口。这样本地推理和远端模型可以随时切换而不用改 OpenCode 的代码。下面从零走一遍写 docker-compose.yml、写 config.toml、起服务、发一个真实请求验证连通性最后把几个我踩过的坑列出来。2. 前置准备TaoToken Key 与目录结构在写编排文件之前先把两件事办了。第一件是拿 TaoToken 的 API Key。访问 https://taotoken.net/api-keys 登录后在控制台创建一把 Key复制出来形如sk-xxxx的字符串。这把 Key 就是 OpenCode 访问模型通道的凭证后面写进 config.toml。如果你还没注册从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进官网走一遍即可整个过程不涉及任何网络工具。第二件是规划目录。我习惯把配置和数据分开方便备份和迁移mkdir -p ~/opencode-deploy/{config,data,models} cd ~/opencode-deploy最终目录长这样opencode-deploy/ ├── docker-compose.yml ├── config/ │ └── config.toml ├── data/ # OpenCode 会话与索引数据 └── models/ # 本地 vLLM 权重可选注意data/目录会存会话历史和代码索引别放在容器里否则docker compose down一执行就没了。挂载出来最省心。关于硬件如果你打算本地跑 vLLM7B 级别的代码模型大概需要 16GB 以上显存如果只走 TaoToken 通道接远端模型那对本地显卡没要求一台 4 核 8GB 的机器就能把 OpenCode 本体跑起来。这也是统一通道的好处之一算力可以后置。3. 可复制的 docker-compose.yml 与 config.toml3.1 docker-compose.yml 骨架这份编排包含两个服务opencode本体以及可选的vllm本地推理后端。如果你只用 TaoToken 通道把 vllm 那段注释掉即可。version: 3.8 services: opencode: image: ghcr.io/opencode-ai/opencode:latest container_name: opencode ports: - 8000:8000 # 后端 API - 3000:3000 # Web 界面 volumes: - ./config:/root/.config/opencode - ./data:/root/.local/share/opencode environment: - OPENCODE_CONFIG/root/.config/opencode/config.toml depends_on: - vllm restart: unless-stopped vllm: image: vllm/vllm-openai:latest container_name: vllm ports: - 8080:8080 volumes: - ./models:/models command: --model /models/Qwen2.5-Coder-7B-Instruct --served-model-name qwen-coder --port 8080 --max-model-len 32768 --gpu-memory-utilization 0.9 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] restart: unless-stopped几个参数值得说明。--served-model-name qwen-coder是给模型起的别名config.toml 里引用这个名字就行不用写一长串路径。--max-model-len 32768控制上下文长度代码补全场景 32K 够用调太大会吃显存。--gpu-memory-utilization 0.9表示允许 vLLM 占用 90% 显存留一点给系统。3.2 config.toml 骨架OpenCode 的模型配置写在 config.toml 里。下面这份同时配了「走 TaoToken 通道」和「走本地 vLLM」两个 provider你可以按需保留。# ~/opencode-deploy/config/config.toml [providers.taotoken] type openai base_url https://taotoken.net/api/v1 api_key sk-你的TaoToken密钥 models [qwen-coder, gpt-4o-mini] [providers.local] type openai base_url http://vllm:8080/v1 api_key not-needed models [qwen-coder] [default] provider taotoken model qwen-coder max_tokens 2048 temperature 0.2这里的关键点是base_url。TaoToken 提供的是 OpenAI 兼容接口所以type填openai即可OpenCode 会用标准的/chat/completions协议去请求。api_key填你第 2 步拿到的那把。temperature 0.2是我对代码场景的偏好低温度让补全更稳定不会天马行空。提示config.toml 里出现明文 Key记得给文件设权限chmod 600 config/config.toml别提交到 Git。4. 启动服务与连通性验证4.1 拉起容器cd ~/opencode-deploy docker compose up -d第一次执行会拉镜像vLLM 镜像比较大耐心等。起来之后看状态docker compose ps正常的话两个服务都是running。如果 vllm 一直重启多半是显存不够或权重路径不对先看日志docker compose logs -f vllm4.2 验证 TaoToken 通道在 OpenCode 之前先用 curl 单独验证通道是否通。这一步能帮你把「通道问题」和「OpenCode 配置问题」分开定位curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: qwen-coder, messages: [{role: user, content: 用 Python 写一个快速排序}], max_tokens: 256 }返回里如果能看到choices[0].message.content里有代码说明通道没问题。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是不是写成了https://taotoken.net/api少了/v1。4.3 验证 OpenCode 本体OpenCode 起来后后端健康检查curl http://localhost:8000/health返回{status:ok}之类即可。然后打开浏览器访问http://localhost:3000进入 Web 界面在对话框里输入一句「解释一下这段代码的作用」并贴一段代码看是否有流式返回。如果界面能出字说明 OpenCode → config.toml → TaoToken 整条链路打通了。想更直接一点也可以走 APIcurl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen-coder, messages: [{role: user, content: 写一个 Dockerfile 多阶段构建示例}] }4.4 切换本地 vLLM 后端如果你本地起了 vLLM把 config.toml 的[default]段改成[default] provider local model qwen-coder然后docker compose restart opencode。这样请求就走内网http://vllm:8080/v1不经过外部通道。两种模式随时切OpenCode 侧不用改任何代码这就是统一配置层的好处。5. 本篇常见错排查报错一CUDA out of memory。vLLM 启动时显存不够。先把--gpu-memory-utilization降到 0.8再把--max-model-len从 32768 降到 16384。还不行就换量化版本权重AWQ 或 GPTQ 能省一半显存。报错二Connection refused连不上 vllm。在 compose 网络里服务之间要用服务名互访也就是http://vllm:8080不是http://localhost:8080。localhost 在容器里指向容器自己当然连不上。这个坑我第一次部署时卡了半小时。报错三TaoToken 返回 401 Unauthorized。九成是 Key 复制时带了空格或换行。用echo -n sk-xxx | wc -c数一下长度或者直接在 config.toml 里重新粘贴一遍。另外确认请求头是Authorization: Bearer sk-xxxBearer 后面有一个空格。报错四OpenCode 界面能开但对话无响应。先看docker compose logs -f opencode如果报model not found说明 config.toml 里[default]的 model 名和 provider 的 models 列表对不上。model 名要和--served-model-name或 TaoToken 侧支持的模型名完全一致大小写敏感。报错五改了 config.toml 不生效。OpenCode 只在启动时读配置改完必须docker compose restart opencode。别指望热重载。报错六端口被占用。3000 或 8000 被别的服务占了改 compose 里的端口映射比如13000:3000然后访问http://localhost:13000。6. 后续怎么用把通道固定下来部署跑通只是第一步。真正让这套东西在团队里活起来关键是别让每个人各自去配 Key。我的做法是把 TaoToken 的 Key 放在 config.toml 里统一管理团队成员通过 OpenCode 的 Web 界面访问不接触底层凭证。需要换模型或调额度时只改一处配置重启容器即可。如果你后面要接长期编码任务或者 Agent 类的自动化流程可以看看 Coding Plan 这类按周期计费的方案比按 token 零散调用更可控https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。日常调试模型输出、对比不同模型效果用模型对话页面就够了https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节和参数说明都在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个实用技巧把docker compose logs -f opencode挂在一个终端里别关边用边看日志。OpenCode 请求失败时日志里会打出实际请求的 base_url 和返回码比在界面上猜快得多。这套编排我用了几个月最常改的就是 config.toml 里的 model 字段其余部分基本没动过。