Goal: pin down "won't install / won't start / can't reach the model" to a root cause within 30 minutes.
Quick Self-check (in this order)
- Does the Node / runtime version meet the docs' requirements
- Port conflicts (is the default service port already taken by another process)
- Is the model API Key valid, and is the correct
base_urlset - Directory permissions (are the logs and workspace writable)
- Is a proxy / corporate network blocking the model domains
- The Docker path: is the image fully pulled, and do the volume-mount paths exist
Symptom → Likely Cause
| Symptom | Check first |
|---|---|
| Command not found | PATH, the package manager's global bin, wrong Node version installed |
| Exits seconds after launch | Read the latest log; missing env; port conflict |
| Starts but no response | Model key 401; balance; wrong base_url |
| Channel QR login fails | Phone network, expired QR code, session-directory permissions |
| Works inside Docker but unreachable from the host | Port mapping, firewall, bind address 127.0.0.1 vs 0.0.0.0 |
Minimal Repro for Model Connectivity
Run one bare request first, with the same Key OpenClaw uses:
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"ping"}]}'
- Fails here → fix the key/network first; don't blame OpenClaw yet
- Succeeds here but OpenClaw still fails → compare the model id and base_url in your config
For Chinese models, see the OpenAI-compatible endpoints on ChinaModelAPI.
Docker Specifics
- Confirm
docker compose psshows everything healthy - Check
docker compose logs --tail=200 - Back up session data before recreating a volume
Info to Collect If It Still Fails
- OS + install method (npm / desktop / docker)
- The first ERROR in the logs (don't just paste the last line)
- Model provider, and whether a proxy is involved
- Whether a "fresh install in a clean directory" reproduces the issue
For more deployment paths see the local deployment tutorial and cloud deployment.
目标：把“装不上 / 起不来 / 连不上模型”压缩到 30 分钟内定位。
快速自检（按顺序）
- Node / 运行时版本是否满足文档要求
- 端口占用（默认服务端口是否被其他进程占用）
- 模型 API Key 是否有效、是否设置了正确
base_url - 目录权限（日志、workspace 是否可写）
- 代理/公司网络是否拦截模型域名
- Docker 路径：镜像是否拉全、卷挂载路径是否存在
症状 → 可能原因
| 症状 | 优先检查 |
|---|---|
| 命令找不到 | PATH、包管理器全局 bin、是否装错 Node 版本 |
| 启动秒退 | 读最新日志；缺 env；端口冲突 |
| 能启动但无响应 | 模型密钥 401；余额；base_url 写错 |
| 通道扫码失败 | 手机网络、二维码过期、会话目录权限 |
| Docker 内正常宿主机不通 | 端口映射、防火墙、bind 地址 127.0.0.1 vs 0.0.0.0 |
模型连接最小复现
用与 OpenClaw 相同的 Key 先跑一次裸请求：
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"ping"}]}'- 这里失败 → 先修密钥/网络，别先怀疑 OpenClaw
- 这里成功但 OpenClaw 失败 → 对比配置里的 model id 与 base_url
中国模型可参考 ChinaModelAPI 的 OpenAI 兼容端点。
Docker 专项
- 确认
docker compose ps全 healthy - 看
docker compose logs --tail=200 - 重新创建 volume 前先备份会话数据
仍失败时收集的信息
- OS + 安装方式（npm / desktop / docker）
- 日志中第一条 ERROR（不要只贴最后一行）
- 模型提供商与是否走代理
- 是否可复现“干净目录新装”
目標：「インストールできない／起動しない／モデルにつながらない」を 30 分以内に切り分けること。
クイック自己診断（上から順に）
- Node / ランタイムのバージョンがドキュメントの要件を満たしているか
- ポート占有（デフォルトのサービスポートが他のプロセスに使われていないか）
- モデル API キーが有効か、正しい
base_urlが設定されているか - ディレクトリ権限（ログと workspace が書き込み可能か）
- プロキシ／社内ネットワークがモデルドメインを遮断していないか
- Docker の経路：イメージを完全に取得したか、ボリュームマウントのパスは存在するか
症状 → 考えられる原因
| 症状 | まず確認 |
|---|---|
| コマンドが見つからない | PATH、パッケージマネージャのグローバル bin、Node バージョンの入れ間違い |
| 起動後数秒で終了 | 最新ログを読む；env 不足；ポート競合 |
| 起動するが反応がない | モデルキー 401；残高；base_url の書き間違い |
| チャネルの QR ログイン失敗 | スマホのネットワーク、QR コードの期限切れ、セッションディレクトリの権限 |
| Docker 内は正常だがホストからつながらない | ポートマッピング、ファイアウォール、bind アドレス 127.0.0.1 vs 0.0.0.0 |
モデル接続の最小再現
OpenClaw と同じキーで、まず素のリクエストを 1 回流します：
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"ping"}]}'
- ここで失敗 → まずキー／ネットワークを修正し、OpenClaw を疑うのは後
- ここは成功し OpenClaw だけ失敗 → 設定の model id と base_url を見直す
中国のモデルは ChinaModelAPI の OpenAI 互換エンドポイントを参照できます。
Docker の個別チェック
docker compose psですべて healthy か確認docker compose logs --tail=200を確認- volume を作り直す前にセッションデータをバックアップ
それでも失敗するときに集める情報
- OS ＋ インストール方法（npm / desktop / docker）
- ログの最初の ERROR（最終行だけ貼らない）
- モデルプロバイダとプロキシ経由の有無
- 「クリーンなディレクトリへの新規インストール」で再現するか
他のデプロイ経路は ローカルデプロイチュートリアル と クラウドデプロイ を参照してください。
目標：把「裝不上 / 起不來 / 連不上模型」壓縮到 30 分鐘內定位。
快速自檢（按順序）
- Node / 執行時版本是否滿足文件要求
- 連接埠占用（預設服務連接埠是否被其他程序占用）
- 模型 API Key 是否有效、是否設定了正確的
base_url - 目錄權限（日誌、workspace 是否可寫）
- 代理/公司網路是否攔截模型網域
- Docker 路徑：映像檔是否拉全、卷掛載路徑是否存在
症狀 → 可能原因
| 症狀 | 優先檢查 |
|---|---|
| 找不到命令 | PATH、套件管理器全域 bin、是否裝錯 Node 版本 |
| 啟動秒退 | 讀最新日誌；缺 env；連接埠衝突 |
| 能啟動但無回應 | 模型金鑰 401；餘額；base_url 寫錯 |
| 通道掃碼失敗 | 手機網路、QR Code 過期、工作階段目錄權限 |
| Docker 內正常但宿主機不通 | 連接埠映射、防火牆、bind 位址 127.0.0.1 vs 0.0.0.0 |
模型連線最小重現
用與 OpenClaw 相同的 Key 先跑一次裸請求：
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"ping"}]}'
- 這裡失敗 → 先修金鑰/網路，別先懷疑 OpenClaw
- 這裡成功但 OpenClaw 失敗 → 對比設定裡的 model id 與 base_url
中國模型可參考 ChinaModelAPI 的 OpenAI 相容端點。
Docker 專項
- 確認
docker compose ps全 healthy - 看
docker compose logs --tail=200 - 重新建立 volume 前先備份工作階段資料
仍失敗時收集的資訊
- OS + 安裝方式（npm / desktop / docker）
- 日誌中第一條 ERROR（不要只貼最後一行）
- 模型供應商與是否走代理
- 是否可重現「乾淨目錄新裝」
Ziel: „installiert sich nicht / startet nicht / erreicht das Modell nicht“ innerhalb von 30 Minuten auf eine Ursache eingrenzen.
Schnelle Selbstprüfung (in dieser Reihenfolge)
- Erfüllt die Node-/Runtime-Version die Anforderungen der Dokumentation
- Portkonflikte (ist der Standard-Service-Port bereits von einem anderen Prozess belegt)
- Ist der Modell-API-Key gültig und ist die korrekte
base_urlgesetzt - Verzeichnisberechtigungen (sind Logs und workspace beschreibbar)
- Blockiert ein Proxy / Firmennetzwerk die Modell-Domains
- Der Docker-Weg: Wurde das Image vollständig heruntergeladen und existieren die Pfade der Volume-Mounts
Symptom → wahrscheinliche Ursache
| Symptom | Zuerst prüfen |
|---|---|
| Command not found | PATH, das globale bin des Paketmanagers, falsche Node-Version installiert |
| Bricht Sekunden nach dem Start ab | Das neueste Log lesen; fehlende env; Portkonflikt |
| Startet, aber keine Antwort | Modell-Key 401; Guthaben; falsche base_url |
| QR-Login des Kanals schlägt fehl | Mobilfunknetz, abgelaufener QR-Code, Berechtigungen des Sitzungsverzeichnisses |
| Funktioniert in Docker, vom Host aber nicht erreichbar | Port-Mapping, Firewall, Bind-Adresse 127.0.0.1 vs 0.0.0.0 |
Minimale Reproduktion der Modellverbindung
Senden Sie zuerst eine einzige, direkte Anfrage mit demselben Key, den OpenClaw verwendet:
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"ping"}]}'
- Schlägt sie fehl → zuerst Key/Netzwerk reparieren; OpenClaw noch nicht beschuldigen
- Gelingt sie, OpenClaw schlägt aber weiterhin fehl → model id und base_url in Ihrer Konfiguration vergleichen
Für chinesische Modelle sehen Sie sich die OpenAI-kompatiblen Endpunkte auf ChinaModelAPI an.
Docker-Spezifika
- Bestätigen Sie, dass
docker compose psdurchgängig healthy anzeigt - Prüfen Sie
docker compose logs --tail=200 - Sichern Sie die Sitzungsdaten, bevor Sie ein Volume neu erstellen
Informationen, die Sie bei anhaltendem Fehlschlag sammeln sollten
- OS + Installationsmethode (npm / desktop / docker)
- Der erste ERROR im Log (nicht nur die letzte Zeile einfügen)
- Modellanbieter und ob ein Proxy beteiligt ist
- Ob eine „Frischinstallation in einem sauberen Verzeichnis“ das Problem reproduziert
Weitere Bereitstellungswege finden Sie im Tutorial zur lokalen Bereitstellung und in der Cloud-Bereitstellung.
Objectif : circonscrire « ne s'installe pas / ne démarre pas / ne joint pas le modèle » jusqu'à la cause racine en moins de 30 minutes.
Autodiagnostic rapide (dans cet ordre)
- La version de Node / du runtime répond-elle aux exigences de la documentation
- Conflits de ports (le port de service par défaut est-il déjà occupé par un autre processus)
- La clé API du modèle est-elle valide et le bon
base_urlest-il défini - Permissions des répertoires (les logs et le workspace sont-ils accessibles en écriture)
- Un proxy / réseau d'entreprise bloque-t-il les domaines du modèle
- La voie Docker : l'image est-elle entièrement téléchargée et les chemins de montage des volumes existent-ils
Symptôme → Cause probable
| Symptôme | Vérifier d'abord |
|---|---|
| Command not found | PATH, le bin global du gestionnaire de paquets, mauvaise version de Node installée |
| S'arrête quelques secondes après le lancement | Lire le dernier log ; env manquant ; conflit de port |
| Démarre mais ne répond pas | Clé du modèle 401 ; solde ; mauvais base_url |
| Échec du login QR du canal | Réseau du téléphone, code QR expiré, permissions du répertoire de session |
| Fonctionne dans Docker mais inaccessible depuis l'hôte | Mapping de ports, pare-feu, adresse de bind 127.0.0.1 vs 0.0.0.0 |
Reproduction minimale de la connectivité au modèle
Envoyez d'abord une requête directe unique, avec la même clé qu'utilise OpenClaw :
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"ping"}]}'
- Échoue ici → corrigez d'abord la clé/le réseau ; n'incriminez pas encore OpenClaw
- Réussit ici mais OpenClaw échoue encore → comparez le model id et le base_url de votre configuration
Pour les modèles chinois, consultez les points de terminaison compatibles OpenAI sur ChinaModelAPI.
Spécificités Docker
- Confirmez que
docker compose psaffiche tout healthy - Vérifiez
docker compose logs --tail=200 - Sauvegardez les données de session avant de recréer un volume
Informations à collecter si l'échec persiste
- OS + méthode d'installation (npm / desktop / docker)
- La première ERROR dans les logs (ne collez pas seulement la dernière ligne)
- Le fournisseur du modèle et l'éventuelle présence d'un proxy
- Si une « installation à neuf dans un répertoire propre » reproduit le problème
Pour d'autres voies de déploiement, voir le tutoriel de déploiement local et le déploiement cloud.
Objetivo: acotar «no se instala / no arranca / no alcanza el modelo» hasta la causa raíz en menos de 30 minutos.
Autodiagnóstico rápido (en este orden)
- ¿La versión de Node / del runtime cumple los requisitos de la documentación?
- Conflictos de puertos (¿está ya ocupado el puerto de servicio por defecto por otro proceso?)
- ¿La API Key del modelo es válida y el
base_urlcorrecto está configurado? - Permisos de directorios (¿los logs y el workspace permiten escritura?)
- ¿Un proxy / red corporativa está bloqueando los dominios del modelo?
- La vía Docker: ¿se descargó la imagen por completo y existen las rutas de montaje de los volúmenes?
Síntoma → Causa probable
| Síntoma | Comprobar primero |
|---|---|
| Command not found | PATH, el bin global del gestor de paquetes, versión de Node equivocada instalada |
| Se cierra a los segundos de arrancar | Leer el log más reciente; falta env; conflicto de puertos |
| Arranca pero no responde | Clave del modelo 401; saldo; base_url equivocado |
| Falla el inicio de sesión por QR del canal | Red del móvil, código QR caducado, permisos del directorio de sesión |
| Funciona dentro de Docker pero inaccesible desde el host | Mapeo de puertos, cortafuegos, dirección de bind 127.0.0.1 vs 0.0.0.0 |
Reproducción mínima de la conectividad con el modelo
Ejecuta primero una única petición directa, con la misma clave que usa OpenClaw:
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"ping"}]}'
- Falla aquí → corrige primero la clave/red; aún no culpes a OpenClaw
- Funciona aquí pero OpenClaw sigue fallando → compara el model id y el base_url de tu configuración
Para los modelos chinos, consulta los endpoints compatibles con OpenAI en ChinaModelAPI.
Puntos específicos de Docker
- Confirma que
docker compose psmuestre todo healthy - Revisa
docker compose logs --tail=200 - Haz una copia de seguridad de los datos de sesión antes de recrear un volumen
Información que recopilar si sigue fallando
- SO + método de instalación (npm / desktop / docker)
- El primer ERROR de los logs (no pegues solo la última línea)
- Proveedor del modelo y si interviene un proxy
- Si una «instalación desde cero en un directorio limpio» reproduce el problema
Para más vías de despliegue, consulta el tutorial de despliegue local y el despliegue en la nube.
Objetivo: acotar «no se instala / no arranca / no alcanza el modelo» hasta la causa raíz en menos de 30 minutos.
Autodiagnóstico rápido (en este orden)
- ¿La versión de Node / del runtime cumple los requisitos de la documentación?
- Conflictos de puertos (¿está ya ocupado el puerto de servicio por defecto por otro proceso?)
- ¿La API Key del modelo es válida y el
base_urlcorrecto está configurado? - Permisos de directorios (¿los logs y el workspace permiten escritura?)
- ¿Un proxy / red corporativa está bloqueando los dominios del modelo?
- La vía Docker: ¿se descargó la imagen por completo y existen las rutas de montaje de los volúmenes?
Síntoma → Causa probable
| Síntoma | Comprobar primero |
|---|---|
| Command not found | PATH, el bin global del gestor de paquetes, versión de Node equivocada instalada |
| Se cierra a los segundos de arrancar | Leer el log más reciente; falta env; conflicto de puertos |
| Arranca pero no responde | Clave del modelo 401; saldo; base_url equivocado |
| Falla el inicio de sesión por QR del canal | Red del móvil, código QR caducado, permisos del directorio de sesión |
| Funciona dentro de Docker pero inaccesible desde el host | Mapeo de puertos, cortafuegos, dirección de bind 127.0.0.1 vs 0.0.0.0 |
Reproducción mínima de la conectividad con el modelo
Ejecuta primero una única petición directa, con la misma clave que usa OpenClaw:
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"ping"}]}'
- Falla aquí → corrige primero la clave/red; aún no culpes a OpenClaw
- Funciona aquí pero OpenClaw sigue fallando → compara el model id y el base_url de tu configuración
Para los modelos chinos, consulta los endpoints compatibles con OpenAI en ChinaModelAPI.
Puntos específicos de Docker
- Confirma que
docker compose psmuestre todo healthy - Revisa
docker compose logs --tail=200 - Haz una copia de seguridad de los datos de sesión antes de recrear un volumen
Información que recopilar si sigue fallando
- SO + método de instalación (npm / desktop / docker)
- El primer ERROR de los logs (no pegues solo la última línea)
- Proveedor del modelo y si interviene un proxy
- Si una «instalación desde cero en un directorio limpio» reproduce el problema
Para más vías de despliegue, consulta el tutorial de despliegue local y el despliegue en la nube.
Obiettivo: ricondurre "non si installa / non si avvia / non raggiunge il modello" alla causa radice entro 30 minuti.
Autodiagnosi rapida (in quest'ordine)
- La versione di Node / del runtime soddisfa i requisiti della documentazione
- Conflitti di porte (la porta di servizio predefinita è già occupata da un altro processo)
- La API Key del modello è valida e il
base_urlcorretto è impostato - Permessi delle directory (i log e il workspace sono scrivibili)
- Un proxy / rete aziendale sta bloccando i domini del modello
- La via Docker: l'immagine è stata scaricata completamente e i percorsi di montaggio dei volumi esistono
Sintomo → Causa probabile
| Sintomo | Controllare prima |
|---|---|
| Command not found | PATH, il bin globale del gestore di pacchetti, versione di Node installata errata |
| Esce pochi secondi dopo l'avvio | Leggere l'ultimo log; env mancante; conflitto di porte |
| Parte ma non risponde | Chiave del modello 401; saldo; base_url errato |
| Il login QR del canale non riesce | Rete del telefono, codice QR scaduto, permessi della directory di sessione |
| Funziona dentro Docker ma irraggiungibile dall'host | Mapping delle porte, firewall, indirizzo di bind 127.0.0.1 vs 0.0.0.0 |
Riproduzione minima della connettività al modello
Eseguire prima una singola richiesta diretta, con la stessa chiave che usa OpenClaw:
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"ping"}]}'
- Fallisce qui → correggere prima chiave/rete; non dare ancora la colpa a OpenClaw
- Riesce qui ma OpenClaw fallisce ancora → confrontare il model id e il base_url nella propria configurazione
Per i modelli cinesi, vedere gli endpoint compatibili OpenAI su ChinaModelAPI.
Specificità di Docker
- Confermare che
docker compose psmostri tutto healthy - Controllare
docker compose logs --tail=200 - Eseguire il backup dei dati di sessione prima di ricreare un volume
Informazioni da raccogliere se il fallimento persiste
- OS + metodo di installazione (npm / desktop / docker)
- Il primo ERROR nei log (non incollare solo l'ultima riga)
- Provider del modello ed eventuale presenza di un proxy
- Se un'"installazione da zero in una directory pulita" riproduce il problema
Per altri percorsi di distribuzione, vedere il tutorial di distribuzione locale e la distribuzione cloud.
목표: "설치 안 됨 / 시작 안 됨 / 모델 연결 안 됨"을 30분 이내에 근본 원인까지 좁히는 것입니다.
빠른 자가 진단 (이 순서대로)
- Node / 런타임 버전이 문서의 요구 사항을 충족하는지 확인하세요
- 포트 충돌 (기본 서비스 포트를 다른 프로세스가 이미 점유하고 있는지)
- 모델 API Key가 유효한지, 올바른
base_url이 설정되어 있는지 확인하세요 - 디렉터리 권한 (로그와 workspace가 쓰기 가능한지)
- 프록시 / 사내 네트워크가 모델 도메인을 차단하고 있는지 확인하세요
- Docker 경로: 이미지를 온전히 받았는지, 볼륨 마운트 경로가 존재하는지 확인하세요
증상 → 예상 원인
| 증상 | 먼저 확인할 것 |
|---|---|
| Command not found | PATH, 패키지 매니저의 전역 bin, 잘못된 Node 버전 설치 |
| 시작 후 몇 초 만에 종료됨 | 최신 로그 읽기; env 누락; 포트 충돌 |
| 시작은 되지만 응답 없음 | 모델 키 401; 잔액; 잘못된 base_url |
| 채널 QR 로그인 실패 | 휴대폰 네트워크, 만료된 QR 코드, 세션 디렉터리 권한 |
| Docker 내부에서는 정상이지만 호스트에서 접근 불가 | 포트 매핑, 방화벽, bind 주소 127.0.0.1 vs 0.0.0.0 |
모델 연결 최소 재현
OpenClaw가 사용하는 것과 동일한 Key로 먼저 단순 요청 한 번을 실행해 보세요:
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"ping"}]}'
- 여기서 실패 → 먼저 키/네트워크를 수정하세요. 아직 OpenClaw를 의심하지 마세요
- 여기서는 성공하지만 OpenClaw가 계속 실패 → 설정의 model id와 base_url을 비교해 보세요
중국 모델은 ChinaModelAPI의 OpenAI 호환 엔드포인트를 참고하세요.
Docker 세부 사항
docker compose ps에서 모두 healthy로 표시되는지 확인하세요docker compose logs --tail=200을 확인하세요- volume을 다시 만들기 전에 세션 데이터를 백업하세요
그래도 실패할 때 수집할 정보
- OS + 설치 방법 (npm / desktop / docker)
- 로그에서 첫 번째 ERROR (마지막 줄만 붙여넣지 마세요)
- 모델 제공사와 프록시 사용 여부
- "깨끗한 디렉터리에 신규 설치" 시 문제가 재현되는지 여부
더 많은 배포 경로는 로컬 배포 튜토리얼과 클라우드 배포를 참고하세요.
الهدف: حصر "لا يُثبَّت / لا يعمل / لا يتصل بالنموذج" في السبب الجذري خلال 30 دقيقة.
فحص ذاتي سريع (بهذا الترتيب)
- هل إصدار Node / بيئة التشغيل يلبي متطلبات التوثيق
- تعارض المنافذ (هل منفذ الخدمة الافتراضي محجوز بالفعل لعملية أخرى)
- هل مفتاح API للنموذج صالح وهل ضُبط
base_urlالصحيح - أذونات المجلدات (هل السجلات و workspace قابلان للكتابة)
- هل البروكسي / شبكة الشركة يحجب نطاقات النموذج
- مسار Docker: هل سُحبت الصورة بالكامل وهل مسارات ربط الأقراص موجودة
العَرَض → السبب المحتمل
| العَرَض | ما تتحقق منه أولًا |
|---|---|
| Command not found | متغير PATH، ومجلد bin العام لمدير الحزم، وتثبيت إصدار خاطئ من Node |
| يخرج بعد ثوانٍ من التشغيل | اقرأ أحدث سجل؛ متغير env ناقص؛ تعارض المنافذ |
| يعمل لكن دون استجابة | مفتاح النموذج 401؛ الرصيد؛ خطأ في base_url |
| فشل تسجيل الدخول عبر رمز QR للقناة | شبكة الهاتف، انتهاء صلاحية رمز QR، أذونات مجلد الجلسة |
| يعمل داخل Docker لكن يتعذر الوصول إليه من الجهاز المضيف | تخطيط المنافذ، وجدار الحماية، وعنوان الربط 127.0.0.1 vs 0.0.0.0 |
أدنى خطوة لإعادة إنتاج الاتصال بالنموذج
أرسل أولًا طلبًا مباشرًا واحدًا بنفس المفتاح الذي يستخدمه OpenClaw:
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"ping"}]}'
- فشل هنا → أصلح المفتاح/الشبكة أولًا؛ لا تلُم OpenClaw بعد
- نجح هنا لكن OpenClaw ما زال يفشل → قارن model id و base_url في الإعدادات
بالنسبة للنماذج الصينية، راجع نقاط النهاية المتوافقة مع OpenAI على ChinaModelAPI.
تفاصيل خاصة بـ Docker
- تأكد من أن
docker compose psيعرض كل شيء بحالة healthy - تحقق من
docker compose logs --tail=200 - انسخ بيانات الجلسة احتياطيًا قبل إعادة إنشاء volume
المعلومات التي تُجمع إذا استمر الفشل
- نظام التشغيل + طريقة التثبيت (npm / desktop / docker)
- أول ERROR في السجلات (لا تلصق السطر الأخير فقط)
- مزوّد النموذج، وهل هناك بروكسي معني
- هل "تثبيت جديد في مجلد نظيف" يعيد إنتاج المشكلة
لمزيد من مسارات النشر، راجع دليل النشر المحلي والنشر السحابي.