README.md

metadata

title: Opencode
emoji: ⚡
colorFrom: green
colorTo: gray
sdk: docker
app_port: 7860
pinned: false

OpenCode on Hugging Face Spaces

本 Space 通过 Docker 部署 OpenCode 的 HTTP API 服务（opencode serve），可在浏览器中调用 OpenCode 的接口。

使用方式

• API 文档（OpenAPI 3.1）：打开 Space 后访问 /doc，例如：
  https://huggingface.co/spaces/<你的用户名>/<Space 名>/doc
• 健康检查：GET /global/health
• 其余接口见 OpenCode 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 存储：会话等数据写入你名下的 Dataset 仓库，用免费仓库存储额度，重启后可恢复。

1. 新建一个 Dataset 仓库
   在 Hub 创建，例如 tao-shen/opencode-data（可先空着）。

2. 在 Space 里配置

   • Settings → Repository secrets：新增 HF_TOKEN，值为你的 Access Token（需 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 配置说明
• OpenCode Server