guide.md

# OpenClaw HF Space 設定指引

這份是目前專案的實際配置指引。

## 模型順序

目前預設模型鏈是：

1. `huggingface/Qwen/Qwen3-8B`
2. `huggingface/deepseek-ai/DeepSeek-R1`
3. `openai-codex/gpt-5.4`

注意：

- `Qwen` 是 primary
- `DeepSeek` 是第一個 fallback
- `openai-codex/gpt-5.4` 是第二個 fallback
- `openai-codex/gpt-5.4` 只有在它本身已經可用時，fallback 才會成功

## 你在 HF Space 要放的檔案

至少要有：

- `Dockerfile`
- `README.md`
- `setup-hf-config.mjs`
- `sync-external-storage.mjs`
- `guide.md`

## HF Space Settings

### Secrets

請加入：

```text
OPENCLAW_GATEWAY_TOKEN=<你的 gateway token>
HF_TOKEN=<你的 Hugging Face token>
SUPABASE_URL=https://cpflxjkupogczhyodoov.supabase.co
SUPABASE_KEY=<你的 supabase service_role key>
```

如果你要 Telegram，再加：

```text
TELEGRAM_BOT_TOKEN=<你的 telegram bot token>
```

### Variables

請加入：

```text
OPENCLAW_MODEL_PRIMARY=huggingface/Qwen/Qwen3-8B
OPENCLAW_MODEL_FALLBACK_1=huggingface/deepseek-ai/DeepSeek-R1
OPENCLAW_MODEL_FALLBACK_2=openai-codex/gpt-5.4
OPENCLAW_CONTROL_UI_ALLOWED_ORIGINS=https://你的-space-url.hf.space
OPENCLAW_SUPABASE_TABLE=openclaw_state
OPENCLAW_SYNC_INTERVAL_MS=300000
```

## Supabase

先在 Supabase SQL Editor 建這個 table：

```sql
create table if not exists openclaw_state (
  path text primary key,
  kind text not null,
  content text not null,
  sha256 text not null,
  size_bytes bigint not null,
  updated_at timestamptz not null,
  synced_at timestamptz not null
);
```

`SUPABASE_KEY` 要用：

- `service_role key`

不要用：

- `Publishable Key`
- `Anon Key`

## Telegram 最小可用設定

如果你只是要 bot 先能用，只要：

```text
TELEGRAM_BOT_TOKEN=<你的 bot token>
```

其他 `OPENCLAW_TELEGRAM_*` 都不是必填。

## Persistent Storage

建議開啟 HF Space 的 persistent storage。

原因：

- OpenClaw 狀態會存在 `/data/.openclaw`
- 如果之後 `openai-codex/gpt-5.4` 要用到持久化 auth，沒有 persistent storage 會不穩

## 部署後怎麼檢查

看 Space logs，至少確認：

1. `setup-hf-config.mjs` 有執行
2. 出現 `model=huggingface/Qwen/Qwen3-8B`
3. 出現 `fallbacks=2`
4. 出現 `supabase=1`
5. gateway listen 在 `0.0.0.0:7860`

再確認：

1. Control UI 能打開
2. 可以用 `OPENCLAW_GATEWAY_TOKEN` 登入
3. Supabase 的 `openclaw_state` 有同步資料

## 關於 `openai-codex/gpt-5.4`

目前 `openai-codex/gpt-5.4` 是 fallback，不是 primary。

這樣做的好處是：

- 主要流量先走 Qwen
- Qwen 不行再走 DeepSeek
- Codex 放最後

但要注意：

- 如果 `openai-codex/gpt-5.4` 還沒完成它需要的登入或授權
- 真正切到第三個 fallback 時，仍然可能失敗

所以目前最穩的理解方式是：

- `Qwen + DeepSeek` 保證主流程
- `Codex` 先保留在 fallback 鏈

## 最後的最小清單

### 必填 Secrets

```text
OPENCLAW_GATEWAY_TOKEN
HF_TOKEN
SUPABASE_URL
SUPABASE_KEY
```

### 必填 Variables

```text
OPENCLAW_MODEL_PRIMARY=huggingface/Qwen/Qwen3-8B
OPENCLAW_MODEL_FALLBACK_1=huggingface/deepseek-ai/DeepSeek-R1
OPENCLAW_MODEL_FALLBACK_2=openai-codex/gpt-5.4
```

### 建議 Variables

```text
OPENCLAW_CONTROL_UI_ALLOWED_ORIGINS=https://你的-space-url.hf.space
OPENCLAW_SUPABASE_TABLE=openclaw_state
OPENCLAW_SYNC_INTERVAL_MS=300000
```