OpenCode Docker 适合需要可复现运行环境、明确文件边界或本地模型路径的场景。容器本身不会自动带来安全性；安全性来自镜像来源、挂载目录、Provider 凭据、网络暴露、命令权限，以及允许写入前收集的验证证据。
快速结论：按任务选择 Docker 路径
Docker Sandbox 适合希望快速得到隔离 OpenCode 工作区的用户，但仍要弄清哪些文件被挂载、哪个 Provider 会收到代码，以及沙箱授予了哪些权限。
Docker Model Runner 属于另一层：它提供本地模型服务，OpenCode 仍是编码界面。Model Runner 可用不代表 OpenCode 的权限、Git 挂载或项目目录已经配置好。
自建镜像适合需要固定 Node 版本、系统包、私有证书或 Compose 团队环境的项目，但你也要负责 Dockerfile、镜像更新、容器用户和凭据注入。
Docker 配置路径与取舍
`opencode docker image`、`opencode docker compose` 和 `docker opencode` 都是同一个配置决策的变体，不需要拆成多个页面。用表格说明区别，再让读者先选一条路径。
如果只是让 OpenCode 读写仓库，从能运行官方 CLI 并访问 Provider 的最小镜像开始。第一次验证不要同时加入数据库、反向代理或整个主目录挂载。
如果使用 Docker 的原因是本地模型隐私，把模型服务与编码代理分开记录。端点选择不会替代项目挂载和权限审查。
| 路径 | 适合场景 | 需要确认的边界 |
|---|---|---|
| Docker Sandbox | 快速得到隔离 OpenCode 工作区 | 认证、项目挂载和沙箱权限 |
| Docker Model Runner | 本地或私有模型推理 | 模型、端点路径、端口和上下文预算 |
| 自建 Docker 镜像 | 固定工具和团队复现 | Dockerfile 来源、非 root 用户、更新和密钥 |
| Docker Compose | 多个服务或团队堆栈 | 服务名、网络、卷和清理方式 |
在容器中运行 OpenCode 前先检查
挂载源码前先检查镜像来源。优先使用 Docker 官方文档或能审查 Dockerfile、基础镜像、发布过程和更新记录的仓库。热门镜像不等于适合敏感代码。
只让容器看到计划编辑的项目，不要挂载整个主目录、SSH 目录、云凭据目录或 Docker socket。能访问宿主 Docker socket 的容器可能控制比普通项目容器更多的资源。
Provider 凭据应在运行时注入，不能写进 Dockerfile、镜像层、提交到 Git 的 Compose 文件或 shell 历史。确认 `.dockerignore` 不会把密钥发送到构建上下文。
第一次任务选择小仓库和无害操作：只读解释、一处文档或测试改动、Git diff，以及不会触碰生产系统的格式化或测试命令。
可靠 OpenCode Docker 配置的 7 个检查点
这些检查把容器启动变成可追溯证据。模型缺失时排查端点，文件错误时排查挂载，写入越界时收紧权限，不要一次改动所有层。
笔记本和 CI 都使用同一顺序。CI 可以采用不同的凭据方式和只读工作区，但仍应记录镜像、Provider、项目路径和命令。
成功返回不等于安全：模型可能能回答，却仍能看到过多宿主文件、使用未固定镜像，或写入团队无法审查的卷。
- 检查镜像 记录镜像名、tag 或 digest、基础镜像、更新来源和容器用户。
- 建立窄工作区 只挂载项目路径，第一次写入使用独立分支或 worktree。
- 连接一个 Provider 先验证一个模型端点，密钥放在镜像和仓库外。
- 确认模型 从容器内确认响应、模型 ID、上下文限制和端口。
- 执行只读任务 先让 OpenCode 总结文件并列出假设。
- 检查小 diff 只改文档或测试 fixture，检查 Git diff，拒绝无关文件。
- 记录清理 停止容器、删除临时卷，记录命令、镜像、模型和修复。
Docker Model Runner 与 OpenAI-compatible 端点
Docker Model Runner 适合私有或本地推理。先启用编码模型，确认与 OpenCode 同一网络中的服务能响应，再使用准确的 base URL 和模型 ID 配置 Provider。不要把产品营销名称当成 API ID。
端点测试和 OpenCode 测试要分开。直接请求证明模型服务可达，OpenCode 只读任务才证明 Provider、仓库上下文、工具权限和终端会话能协作。
本地端点也可能暴露过宽。只绑定所需接口，默认不要发布到公网，并写清容器使用 host gateway、Compose 服务名还是远程模型服务器。
# Illustrative shape only; confirm current image, endpoint, and model fields in official docs
docker run --rm -it --mount type=bind,src="$PWD",dst=/workspace --workdir /workspace -e OPENAI_API_KEY -e OPENAI_BASE_URL opencode-image:reviewed opencode权限、密钥、端口与 Git 安全
容器边界只是权限模型的一部分。OpenCode 权限、Docker 挂载、Linux 用户、Provider 访问和 Git 分支规则应该互相匹配。
团队应写下最小命令和清理方式：是否任务后删除容器、是否允许命名卷、哪些端口只在私网开放，以及审查者如何复现镜像和模型。
第一次写入应该很小：README 一句话、测试 fixture 或格式化改动。若 diff 出现锁文件、密钥、生成 bundle 或项目外文件，应先修边界。
| 检查项 | 更稳妥的默认值 | 风险信号 |
|---|---|---|
| 密钥 | 运行时注入，实验后轮换 | 写进 Dockerfile、镜像历史或 Compose |
| 文件系统 | 单一项目挂载、非 root、独立 worktree | 挂载主目录、SSH key 或 Docker socket |
| 网络 | 只开放 Provider 和必要端口 | 所有端口发布或公网模型端点 |
| Git | 每次写入后检查 status 和 diff | 写到目标 worktree 之外 |
| 镜像 | 固定 digest 或审查过的 tag | 无人维护的 latest 镜像 |
排错：定位失败发生在哪一层
如果 `opencode` 不存在，先确认镜像内含 CLI、entrypoint 保留 PATH，且命令运行在正确用户环境。不要先改 Provider 配置。
模型列表为空时，从容器内测试端点，检查 base URL、DNS、端口、凭据和模型 ID。容器内的 `localhost` 可能指向容器自己，而不是宿主或 Compose 服务。
答案正常但编辑错误时，缩小挂载和任务范围，检查权限策略并重新做只读请求。记录镜像摘要、Provider、模型、命令和 Git diff，方便复现。
| 现象 | 可能层 | 第一检查 |
|---|---|---|
| 找不到 OpenCode 命令 | 镜像或 PATH | 在同一镜像和 workdir 中运行版本命令 |
| Provider 可见但没有模型 | 端点或模型 ID | 从容器内测试端点并核对准确 ID |
| 找不到文件 | 挂载或 workdir | 打印工作目录并列出挂载项目 |
| 请求超时 | 网络、端口、配额或模型 | 短请求测试并检查容器网络 |
| 改了意外文件 | 挂载、权限或任务范围 | 停止、检查 Git、移除宽挂载 |
OpenCode Docker 常见问题
OpenCode 可以在 Docker 容器中运行吗？
可以。Docker 能为 OpenCode 提供受控运行环境，但仍需审查镜像、项目挂载、Provider 凭据、网络和命令权限。
应该用 Docker Sandbox 还是自建 OpenCode 镜像？
快速隔离优先选择 Docker Sandbox；需要固定依赖、私有证书或团队复现且能维护镜像时再自建。
如何把 OpenCode 连接到 Docker Model Runner？
先验证模型服务，再按官方文档配置 OpenAI-compatible base URL 和准确模型 ID，并从同一容器网络测试。
OpenCode Docker 应该挂载什么？
只挂载项目或 worktree，避免主目录、SSH key、云凭据目录和宿主 Docker socket。
OpenCode 一定需要 Docker Compose 吗？
不需要。单容器更容易验收；只有多个服务需要私有网络和可复现编排时才使用 Compose。
为什么容器里看不到 OpenCode 模型？
常见原因是 base URL、容器内 localhost、模型 ID、端口、Provider key 或网络服务名错误。
需要核对的官方来源
Docker 和 OpenCode 的集成细节会变化。将命令用于敏感仓库前，请核对官方文档中的镜像、认证字段、端点和权限。