1. 为什么要在 Docker 里跑 OpenCode还要接统一 API 通道OpenCode 是一个开源的 AI 编码代理AI Coding AgentMIT 许可证模型无锁定支持终端 CLI、Web 界面和桌面端。它的核心价值在于把「理解任务 → 生成代码 → 执行测试 → 自我修正」串成一个闭环你可以用自然语言描述需求让代理独立完成编码工作。适合谁想自托管、不想被某一家模型供应商绑死、又希望有一套统一入口管理多个模型 Key 的开发者。但真到自己部署这一步问题就来了。第一OpenCode 本身不绑定模型你得自己填 API 地址和 Key第二如果你同时用 Claude、GPT、Gemini 或者本地模型每个供应商一套 Key、一套计费、一套限流管理起来很碎第三容器里的环境变量、配置文件路径、持久化目录如果没规划好重启一次配置就丢。我试过把 Key 直接写死在 compose 里结果换模型时改得满屏都是。这篇就聚焦两件事用官方原生 Docker 镜像把 OpenCode 跑起来以及通过 TaoToken 的统一 API 通道接入模型让 OpenCode 只认一个 base_url 和一个 Key。全程可复制包含 docker run、docker compose、config.toml 骨架和一次真实的代码补全请求验证。2. TaoToken 前置准备拿到统一 Key 和接入地址TaoToken 在这里扮演的角色是「统一 API 通道」OpenCode 只需要配置一个 OpenAI 兼容的 base_url 和一个 Key就能调用背后多个模型不用在 OpenCode 里为每个供应商单独写配置。对自托管场景来说这能省掉大量环境变量拼接的工作。你需要先做两件事。第一注册并登录 TaoToken 控制台创建一个 API Key。地址是 https://taotoken.net/api-keys 创建后复制保存后面会作为环境变量注入容器。注意 Key 只在创建时完整显示一次丢了就重新建一个。第二确认接入地址。OpenCode 走 OpenAI 兼容协议时base_url 填 https://taotoken.net/api 不要带任何多余路径。如果你用的是 Anthropic 协议风格的模型通道OpenCode 也支持单独配置但本文以 OpenAI 兼容通道为主通用性最好。注意Key 属于敏感信息不要写进会提交到 Git 的 compose 文件里。推荐用.env文件加环境变量引用的方式下面会给完整写法。如果你还没决定用哪个模型可以先到模型对话页面 https://taotoken.net/model-chat 试一下对话效果确认通道可用再往 OpenCode 里接能少走弯路。3. 可复制配置docker run 与 docker compose 两套写法OpenCode 官方镜像在 ghcr.io/anomalyco/opencode。本文写作时 latest 对应 1.2.15你可以用 latest也可以锁定版本号保证可复现。3.1 先建目录不管用哪种方式先把持久化目录建好。下面以/opt/opencode为例你可以换成自己的路径。mkdir -p /opt/opencode/{data,workspace} cd /opt/opencodedata用来持久化 OpenCode 的配置和会话数据workspace作为项目工作目录挂进容器。这两个目录分开挂是为了升级镜像时不丢配置、也不污染代码。3.2 方式一docker run 快速起一个 Web 服务docker run -d \ --restart unless-stopped \ --name opencode \ -p 4096:4096 \ -v /opt/opencode/data:/home/opencode \ -v /opt/opencode/workspace:/home/opencode/workspace \ -e HOME/home/opencode \ -e OPENCODE_SERVER_USERNAMEadmin \ -e OPENCODE_SERVER_PASSWORD换成你的强密码 \ -e OPENAI_API_KEY你的TaoTokenKey \ -e OPENAI_BASE_URLhttps://taotoken.net/api \ ghcr.io/anomalyco/opencode:latest \ web --hostname 0.0.0.0 --port 4096参数逐个说清楚-p 4096:4096把容器端口映射到宿主机-v两行分别挂 data 和 workspaceHOME/home/opencode让容器内主目录指向挂载点配置才会落盘OPENCODE_SERVER_USERNAME/PASSWORD给 Web 界面加一层登录保护不设的话默认用户是 opencode 且无密码公网暴露很危险OPENAI_API_KEY和OPENAI_BASE_URL就是 TaoToken 的统一通道配置最后web --hostname 0.0.0.0 --port 4096是容器启动命令以 Web 模式监听所有网卡。3.3 方式二docker compose推荐长期运行把敏感信息放进.envcompose 文件只做引用这样文件可以安全地放进版本库。先写.envOPENCODE_SERVER_USERNAMEadmin OPENCODE_SERVER_PASSWORD换成你的强密码 OPENAI_API_KEY你的TaoTokenKey OPENAI_BASE_URLhttps://taotoken.net/api再写docker-compose.ymlservices: opencode: image: ghcr.io/anomalyco/opencode:latest container_name: opencode restart: unless-stopped ports: - 4096:4096 volumes: - ./data:/home/opencode - ./workspace:/home/opencode/workspace environment: - HOME/home/opencode - OPENCODE_SERVER_USERNAME${OPENCODE_SERVER_USERNAME} - OPENCODE_SERVER_PASSWORD${OPENCODE_SERVER_PASSWORD} - OPENAI_API_KEY${OPENAI_API_KEY} - OPENAI_BASE_URL${OPENAI_BASE_URL} command: web --hostname 0.0.0.0 --port 4096启动docker compose up -d docker compose logs -f opencode看到服务监听 4096 的日志就说明起来了。浏览器打开http://你的服务器IP:4096用.env里的账号密码登录。3.4 config.toml 骨架OpenCode 支持用配置文件声明模型和供应商比纯环境变量更清晰。配置文件放在挂载的 data 目录下即/opt/opencode/data/.config/opencode/config.toml具体路径以容器内 HOME 为准本文 HOME 指向/home/opencode所以是/opt/opencode/data/.config/opencode/config.toml。# OpenCode 配置文件骨架 # 通过 TaoToken 统一通道接入OpenAI 兼容协议 [providers.taotoken] type openai base_url https://taotoken.net/api api_key {env:OPENAI_API_KEY} [models.default] provider taotoken model claude-sonnet-4-20250514 [models.fast] provider taotoken model gpt-4o-mini这里api_key {env:OPENAI_API_KEY}表示从环境变量读取避免明文写进配置文件。model字段填你在 TaoToken 里可用的模型名具体以控制台模型列表为准。配好两个模型别名后日常编码用 default快速问答切 fast切换成本很低。提示如果你更习惯纯环境变量方式只配OPENAI_API_KEY和OPENAI_BASE_URL也能跑config.toml 属于进阶用法适合需要多模型别名的场景。4. 验证请求发一次代码补全确认通道连通配置写完不代表通道通了必须发一次真实请求验证。有两种验证方式建议都做一遍。4.1 先用 curl 验证 TaoToken 通道本身在宿主机上直接打一次 OpenAI 兼容接口确认 Key 和 base_url 没问题curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [ {role: user, content: 用 Python 写一个快速排序函数只输出代码} ] }返回里能看到choices[0].message.content带代码说明通道和 Key 都正常。这一步排除了网络和鉴权问题后面 OpenCode 里再报错就基本是配置问题。4.2 再在 OpenCode 里发一次补全请求登录 Web 界面后新建一个会话输入一个具体任务比如「在当前 workspace 下创建一个 hello.py打印 1 到 10 的平方」。OpenCode 的 build 代理会读取 workspace、生成文件、必要时执行验证。如果你想用 CLI 模式快速验证可以进容器执行docker exec -it opencode sh opencode run 在当前目录创建 hello.py打印 1 到 10 的平方执行后检查 workspace 目录cat /opt/opencode/workspace/hello.py能看到生成的代码文件就说明从 OpenCode → TaoToken 通道 → 模型 → 返回结果这条链路完全打通了。这一步是整个部署里最关键的验证点别跳过。5. 本篇常见错排查部署过程中最容易踩的坑集中在下面几类按出现频率排。容器起来但 Web 打不开。先看docker compose logs opencode如果日志显示监听 127.0.0.1 而不是 0.0.0.0说明启动命令里的--hostname 0.0.0.0没生效检查 command 是否被覆盖。再确认宿主机防火墙放行了 4096 端口。登录后模型调用报 401。九成是 Key 没注入成功。进容器docker exec -it opencode env | grep OPENAI看环境变量在不在。如果用了.env但 compose 里没写${OPENAI_API_KEY}引用变量不会自动进容器。报 base_url 相关错误。检查OPENAI_BASE_URL是不是写成了https://taotoken.net/api/v1。OpenCode 走 OpenAI 兼容协议时base_url 填到/api即可SDK 会自己拼/v1/chat/completions多写一层会 404。配置重启后丢失。说明 data 目录没挂对或者HOME没设成挂载点。确认-v /opt/opencode/data:/home/opencode和-e HOME/home/opencode同时存在缺一个配置就落不到盘上。模型名报 not found。config.toml 里的 model 字段必须和 TaoToken 控制台里可用的模型名完全一致大小写和版本后缀都不能错。不确定就先在模型对话页面确认模型标识。权限问题导致 workspace 写不进去。容器内进程用户和宿主机目录属主不一致时会写失败。简单做法是chmod 777 /opt/opencode/workspace先跑通生产环境再按实际用户调整属主。6. 后续怎么用把统一通道接进日常编码流跑通之后OpenCode 的两种代理模式可以分工用plan 代理是只读的适合先让它分析陌生代码库、出重构计划build 代理有完整系统访问权限适合真正改代码、跑测试。日常我一般先用 plan 摸清结构确认方案后再切 build 执行避免代理一上来就动文件。如果你打算长期把 OpenCode 当主力编码代理尤其是接进 CI 或者做 Agent 自动化建议了解一下 Coding Plan地址是 https://taotoken.net/coding-plan 它在统一通道基础上更适合高频、长会话的编码场景。接入文档在 https://taotoken.net/doc 里面有各协议的完整参数说明遇到配置细节可以直接对照。最后留一个实用习惯把.env加进.gitignorecompose 文件里永远只写变量引用。这样你的 OpenCode 部署既能随时重建又不会因为一次误提交把 Key 泄露出去。