1. 为什么要在 Ubuntu 上用 Docker 跑 OpenCodeOpenCode 是一个开源的 AI 编程代理能在终端里读代码、改文件、跑命令配合 build 和 plan 两种模式一个负责动手改代码一个负责只读分析。它本身支持 npm、Homebrew 等多种安装方式但如果你手上有好几台 Ubuntu 机器或者想把它塞进已有的容器编排里直接用 Docker 跑会更省心环境隔离、版本固定、迁移时复制一个 compose 文件就行。真正让人头疼的不是装 OpenCode而是模型 Key 的管理。我一开始在宿主机上装了 OpenCode又配了 Claude Code还在 Cline 里填了一套 Key结果三个工具各存一份改一次模型要翻三个配置文件。后来把 OpenCode 放进容器同时用 TaoToken 做统一入口所有工具都指向同一个 Base URL 和同一把 Key配置量直接砍半。这篇就按这个思路走Ubuntu 24.04 主机 Docker Compose 部署 OpenCode TaoToken 统一 Key 接入从镜像构建一路跑到容器内对话请求成功。适合谁看手里有 Ubuntu 服务器或虚拟机的开发者想用容器方式跑 AI 编程代理又不想被多套 Key 折腾的人。全程命令可直接复制配置片段按你的实际路径改一下就能用。先说清楚整体链路。OpenCode 容器启动后监听 4096 端口Web 界面和 API 都走这个口。模型请求不直接打到各家厂商而是发到 TaoToken 的 API 地址由它按模型 ID 路由。这样你在 OpenCode 里换模型只需要改一个 Model ID不用动 Key。容器内的配置文件放在挂载出来的 data 目录里重建容器也不丢。下面按顺序来先检查 Ubuntu 上的 Docker 环境再写 Dockerfile 和 compose然后配 TaoToken最后进容器验证请求。每一步都有对应的命令和预期输出遇到报错在第五节对照排查。2. TaoToken 前置准备与统一 Key 获取在写容器配置之前先把 TaoToken 这边的准备工作做完。核心就两件事拿到 API Key确认 Base URL。这两样东西后面会同时出现在 OpenCode 的配置里缺一不可。打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录后进入控制台。控制台里能找到 API Keys 管理页新建一个 Key复制出来先存到安全的地方。这个 Key 就是后面所有工具共用的那一把OpenCode、Claude Code、Cline 都可以填它。Base URL 固定是 https://taotoken.net/api 注意这个地址不带任何查询参数填配置的时候原样写进去就行。很多人第一次配会把官网地址和 API 地址搞混官网是给人看的页面API 是给程序请求的端点两者不一样。模型 ID 这块TaoToken 支持多种模型你在控制台的模型列表里能看到可用的 ID。常见的有 claude 系列、gpt 系列等具体以控制台实时展示为准。选一个你常用的比如做代码补全和重构Claude 系列比较稳做快速问答轻量模型响应更快。把选定的 Model ID 记下来后面配置里要填。这里有个容易踩的坑Key 的权限范围。新建 Key 时如果控制台有权限选项确认它至少能访问你打算用的模型。有些 Key 默认只开了部分模型权限配好之后请求返回 403 或者模型不存在排查半天发现是权限没开。建 Key 的时候顺手勾上需要的模型范围省得后面返工。另外提醒一句Key 不要直接写死在 Dockerfile 里。Dockerfile 构建出来的镜像层是可以被查看的Key 写进去等于泄露。正确做法是通过环境变量或者挂载的配置文件传入compose 里用 env_file 或者 environment 字段都行。下面第三节会给出具体写法。准备工作做完你手上应该有三样东西一把 TaoToken API Key、Base URL https://taotoken.net/api 、一个选定的 Model ID。接下来进入容器配置环节。如果你还没建 Key现在去控制台建一个顺便把模型对话页面打开试一句确认 Key 本身是通的。这一步花两分钟能避免后面在容器里排查半天发现是 Key 的问题。3. 可复制的 Dockerfile 与 docker-compose 配置这一节是全文的核心给出可直接复制的配置文件。先建目录结构再写 Dockerfile然后写 compose最后把 TaoToken 的配置片段塞进去。先在 Ubuntu 上创建项目目录mkdir -p /data/opencode/{data,workspace,config} cd /data/opencodedata 存 OpenCode 的数据库和配置workspace 是 AI 实际读写代码的工作目录config 放我们自己的模型配置。三个目录都挂载出来容器重建不丢数据。写 Dockerfile。这里基于官方镜像做一层薄封装主要是把配置目录和启动参数固化下来FROM ghcr.io/anomalyco/opencode:1.15.13 USER root RUN mkdir -p /home/opencode/.config/opencode \ chown -R opencode:opencode /home/opencode/.config USER opencode WORKDIR /home/opencode/workspace EXPOSE 4096 CMD [web, --hostname, 0.0.0.0, --port, 4096]这个 Dockerfile 没做太多事就是确保配置目录存在、权限正确、工作目录设好。版本号固定 1.15.13避免每次构建拉到不同版本导致行为不一致。你要升级的时候改这个 tag 重新构建就行。接下来是 docker-compose.yml这是重点services: opencode: build: context: . dockerfile: Dockerfile image: opencode-taotoken:1.15.13 container_name: opencode restart: unless-stopped ports: - 4096:4096 volumes: - ./data:/home/opencode - ./workspace:/home/opencode/workspace - ./config:/home/opencode/.config/opencode environment: - HOME/home/opencode - OPENCODE_SERVER_USERNAMEadmin - OPENCODE_SERVER_PASSWORDchange_me_please - TAOTOKEN_API_KEY${TAOTOKEN_API_KEY} - TAOTOKEN_BASE_URLhttps://taotoken.net/api env_file: - .env command: web --hostname 0.0.0.0 --port 4096注意几个点。OPENCODE_SERVER_PASSWORD 别用 123456改成你自己的强密码这个口暴露在网络上就是登录凭证。TAOTOKEN_API_KEY 通过 .env 文件传入不写在 compose 里避免提交到 git 时泄露。env_file 和 environment 同时用的时候environment 里的值优先级更高但这里 Key 只从 .env 读所以不冲突。创建 .env 文件cat /data/opencode/.env EOF TAOTOKEN_API_KEYsk-你的实际Key粘贴在这里 EOF chmod 600 /data/opencode/.envchmod 600 是必须的这个文件只有 root 能读防止其他用户看到 Key。现在写 OpenCode 的模型配置。OpenCode 读取配置的路径是 /home/opencode/.config/opencode/config.json我们挂载的 config 目录对应这里。创建配置文件{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} }, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 }, gpt-4o: { name: GPT-4o } } } }, model: taotoken/claude-sonnet-4-5 }这个 JSON 里baseURL 填 TaoToken 的 API 地址apiKey 用 {env:TAOTOKEN_API_KEY} 引用环境变量这样 Key 不会出现在配置文件里。models 下面列了你打算用的模型 ID这些 ID 要和 TaoToken 控制台里的一致。最后的 model 字段指定默认用哪个。把这段 JSON 写到 /data/opencode/config/config.jsoncat /data/opencode/config/config.json EOF { $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} }, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 }, gpt-4o: { name: GPT-4o } } } }, model: taotoken/claude-sonnet-4-5 } EOF到这里三件套齐了Base URL 是 https://taotoken.net/api Key 从 .env 读Model ID 在 config.json 里指定。这三个东西在 OpenCode、Claude Code、Cline 里的填法逻辑是一样的只是字段名不同。记住这个对应关系后面换工具不用重新理解。构建并启动cd /data/opencode docker compose build docker compose up -d构建过程会拉取基础镜像第一次可能慢一点。启动后检查状态docker compose ps预期看到 opencode 容器状态是 Up端口映射 0.0.0.0:4096-4096/tcp。如果状态是 Restarting 或者 Exited直接看日志下一节会讲怎么排查。4. 容器内验证请求与成功结果确认容器跑起来不代表模型能通得实际发一次请求验证。这一节从日志检查开始到容器内发请求再到 Web 界面确认一步步来。先看容器日志确认 OpenCode 服务本身启动正常docker compose logs --tail50 opencode正常输出里会有数据库迁移完成的提示然后是启动 banner最后两行类似Local access: http://localhost:4096 Network access: http://192.168.x.x:4096看到这两行说明 Web 服务起来了。如果卡在数据库迁移或者报错退出记下报错内容第五节对照排查。接下来进容器内部直接验证 TaoToken 的连通性。这一步很关键它把「容器能不能访问外网」和「Key 对不对」两个问题分开验证docker exec -it opencode sh进去之后用 curl 直接打 TaoToken 的 APIcurl -s -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复两个字通了}], max_tokens: 20 }如果返回 JSON 里 choices 数组有内容说明 Key 和网络都没问题。返回大概长这样{ id: chatcmpl-xxx, object: chat.completion, choices: [ { index: 0, message: { role: assistant, content: 通了 }, finish_reason: stop } ] }看到 choices 里有 content这一步就过了。如果返回 401是 Key 的问题返回 404是模型 ID 写错了连接超时是容器网络出不去。三种情况分别对应第五节的排查项。curl 验证通过后退出容器exit然后从宿主机访问 Web 界面。浏览器打开 http://你的服务器IP:4096 用 compose 里设的 admin 和密码登录。进去之后在设置里确认模型提供商显示的是 TaoToken模型列表里有你配的那几个。在对话框里发一句测试比如「用 Python 写一个快速排序」。如果 OpenCode 正常返回代码说明整条链路通了Web 界面 → OpenCode 服务 → TaoToken API → 模型 → 返回。再验证一下 workspace 挂载是否生效。在 Web 界面里让 OpenCode 创建一个文件比如「在 workspace 下创建 hello.py内容是打印 hello」。然后回宿主机看ls -la /data/opencode/workspace/ cat /data/opencode/workspace/hello.py如果文件出现了说明容器内的写入正确落到了宿主机挂载目录。这个验证很重要因为 OpenCode 的核心用途就是改代码挂载不通等于白部署。最后确认一下配置持久化。重启容器docker compose restart重启后再登录 Web 界面模型配置应该还在不需要重新配。因为 config.json 挂在宿主机上容器重启不影响。到这里从镜像构建到对话请求的全流程就跑通了。5. 常见报错排查对照这一节按真实报错来每个都给出症状、原因和解决命令。遇到问题先在这里找对应项。401 Unauthorized。curl 返回 {error:{message:Invalid API key}} 或者类似。原因通常是 .env 里的 Key 没被容器读到或者 Key 本身失效。先确认容器内环境变量存在docker exec opencode env | grep TAOTOKEN如果输出为空说明 .env 没生效。检查 compose 里 env_file 路径对不对.env 文件是否在 /data/opencode 目录下。如果环境变量有值但还是 401去 TaoToken 控制台确认 Key 状态是不是被禁用或者删除了。还有一种情况是 Key 复制时带了空格或换行重新复制一次确保 .env 里等号后面没有多余字符。local proxy failed / connection refused。curl 报连接失败或者超时。先在容器内测基础网络docker exec opencode curl -sI https://taotoken.net/api如果这个也失败说明容器出不了网。检查宿主机 DNS 和防火墙Ubuntu 上确认 ufw 没拦出站sudo ufw status如果宿主机能访问但容器不能检查 Docker 的网络模式默认 bridge 应该没问题。有些环境配了自定义 DNS 导致容器解析不了域名在 compose 里加 dns 配置dns: - 8.8.8.8 - 1.1.1.1reading choices 相关报错。OpenCode 日志里出现类似 cannot read property choices of undefined 或者 reading choices。这通常是 API 返回格式和 OpenCode 预期的不一致。原因多半是 baseURL 配错了比如填成了官网地址而不是 API 地址或者路径多了/少了一段。确认 config.json 里 baseURL 是 https://taotoken.net/api 不要带 /v1 后缀OpenCode 的 openai-compatible provider 会自己拼路径。如果还不行检查模型 ID 是否在 TaoToken 支持列表里不支持的模型可能返回非标准格式。OAuth 相关报错。日志里出现 OAuth token 或者 authentication flow 字样。OpenCode 某些 provider 走 OAuth 流程但我们用的是 API Key 模式不应该触发 OAuth。如果出现检查 config.json 里 provider 的 npm 字段是不是 ai-sdk/openai-compatible这个包走的是标准 API Key 认证。如果误配成了别的 provider 包会走 OAuth 导致失败。改回 openai-compatible 重新构建。容器启动后立即退出。docker compose ps 显示 Exited。看日志docker compose logs opencode常见原因是 config.json 格式错误JSON 解析失败导致启动中断。用 python 验证一下python3 -m json.tool /data/opencode/config/config.json有语法错误会直接报出行号。修好再重启。另一个原因是端口 4096 被占用改 compose 里的宿主机端口映射比如 4097:4096。Web 界面能开但模型列表为空。登录后设置里看不到 TaoToken 的模型。检查 config.json 是否被容器读到docker exec opencode cat /home/opencode/.config/opencode/config.json如果文件不存在说明挂载路径不对。确认 compose 里 volumes 的 ./config 映射到 /home/opencode/.config/opencode且宿主机上 config.json 确实在这个目录。路径大小写和层级都要对。权限错误 permission denied。容器内写 workspace 报权限问题。检查宿主机目录属主ls -ld /data/opencode/workspace如果属主是 root 而容器内用户是 opencode会写不进去。改属主sudo chown -R 1000:1000 /data/opencode/workspace1000 是 opencode 用户在容器内的常见 UID具体可以进容器用 id 命令确认。排查完记得重新构建或重启docker compose down docker compose up -d --build6. 长期使用与 Key 统一管理建议跑通之后说几个长期用的实际建议。第一Key 轮换。TaoToken 的 Key 如果泄露或者你想定期更换只需要改 .env 文件里的值然后重启容器docker compose restart opencode不用重新构建镜像因为 Key 是运行时注入的。这就是把 Key 放环境变量而不是写进镜像的好处。第二多工具共用一把 Key。你现在 OpenCode 用的是这把 Key如果同时用 Claude Code它的配置里 Base URL 填 https://taotoken.net/api Key 填同一把Model ID 填同一个。Cline 的 MCP 配置也是同样三件套。这样你只需要在 TaoToken 控制台管理一处所有工具同步生效。换模型的时候改各工具的 Model ID 就行Key 不用动。第三模型切换。OpenCode 的 config.json 里 models 字段可以列多个模型用的时候在界面上切换。比如日常问答用轻量模型复杂重构切到 Claude Sonnet。改完 config.json 重启容器生效docker compose restart opencode第四备份。data 目录里有 OpenCode 的数据库和会话记录workspace 是你的代码。定期备份这两个目录就行tar czf opencode-backup-$(date %Y%m%d).tar.gz -C /data opencode/data opencode/workspace opencode/configconfig 目录也一起备里面是模型配置恢复的时候省事。第五升级。OpenCode 出新版本时改 Dockerfile 里的 tag然后docker compose build --no-cache docker compose up -d--no-cache 确保拉到新基础镜像。升级前先备份 data 目录防止数据库迁移出问题。如果你还没开始用建议先去 TaoToken 控制台把 Key 建好模型对话页面试一句确认可用再回来按第三节的配置走。整条链路里最容易出问题的就是 Key 和 baseURL 这两个点提前确认能省不少排查时间。