---
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/)