Add files via upload

docs/en-US/troubleshooting.md

@@ -0,0 +1,98 @@
+# Troubleshooting
+
+[中文](../zh-CN/troubleshooting.md)
+
+Debug by layer. Do not change random config before locating the failing layer.
+
+## Diagnostic Order
+
+1. Process: is the service alive, any panic?
+2. Network: port, HTTPS, reverse proxy, browser console.
+3. Auth: does `/api/auth/validate` return 200?
+4. Config: can `/api/config` be read and applied?
+5. Model: does model test pass?
+6. Tools: do tool list and schemas look right?
+7. Database: is `data/` writable, any lock?
+8. Subsystem: KB, MCP, C2, WebShell minimal action.
+
+## Minimal Commands
+
+```bash
+lsof -i :8080
+curl -k -I https://127.0.0.1:8080/
+curl -k -I https://127.0.0.1:8080/static/logo.png
+ls -lh data/
+```
+
+If a reverse proxy is involved, test both proxy address and upstream address.
+
+## Common Issues
+
+Page inaccessible:
+
+- wrong protocol, especially HTTPS vs HTTP;
+- self-signed cert warning;
+- port occupied;
+- reverse proxy loop.
+
+Login fails:
+
+- wrong `auth.password`;
+- config not applied/restarted;
+- stale cookie;
+- audit throttling repeated failures.
+
+Model fails:
+
+- wrong `base_url` path;
+- invalid API key;
+- model unavailable;
+- reasoning fields unsupported by gateway. Try `openai.reasoning.mode: off`.
+
+Streaming stalls:
+
+- proxy buffers SSE;
+- model gateway timeout;
+- context too large;
+- browser/network interruption.
+
+Tool fails:
+
+- real command not installed;
+- YAML schema wrong;
+- HITL rejected or pending;
+- timeout or no-output timeout.
+
+Knowledge base empty:
+
+- `knowledge.enabled` false;
+- scan/index not run;
+- embedding API failed;
+- threshold or risk type too strict.
+
+C2 returns 503:
+
+- expected when `c2.enabled: false`.
+
+## Common Misdiagnoses
+
+- "Model is broken": HITL is waiting.
+- "Tool missing": tool_search hides it from current context.
+- "Knowledge base useless": index not rebuilt or risk type too narrow.
+- "Config saved but ineffective": listener/TLS changes need restart.
+- "Robot silent": platform callback or signature config wrong.
+
+## Issue Template
+
+```text
+Version:
+Startup method:
+Access path:
+Relevant config:
+Steps:
+Expected:
+Actual:
+Server logs:
+Browser console:
+API response:
+```