| | --- |
| | title: Opencode |
| | emoji: ⚡ |
| | colorFrom: green |
| | colorTo: gray |
| | sdk: docker |
| | app_port: 7860 |
| | pinned: false |
| | --- |
| | |
| | # OpenCode on Hugging Face Spaces |
| |
|
| | 本 Space 通过 **Docker** 部署 [OpenCode](https://opencode.ai/) 的 HTTP API 服务（`opencode serve`），可在浏览器中调用 OpenCode 的接口。 |
| |
|
| | ## 使用方式 |
| |
|
| | - **API 文档（OpenAPI 3.1）**：打开 Space 后访问 `/doc`，例如： |
| | `https://huggingface.co/spaces/<你的用户名>/<Space 名>/doc` |
| | - **健康检查**：`GET /global/health` |
| | - 其余接口见 [OpenCode Server 文档](https://opencode.ai/docs/server/)，如会话、消息、文件、LSP/MCP 等。 |
| |
|
| | ## 密钥与配置（可选） |
| |
|
| | 若需使用需认证的模型（如 OpenAI、Claude 等），请在 Space 的 **Settings → Repository secrets** 中配置相应环境变量；OpenCode 会读取常见命名（如 `OPENCODE_*` 或各 provider 的 API key 变量）。 |
| | 服务端 HTTP Basic 认证可设置： |
| |
|
| | - `OPENCODE_SERVER_PASSWORD`（必填时启用认证；**请务必在 HF 的 Secrets 里设置，不要写进代码**） |
| | - `OPENCODE_SERVER_USERNAME`（可选，默认 `opencode`） |
| |
|
| | 启用 Basic Auth 后，客户端需要提供**用户名 + 密码**（这是 HTTP Basic 机制决定的，无法只要密码）。 |
| | 默认用户名是 **`opencode`**，除非你设置了 `OPENCODE_SERVER_USERNAME`。 |
| |
|
| | ## 持久化存储（Dataset，免费） |
| |
|
| | 采用 [HF 官方推荐的 Dataset 存储](https://huggingface.co/docs/hub/spaces-storage#dataset-storage)：会话等数据写入你名下的 **Dataset 仓库**，用免费仓库存储额度，重启后可恢复。 |
| |
|
| | 1. **新建一个 Dataset 仓库** |
| | 在 [Hub](https://huggingface.co/new-dataset) 创建，例如 `tao-shen/opencode-data`（可先空着）。 |
| |
|
| | 2. **在 Space 里配置** |
| | - **Settings → Repository secrets**：新增 `HF_TOKEN`，值为你的 [Access Token](https://huggingface.co/settings/tokens)（需 **Write** 权限）。 |
| | - **Settings → Variables**：新增 `OPENCODE_DATASET_REPO`，值为 **repo_id**（如 `tao-shen/opencode-data`），或填完整 URL（如 `https://huggingface.co/datasets/tao-shen/opencode-data`）也会自动识别。 |
| | |
| | 3. **行为** |
| | - 启动时：从该 Dataset 拉取已有数据到 `~/.local/share/opencode`（若有）。 |
| | - 运行中：**有改动即同步**（inotify 监听，约 20 秒防抖后上传），不再按固定间隔。 |
| | - 未设置上述两个变量时，与之前一致：不恢复、不保存，重启后数据丢失。 |
| | |
| | ## 直接使用外部存储（自建/本地跑容器时） |
| | |
| | 若你在**自己的机器或 VPS** 上跑本镜像，希望 OpenCode **直接读写**某块盘或网络存储（不经过 Dataset 同步）： |
| | |
| | 1. 把外部存储挂载到容器内某路径，例如 `/mnt/opencode-data`（NFS、云盘、本地卷均可）。 |
| | 2. 设置环境变量：**`XDG_DATA_HOME=/mnt/opencode-data`**（可选再加 `XDG_CONFIG_HOME=/mnt/opencode-data/.config`）。 |
| | 3. 启动容器。OpenCode 会直接读写该路径，无需 HF_TOKEN / Dataset，也不会跑任何同步脚本。 |
| | |
| | 在 **Hugging Face Spaces** 里无法挂载自定义卷，因此「直接外部存储」仅适用于自建/本地部署。 |
| |
|
| | ## 参考 |
| |
|
| | - [Spaces 配置说明](https://huggingface.co/docs/hub/spaces-config-reference) |
| | - [OpenCode Server](https://opencode.ai/docs/server/) |
| |
|
