# opencode-sandbox
[](LICENSE)
[](https://github.com/PraveenNellihela/opencode-sandbox/actions)
[](https://docs.docker.com/get-docker/)
[](https://github.com/PraveenNellihela/opencode-sandbox)
隔离的、持久化的 Docker 沙箱，用于在任何 OS 上运行 [opencode](https://opencode.ai)。免费模型，无 token 限制，保护您的宿主机安全。
## 为什么要对 opencode 使用沙箱？
opencode 是一个强大且免费的 AI 编程代理 —— 但是赋予任何 AI CLI 权限
去访问您的整个文件系统是一个真正的安全风险。依赖项中的提示词注入、
您要求它审查的仓库中的恶意代码，或者简单的 bug，
都可能会暴露您的整个机器。付费的 AI 编程工具通常会限制您的
token 数量并设置使用时限。opencode-sandbox 解决了所有这些问题。
| 优势 | 这对您意味着什么 |
|---------|----------------------|
| **🔒 宿主机隔离** | AI 只能看到您当前的项目目录。SSH 密钥、浏览器数据、dotfiles 和其他仓库均被限制访问。 |
| **🛡️ 默认非 root** | 以专用的 `dev` 用户身份运行，且没有 `sudo` 权限。即使是遭到破坏的代理也无法提权访问您的宿主机。 |
| **💸 免费且强大的模型** | opencode 包含了免费模型（DeepSeek V4 Flash、Big Pickle 等），这些模型在日常编程中非常实用 —— 整个仓库都是使用它们构建的。无需按月订阅。 |
| **⏱️ 无 token 限制** | 与 Claude Code 会过期的付费 token 不同，您可以按照自己的规则使用模型。只有在您选择高级提供商时才需要付费。 |
| **📦 处处一致** | 相同的 Docker 镜像在 Linux、macOS 和 Windows (WSL2) 上的行为完全一致。告别“在我的机器上能跑”的问题。 |
| **🔄 智能持久化** | Auth token、插件和配置通过 Docker 数据卷在重启后依然保留。系统软件包在每次会话中会干净地重置。 |
| **⚙️ 可复现的工具链** | Node.js、Python、Go、CLI 工具 —— 在构建时预装，而不是临时通过 `apt-get` 安装。团队成员可以获得完全一致的开发环境。 |
## 快速开始
```
# 1. 克隆并进入 repo
git clone https://github.com/PraveenNellihela/opencode-sandbox.git
cd opencode-sandbox
# 2. 运行安装程序（检测 OS，构建 Docker image，复制 wrapper 到 ~/bin/）
./install.sh
# 3. 使用 opencode，它在 Docker 内运行，bind-mounted 到当前目录
cd ~/code/my-project
opencode
```
安装程序会检测您的 OS 和 shell，将包装器复制到 `~/bin/`，并构建 Docker 镜像。您可能需要将 `~/bin` 添加到您的 PATH 中（如果是这样，安装程序会提示您）。
### 自定义您的构建
向 `install.sh` 传递参数以预装工具链、代理、插件和 MCP 服务器：
| 参数 | 描述 |
|------|-------------|
| `-R, --recommended` | 全功能启动（Node.js + Python + CLI 工具 + superpowers + 插件 + MCP + 代理） |
| `-t, --toolchain LIST` | 以逗号分隔：`node,python,go,cli` |
| `-p, --plugin LIST` | 以逗号分隔：`superpowers,pty,notify,websearch,mcp-tool-search` |
| `-m, --mcp LIST` | 以逗号分隔：`filesystem,context7,brave-search,github` |
| `-a, --agents` | 包含 6 个预构建的子代理（code-reviewer、security-analyst、debugger、documenter、tester、planner） |
| `-i, --interactive` | 通过交互式提示进行选择 |
示例：
```
# 最小化（默认 — 与原始版本相同）
./install.sh
# 包含所有 extras 的完全增强版
./install.sh --recommended
# 自定义：仅 Node.js + CLI tools + superpowers + agents
./install.sh -t node,cli -p superpowers -a
# 交互模式
./install.sh -i
```
### --recommended 包含的内容
```
Toolchains: Node.js + Python 3 + ripgrep + fd-find + jq + tmux
Plugins: superpowers + opencode-pty + opencode-notify + opencode-websearch-cited
MCP: filesystem + Context7
Agents: code-reviewer, security-analyst, debugger, documenter, tester, planner
```
### 预构建子代理
当使用 `-a` 或 `--recommended` 时，6 个专业的子代理将被加载到 `~/.config/opencode/agents/` 中。您可以通过 `@name` 在对话中调用它们中的任何一个：
| 代理 | 用途 |
|---|---|
| `@code-reviewer` | 代码质量、模式和最佳实践（只读） |
| `@security-analyst` | 漏洞评估、依赖审计（只读） |
| `@debugger` | 系统性的根因分析（完全访问权限） |
| `@documenter` | 技术文档、API 文档（写入 + 只读 bash） |
| `@tester` | 测试生成、覆盖率分析（完全访问权限） |
| `@planner` | 实现计划、任务分解（只读） |
### 恢复默认设置
如果您想清除预置的配置并重新开始：
```
# 删除已存储的 volumes（设置、plugins、auth tokens）
docker volume rm opencode-config opencode-data
# 使用您选择的选项重新构建
./install.sh --recommended
```
否则，现有的数据卷数据在重新构建时会被保留（只有空的数据卷会被填充）。
## 工作原理
- **隔离性：**容器只能看到当前的项目目录（通过 bind mount）。看不到您的主目录、其他仓库或宿主机进程。
- **持久性：**设置和 auth token 通过 Docker 数据卷在容器重启后依然保留。
- **安全性：**以非 root 用户身份运行，没有 sudo 权限。仅使用 Docker 网络。
## 哪些会保留，哪些不会保留
**会保留的内容**（Docker 数据卷）：
- `~/.config/opencode` — 设置、插件
- `~/.local/share/opencode` — auth token、会话数据
**不会保留的内容**（容器退出时丢失）：
- 会话期间安装的 OS 级软件包
- 上述目录之外的任何更改
如果您需要某个软件包（例如插件的 Node.js），请将其添加到 `Dockerfile` 并重新构建。
## 跨平台
### Linux
安装 Docker Engine 后即可开箱即用。
### macOS
请先安装 Docker Desktop：https://docs.docker.com/desktop/install/mac-install/
同时支持 Apple Silicon 和 Intel 芯片。
### Windows (WSL2)
1. 安装 WSL2：`wsl --install`
2. 安装带有 WSL2 后端的 Docker Desktop
3. 在 WSL 内部运行 `install.sh`
## Shell 支持
安装程序会检测您的 shell，并检查 `~/bin` 是否已经配置。如果没有，它会打印一条命令供您执行：
| Shell | 配置文件 | 要添加的命令 |
|-------|-------------|----------------|
| bash | `~/.bashrc` | `echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc` |
| zsh | `~/.zshrc` | `echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc` |
| fish | `~/.config/fish/config.fish` | `fish_add_path ~/bin` |
运行命令后，重启您的 shell 或执行 `source ~/.bashrc`（或 `~/.zshrc`）。
卸载后如需移除配置：
| Shell | 移除命令 |
|-------|-------------------|
| bash (Linux) | `sed -i '/export PATH="\$HOME\/bin:\$PATH"/d' ~/.bashrc` |
| bash (macOS) | `sed -i '' '/export PATH="\$HOME\/bin:\$PATH"/d' ~/.bashrc` |
| zsh (Linux) | `sed -i '/export PATH="\$HOME\/bin:\$PATH"/d' ~/.zshrc` |
| zsh (macOS) | `sed -i '' '/export PATH="\$HOME\/bin:\$PATH"/d' ~/.zshrc` |
| fish | `fish_remove_path ~/bin` |
## 添加依赖
可以通过两种方式添加系统软件包：
### 在构建时添加（推荐）
使用 `install.sh` 的参数来包含常用的工具链：
```
./install.sh -t node,python,cli
```
或者使用 `--recommended` 参数获取完整设置。
对于内置参数未涵盖的软件包，请在 `USER dev` 行之前将安装步骤添加到 `Dockerfile` 中：
```
RUN apt-get update && apt-get install -y --no-install-recommends \
your-package-here \
&& rm -rf /var/lib/apt/lists/*
```
然后重新构建：
```
$ docker build -t local:opencode .
```
缓存的层使这一过程非常快。
### 在容器内部添加（临时）
会话期间安装的软件包将在容器退出时丢失。这对于一次性的实验很有用，但不适合在生产环境中使用。
## 安装插件
可以在构建时或运行时添加插件。
### 在构建时安装
使用 `install.sh -p` 预先配置插件，以便它们在首次启动时即可使用：
```
./install.sh -p superpowers,pty,notify,websearch
```
这会将它们植入到随镜像附带的 `opencode.json` 中。可用插件：
- `superpowers` — [obra/superpowers](https://github.com/obra/superpowers)：代理技能框架
- `pty` — [opencode-pty](https://github.com/shekohex/opencode-pty)：为交互式进程提供真正的 PTY 支持
- `notify` — [opencode-notify](https://github.com/opencode-notify)：任务完成时的桌面通知
- `websearch` — [opencode-websearch-cited](https://github.com/ghoulr/opencode-websearch-cited)：带引用的网络搜索
- `mcp-tool-search` — [opencode-mcp-tool-search](https://github.com/francisco-m001/opencode-mcp-tool-search)：减少 MCP 服务器带来的上下文冗余
### 在容器内部安装（持久化）
opencode 自行安装的插件会存放在 `~/.config/opencode`（一个持久化的数据卷）下，因此它们在容器重启后依然存在。要在容器运行后手动添加插件，请通过 opencode 的配置 UI 编辑 `opencode.json`，或直接在数据卷中进行编辑。
示例：[superpowers](https://github.com/obra/superpowers)，在 opencode 内部使用以下命令安装：
```
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
```
要在容器运行后编辑生成的配置，请打开 TUI 并使用 opencode 的配置命令，或者直接在宿主机上编辑 `~/.config/opencode/opencode.json`（它存储在 Docker 数据卷中）。
## 安全模型
- **非 root：**容器以 `dev` 用户身份运行，没有 sudo 权限。
- **最小访问权限：**通过 bind mount 只能看到当前的项目目录。
- **网络：**默认的桥接网络 —— 可以连接到互联网（用于 LLM API），但宿主机上的任何内容都不会被暴露。
如果您在某些情况下需要实时的 root 权限，这提示您应该将其添加到 Dockerfile 并重新构建，而不是授予提权权限。
### 使用 Podman 代替 Docker
这些脚本支持将 Podman 作为 Docker 的替代方案。安装 Podman：
- Linux：`sudo apt install podman` 或 `sudo dnf install podman`
- macOS：`brew install podman`
Podman 完全消除了对宿主机上 root 守护进程的担忧。详情请参阅 https://podman.io。
## 卸载
```
$ ./uninstall.sh
```
这将移除：
- `~/bin/opencode`（包装器脚本）
- Docker 镜像（可选，会提示确认）
- Docker 数据卷（可选，会提示确认 —— 未经确认不会删除）
它**不会**自动编辑您的 shell 配置。您需要手动移除 PATH 行。
## 故障排除
**“Docker: command not found” / “Podman: command not found”**
→ 安装 Docker：https://docs.docker.com/get-docker/
→ 或者安装 Podman：https://podman.io/getting-started/installation
**“Cannot connect to the Docker daemon” / “Cannot connect to Podman socket”**
→ 启动 Docker Desktop 或执行：`sudo systemctl start docker`
→ 对于 Podman：`podman machine start` (macOS) 或检查系统服务
**安装后提示 “opencode: command not found”**
→ 重启您的 shell，或者执行：`source ~/.bashrc`（或 `~/.zshrc`）
**“Image not found” 错误**
→ 包装器不再自动构建。在 opencode-sandbox 仓库中运行 `./install.sh` 来构建它。
→ 如果您已经安装了包装器但删除了镜像：`cd path/to/opencode-sandbox && ./install.sh`
**`~/bin` 权限被拒绝**
→ 检查所有权：`ls -la ~/bin`
→ 修复：`chown -R $(whoami) ~/bin`
**macOS 终端：主题字体和颜色渲染不正确**
→ 与 VSCode 的集成终端或其他终端相比，内置的 macOS 终端应用程序可能会显示错误的颜色或字体。这是一个已知的 macOS 问题 —— 请参阅 [#4721](https://github.com/anomalyco/opencode/issues/4721)。升级到 macOS 26 可以解决此问题。或者，您也可以使用其他终端（例如 iTerm2、VSCode 终端或 Kitty）。
## 测试
本项目包含使用 [bats-core](https://github.com/bats-core/bats-core) 进行单元测试的测试基础架构，并使用 GitHub Actions 进行 CI。
### 前置条件
```
# 安装 bats
npm install -g bats
# 安装 shellcheck（可选，用于 shell linting）
sudo apt install shellcheck # Linux
brew install shellcheck # macOS
# 安装 hadolint（可选，用于 Dockerfile linting）
brew install hadolint # macOS
# 或者：docker run --rm -i hadolint/hadolint < Dockerfile
```
### 运行测试
```
# 运行所有测试
make test
# 仅运行静态分析（shellcheck、hadolint、syntax checks）
make test-lint
# 仅运行单元测试（不需要 Docker）
make test-unit
# 仅运行 end-to-end 测试（需要 Docker）
make test-e2e
```
### CI 流水线
`.github/workflows/ci.yaml` 流水线会在每次推送和 PR 时运行：
1. **Lint** — ShellCheck、Hadolint、bash 语法、JSON 验证、frontmatter 验证
2. **单元测试** — 针对 `configure-opencode`、包装器和 install.sh 参数的 bats 测试
3. **Docker 构建矩阵** — 构建并验证包含所有 build-arg 组合的镜像
4. **E2E 测试** — 针对构建好的镜像进行完整的集成测试
### Pre-commit Hook
要在本地启用 pre-commit hook：
```
pip install pre-commit # or: brew install pre-commit
pre-commit install
```
这会在每次提交时运行 ShellCheck 和 `shfmt`。Hook 在 `.pre-commit-config.yaml` 中配置。
### 测试结构
```
test/
helper.bash # Shared test helper functions
test_configure.bats # configure-opencode.sh unit tests
test_wrapper.bats # opencode wrapper behavior tests
test_install_flags.bats # install.sh flag parsing tests
test_e2e.bats # Docker build + run integration tests
fixtures/
golden_minimal.json # Expected output for default build
golden_recommended.json # Expected output for --recommended build
```