Privix Agent 知识库

# Privix / OpenClaw 安装与使用知识库（Agent 版）

## 元信息
- 文档版本: 2026-04-14
- 适用产品: Privix v1.4.3（单一应用，按 license 启用 Invest / Knowledge / SOP 行业模块）
- 目标读者: AI Agent（钳子助手、ChatGPT、Claude 等）
- 用途: 回答用户关于安装、配置、使用、排障的问题

---

## 1. 产品定义

### Privix
- 定义: 基于 Tauri v2 的本地化 AI 桌面工作台
- 底层引擎: OpenClaw（开源个人 AI 助手平台）
- 平台: macOS（已发布）、Windows（待发布）、Linux（待发布）
- 安装包大小: ~10MB
- 默认端口: 面板 :1420, Gateway :18789
- 产品形态: 单一 Privix 应用，运行时按 license 启用行业模块
  - **Invest 模块** — 投资工作台，面向 PE/VC，含投资管理模块与完整管理台
  - **Knowledge 模块** — Agent 知识库，聚焦资料整理、检索与问答
  - **SOP 模块** — Agent SOP，聚焦规则维护、任务规划与结构化文档输出

### OpenClaw
- 定义: 开源个人 AI 助手平台，提供 Gateway、Agent、Channel 等核心能力
- 关系: Privix 以单一应用形态运行，Invest / Knowledge / SOP 行业模块均基于 OpenClaw 管理台能力构建
- CLI: 命令行工具，用于安装/配置/管理 OpenClaw
- Gateway: 核心后端服务，处理消息路由、Agent 执行、渠道连接
- 推荐版本: 2026.4.8

### 钳子助手
- 定义: Privix 内置的独立 AI 助手（不是 OpenClaw Agent）
- 用途: 排障、问答、日志分析、环境检查
- 独立性: 有自己的模型配置，不依赖 OpenClaw Gateway
- 优先级: 建议用户最先配置，作为后续排障的"第二双眼睛"

---

## 2. 安装流程

### macOS 安装
1. 从官网或 GitHub Releases 下载 .dmg 文件
2. 双击 .dmg，将应用图标拖入"应用程序"文件夹
3. 首次打开可能被 Gatekeeper 拦截
   - 错误信息: "无法打开...因为无法验证开发者" 或 "已损坏"
   - 解决: 系统设置 → 隐私与安全性 → 找到 Privix → 仍要打开
4. 首次启动自动进入"初始设置"

### Windows 安装
1. 下载 .exe 安装包
2. 双击运行，按提示完成安装
3. 常见问题: 管理员权限、npm 缓存、Git HTTPS 配置
4. Node.js PATH 问题: 重启应用刷新环境变量

### Linux 安装
- 无桌面环境建议走 Web 版部署
- 面板通过 :1420 访问
- Gateway 通过 :18789 管理

### 初始设置检查项
| 检查项 | 说明 | 失败处理 |
|--------|------|----------|
| Node.js | 运行环境 | 从 nodejs.org 下载安装 |
| Git | 版本控制 | 从 git-scm.com 下载安装 |
| OpenClaw CLI | 命令行工具 | 点击页面"安装"按钮 |
| 配置文件 | ~/.openclaw/openclaw.json | 点击"初始化"按钮 |

---

## 3. 推荐配置顺序

1. 安装 Privix → 完成初始设置
2. 配置钳子助手（优先！给它一个可用模型）
3. 配置模型（至少 1 个主模型，建议 1-2 个备选）
4. 启动 Gateway（服务管理/仪表盘页面）
5. 创建 Agent（Agent 管理页面）
6. 实时聊天验证（发第一条消息确认链路）
7. 接消息渠道（飞书/Telegram，可选）

---

## 4. 核心页面职责

| 页面 | 路由 | 职责 |
|------|------|------|
| 全局概览 | /overview | 单一应用默认首页，功能板块快速入口 |
| 初始设置 | /setup | 环境检查、OpenClaw 初始化 |
| 投资概览 | /invest-dashboard | 投资工作台仪表盘（PE/VC） |
| 仪表盘 | /dashboard | Gateway 状态、系统概览 |
| 钳子助手 | /assistant | 内置 AI 问答、排障卡片 |
| 模型配置 | /models | 服务商/模型管理、主备选设置 |
| Agent 管理 | /agents | 创建/编辑/备份 Agent |
| Skills | /skills | 已安装 Skills + SkillHub 商店 |
| 实时聊天 | /chat | 验证 Agent 回复、模型切换 |
| 多Agent会话 | /sessions | 多 Agent 并行会话管理 |
| 服务管理 | /services | Gateway 启停、版本、备份 |
| 消息渠道 | /channels | 飞书/Telegram/Discord 等接入 |
| 日志查看 | /logs | Gateway/错误/守护/审计日志 |
| 记忆文件 | /memory | Agent 工作记忆、归档 |
| 定时任务 | /cron | 定时规则管理 |
| 自动化 | /automation | 自动化中心、模板卡片 |
| Gateway | /gateway | Gateway 详细配置与监控 |
| 企业库 | /companies | 投资标的企业管理 |
| 联系人 | /contacts | 投资联系人管理 |
| 项目管道 | /pipeline | Deal Pipeline 看板 |
| 战略评分 | /scoring | 多维度交易评分 |
| SOP | /sop | 任务规划 + SOP 归纳 |
| 关于 | /about | 版本信息、下载链接 |
| EvoScientist | /evoscientist | 多科学家协作（4 Tab: 工作台/聊天/设置/架构） |
| Agentic Swarm | /clawswarm | 多智能体 DAG 任务编排 |
| Star Office | /star-office | 像素风 AI 办公室看板 |

---

## 5. 目录结构

```
~/.openclaw/
├── openclaw.json          # 主配置（JSON5，支持注释）
├── .env                   # 全局环境变量
├── workspace/             # main Agent 工作区
│   ├── IDENTITY.md        # Agent 身份
│   ├── SOUL.md            # Agent 人格
│   └── ...
├── agents/
│   ├── main/agent/        # main Agent 配置
│   │   ├── models.json    # 模型配置
│   │   └── auth-profiles.json
│   └── <agentId>/
│       ├── agent/
│       └── workspace/
├── skills/                # Agent Skills 目录
└── logs/                  # 日志文件
```

---

## 6. 当前版本重点

### SkillHub 技能商店
- Skills 页面新增"商店"标签页（Installed + Store 双 Tab）
- 在线浏览 SkillHub 完整技能索引，支持搜索和一键安装
- 替代旧版 CLI 命令（skillsClawHubSearch / skillsClawHubInstall 已移除）
- 后端改用 SkillHub SDK（scripts/lib/skillhub-sdk.js），不再依赖 OpenClaw CLI
- 支持按 Agent 分配不同 Skills 目录（agent_id 参数路由）

### Chat OpenClaw 4.5+ 兼容
- 支持 Agent 事件流：lifecycle、item、plan、approval、thinking、command_output
- 3 分钟超时保护（ultimate timeout），避免静默无回复
- 打字指示器显示实时经过时间
- 修复空灰气泡问题（0-content-chunk 检测）

### Gateway 稳定性增强
- 仪表盘刷新节流（5 秒），避免频繁请求
- TCP 连接重试机制
- 停止检测阈值 2→3 次
- 自动重启前增加 3 秒延迟 + 缓存失效

### 热更新移除
- 关于页面和更新横幅改为下载链接（指向官网和 GitHub Releases）
- 不再支持应用内热更新/回滚

### 助手 SkillHub 工具迁移
- 钳子助手工具：skills_clawhub_search → skillhub_search, skills_clawhub_install → skillhub_install
- 新增空流错误检测

---

## 7. 排障决策树

### 用户说"装不上"
1. 什么操作系统？
2. macOS → Gatekeeper 拦截？→ 系统设置放行
3. Windows → 管理员权限？npm/Git 问题？
4. 初始设置页面哪项红色？→ 按对应方案处理

### 用户说"聊天没回复"
1. Gateway 是否运行？→ 仪表盘/服务管理检查
2. 模型是否配置且测试通过？→ 模型配置检查
3. Agent 是否创建且绑定模型？→ Agent 管理检查
4. Gateway 认证是否拦截？→ 安全设置检查
5. 以上都正常 → 查看日志，找具体错误
6. 如果聊天显示"超时" → 当前版本有 3 分钟超时保护，检查模型响应速度

### 用户说"飞书/Telegram 不回复"
1. Gateway 是否运行？
2. 渠道配置是否保存？
3. 平台侧应用是否发布？
4. 机器人是否加入群/工作台？
5. 配对审批是否完成？

### 用户说"突然不工作了"
1. 最近是否切换了 OpenClaw 版本？
2. 最近是否改过模型配置/API Key？
3. 最近是否改过 Gateway 安全设置？
4. 用日志分析缩小范围，不要直接重装

### 用户说"Skills 装不了"
1. 当前版本使用 SkillHub 商店；旧版才需要 CLI
2. 网络是否能访问 SkillHub（检查代理设置）
3. Agent Skills 目录是否有写权限？
4. 查看钳子助手"Skills 管理"卡片诊断

---

## 8. 常见错误及解决

### ERR: macOS "已损坏"或"无法验证开发者"
- 原因: Gatekeeper 未签名应用拦截
- 解决: 系统设置 → 隐私与安全性 → 仍要打开

### ERR: Node.js 检测不到
- macOS: 从终端启动应用（PATH 问题）
- Windows: 重启应用（PATH 环境变量刷新）
- 彻底解决: 安装 Node.js LTS 版本

### ERR: Gateway 启动失败
- 检查端口 18789 是否被占用
- 检查 openclaw.json 格式是否正确
- 检查模型配置是否有效
- 检查 gateway.auth 认证模式
- 当前版本: Gateway 自动重启有 3 秒延迟，等待完成

### ERR: 模型连接超时
- 检查 API Key 是否正确
- 检查 Base URL 是否可达
- 检查网络代理设置
- 检查服务商侧服务状态

### ERR: Agent 不回复
- 确认 Gateway 运行中
- 确认 Agent 绑定了可用模型
- 确认实时聊天选择了正确的 Agent
- 查看日志中的具体错误信息
- 当前版本: 检查是否触发了 3 分钟超时保护

### ERR: SkillHub 搜索/安装失败
- 检查网络连接（可能需要代理）
- 确认 Privix 版本为当前发布版或更新
- 旧版本使用 CLI 命令，不支持 SkillHub SDK

---

## 9. 飞书接入要点
- 在飞书开放平台创建企业自建应用
- 开启机器人能力
- 获取 App ID 和 App Secret
- 事件订阅: 建议使用长连接（WebSocket）
- 配置字段: appId, appSecret, domain(feishu/lark), pluginVersion(builtin/official)
- 保存后完成配对审批
- 发布应用版本后机器人才对他人可见

## 10. Telegram 接入要点
- 通过 @BotFather 创建 Bot
- 获取 Bot Token
- 通过 @userinfobot 获取用户 ID
- 配置字段: botToken, allowedUsers
- 最轻量的外部渠道选择

---

## 11. AI 多Agent 系统

### EvoScientist 多科学家协作
- 路由: /evoscientist，通过 ?tab=workbench|chat|settings|architecture 切换
- 以 Coordinator 为核心，调度多个专属 Scientist 并行协作
- 支持 8 大 LLM Provider：Anthropic、OpenAI、Google GenAI、MiniMax 等
- 四维人格调控：严谨度、主动性、审慎度、架构思维（各 1-5）
- 内置 12 个案例模板，覆盖竞品分析、代码审查、市场测算、技术选型

### Agentic Swarm 蜂群协作
- 路由: /clawswarm
- 输入目标 → LLM 自动拆解 → DAG 审核 → 可视化 → 多智能体并行执行
- Kahn 拓扑排序 + DAG 验证
- 5 大预设模板：深度研究、尽调报告、头脑风暴、文档审校、竞品监控
- 支持直连 Anthropic/OpenAI/Gemini API（无需 Gateway）

### 多Agent 会话（Sessions）
- 路由: /sessions
- 支持多 Agent 并行会话，每个 Agent 独立上下文

---

## 12. SOP 任务规划系统

### 功能概述
- 任务规划器：描述目标 → AI 自动拆解为分步任务（DAG 依赖管理）
- 执行监督：超时告警、质量门槛、步骤回退（级联重置下游）
- 流程图可视化：自绘 SVG（Kahn 分层算法），状态着色，导出 SVG/PNG/Mermaid
- SOP 归纳器：从已完成计划提炼共性步骤模式，合并为标准模板

### 步骤状态流转
pending → ready → running → waiting_review → completed / failed / skipped

### 常见问题
- Q: AI 不可用时能否使用任务规划？
  A: 可以。内置关键词匹配降级方案，无需 AI 也能自动拆解。
- Q: 如何回退步骤？
  A: 点击回退按钮，下游依赖步骤级联重置为 pending。

---

## 13. 投资模块（启用 Invest 模块时可见）

### 核心模块
| 模块 | 路由 | 说明 |
|------|------|------|
| 投资概览 | /invest-dashboard | 项目池漏斗、管道分布、近期动态 |
| 企业库 | /companies | 被投及关注企业档案管理 |
| 联系人 | /contacts | 投资相关联系人，关联企业与角色标签 |
| 项目管道 | /pipeline | 六阶段 Deal Pipeline（寻源→初筛→尽调→IC→条款→关闭） |
| 战略评分 | /scoring | 多维度交易评分量化投资决策 |
| 自动化 | /automation | 定时任务与心跳规则，投后监控 |

---

## 14. 回答原则

### 当用户问"怎么安装"
- 先确认操作系统
- 给出对应平台安装步骤
- 提醒 macOS Gatekeeper 问题
- 引导完成初始设置

### 当用户问"怎么用"
- 推荐配置顺序（见第 3 节）
- 强调先配钳子助手
- 不要先讲概念，先讲操作路径

### 当用户问"为什么不工作"
- 使用排障决策树（见第 7 节）
- 先缩小层级: 环境 → 模型 → Gateway → Agent → 渠道
- 不要建议重装，先定位具体问题

### 当用户问"Skills 怎么装"
- 当前版本: 引导去 Skills 页面"商店"标签页搜索安装
- 旧版: 使用 CLI 命令（openclaw skill install）
- 提醒检查 Agent Skills 目录和网络连接

### 当用户是非技术用户
- 避免术语或立即解释
- 给出具体的点击路径而非命令行
- 引导到钳子助手获取进一步帮助

### 当用户是技术用户
- 可以给出 CLI 命令和配置文件路径
- 可以引用目录结构（第 5 节）
- 可以建议查看日志具体排查