docs(guide): rewrite CLAUDE.md with ZCLAW-first perspective

Major changes:
- Shift from "OpenFang desktop client" to "independent AI Agent desktop app"
- Add decision principle: "Is this useful for ZCLAW? Does it affect ZCLAW?"
- Simplify project structure and tech stack sections
- Replace OpenClaw vs OpenFang comparison with unified backend approach
- Consolidate troubleshooting from scattered sections into organized FAQ
- Update Hands system documentation with 8 capabilities and status
- Stream

docs/knowledge-base/troubleshooting.md

@@ -729,7 +729,81 @@ ctx.fillStyle = '#f9fafb'; // gray-50 (浅色)
 
 ---
 
-## 8. 相关文档
+## 8. 端口配置问题
+
+### 8.1 OpenFang 端口不匹配导致 Network Error
+
+**症状**: 创建 Agent 或其他 API 操作时报错 `Failed to create agent: Network Error`，控制台显示 `POST http://localhost:1420/api/agents net::ERR_CONNECTION_REFUSED`
+
+**根本原因**: `runtime-manifest.json` 声明端口 4200，但实际 OpenFang 运行在 **50051** 端口
+
+**正确配置**:
+
+| 配置位置 | 正确端口 |
+|---------|----------|
+| `runtime-manifest.json` | 4200 (声明，但实际不使用) |
+| **实际运行端口** | **50051** |
+| `vite.config.ts` 代理 | **50051** |
+| `gateway-client.ts` | **50051** |
+
+**解决方案**:
+
+1. 更新 `vite.config.ts`:
+```typescript
+proxy: {
+  '/api': {
+    target: 'http://127.0.0.1:50051',  // 使用实际运行端口
+    // ...
+  },
+}
+```
+
+2. 更新 `gateway-client.ts`:
+```typescript
+export const DEFAULT_GATEWAY_URL = `${DEFAULT_WS_PROTOCOL}127.0.0.1:50051/ws`;
+export const FALLBACK_GATEWAY_URLS = [
+  DEFAULT_GATEWAY_URL,
+  `${DEFAULT_WS_PROTOCOL}127.0.0.1:4200/ws`,  // 保留作为备选
+];
+```
+
+**验证端口**:
+```bash
+# 检查实际运行的端口
+netstat -ano | findstr "50051"
+netstat -ano | findstr "4200"
+```
+
+**注意**: `runtime-manifest.json` 中的端口声明与实际运行端口不一致，以实际监听端口为准。
+
+**涉及文件**:
+- `desktop/vite.config.ts` - Vite 代理配置
+- `desktop/src/lib/gateway-client.ts` - WebSocket 客户端默认 URL
+- `desktop/src/components/Settings/General.tsx` - 设置页面显示地址
+- `desktop/src/components/Settings/ModelsAPI.tsx` - 模型 API 重连逻辑
+
+**排查流程**:
+1. 先用 `netstat` 确认实际监听端口
+2. 对比 `runtime-manifest.json` 声明端口与实际端口
+3. 确保所有前端配置使用**实际监听端口**
+4. 重启 Vite 开发服务器
+
+**验证修复**:
+```bash
+# 检查端口监听
+netstat -ano | findstr "50051"
+# 应显示 LISTENING
+
+# 重启 Vite 后测试
+curl http://localhost:1420/api/agents
+# 应返回 JSON 数组而非 404/502
+```
+
+**文件**: 多个配置文件
+
+---
+
+## 9. 相关文档
 
 - [OpenFang 配置指南](./openfang-configuration.md) - 配置文件位置、格式和最佳实践
 - [Agent 和 LLM 提供商配置](./agent-provider-config.md) - Agent 管理和 Provider 配置
@@ -741,6 +815,7 @@ ctx.fillStyle = '#f9fafb'; // gray-50 (浅色)
 
 | 日期 | 变更 |
 |------|------|
+| 2026-03-20 | 添加端口配置问题：runtime-manifest.json 声明 4200 但实际运行 50051 |
 | 2026-03-18 | 添加记忆提取和图谱 UI 问题 |
 | 2026-03-18 | 添加刷新后对话丢失问题和 ChatArea 布局问题 |
 | 2026-03-17 | 添加首次使用引导流程 |