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

請加入：

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

如果你要 Telegram，再加：

TELEGRAM_BOT_TOKEN=<你的 telegram bot token>

Variables

請加入：

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：

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 先能用，只要：

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

OPENCLAW_GATEWAY_TOKEN
HF_TOKEN
SUPABASE_URL
SUPABASE_KEY

必填 Variables

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

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