安装¶

本页将引导你在 5 分钟内完成 OLAV 的安装和初始化。

功能声明

ID	声明	状态
C-L2-01	`olav version` 正确报告版本号	✅ v0.18.0
C-L2-13	`olav init` 创建项目目录结构	✅ v0.18.0

环境要求¶

依赖	说明
Python 3.11+	OLAV 的运行环境
LLM API Key	支持 OpenAI、Anthropic、Ollama（本地）等多种提供商

第一步：安装¶

pip install（推荐）从源码安装（开发）

pip install olav

git clone https://github.com/olav-ai/olav.git
cd olav
uv sync

开发模式

源码安装后，所有 olav 命令需加 uv run 前缀，如 uv run olav version。以下文档示例均使用 pip install 后的裸 olav 命令。

验证安装是否成功：

olav version

看到类似输出即表示安装成功：

OLAV v0.24.1

第二步：直接运行 —— OLAV 自己完成初始化¶

进入你的工作目录，直接运行：

olav

首次运行时 OLAV 会检测到尚未初始化，自动完成全部准备工作——目录、数据库、核心 Agent、本地嵌入模型——然后只询问一件它无法推断的事：

First run detected — setting up OLAV...
No LLM API key configured yet.
Paste your LLM API key: ********
✓ API key saved to .olav/config/api.json

到此为止，你已经进入交互式 TUI，可以直接提问。欢迎页展示的是你的真实状态——如果有需要注意的事项（嵌入后端不可用、还没有导入设备数据），它会直接说明并给出解决办法，而不是显示一条随机提示语。

随时健康体检

olav doctor          # 在 shell 中
/doctor              # 在 TUI 内

零 LLM 的确定性探测：脚手架、LLM 连通性、嵌入后端——每个失败项都附带可执行的修复动作。

`olav doctor` 检查什么¶

olav doctor 是一次快速、零 LLM 的预检。它从不崩溃 —— 8 项检查每项给出一个 ✓ / ⚠ 结论：

检查项	验证内容
`scaffolding`	`.olav/` 目录、配置、数据库是否就位
`llm`	LLM 端点可达、配置的模型有响应
`embedding`	嵌入后端（本地模型或 API）是否可用
`agents`	顶层 SKILL.md 是否解析成功 —— N 已加载 / M 失败
`subagents`	每个子代理都被其父级声明、无孤儿目录
`tools`	每个 `@tool` 文件能否编译 —— 一个坏工具文件会拖垮它所属的 agent
`memory`	经验层是否已 prime？各类别计数 —— 0 条 guide 时 `⚠`
`recall`	一次冒烟探测：嵌入一条查询 + 一次检索确认召回链路已接通（不是精度基准 —— 精度用 `olav kb bench`）

输出示例：

✓ agents: 6 loaded, 0 failed
✓ subagents: 18 wired, 0 orphaned
✓ tools: 19 registered, 0 syntax error(s)
✓ memory: primed — 34 usage_guide · 13 reflection · 10 fact
✓ recall: responsive (3 hit(s) for probe) — `olav kb bench` for accuracy

olav doctor --json 以机器可读的 JSON 输出同样这些检查。

脚本化 / CI 场景

olav init 保留等价的非交互式初始化（永不弹出提问）。key 通过 OPENAI_API_KEY 环境变量提供，或事后编辑 .olav/config/api.json。

第三步：配置 API Key（手动 / 多 provider）¶

上面的交互式提问覆盖了最常见的单 provider 场景。多 provider、自定义 endpoint 或脚本化部署时，可直接编辑 .olav/config/api.json——或者 直接让 admin agent 帮你改：

olav --agent admin "把 LLM 换成 deepseek-chat，key 是 sk-..."
olav --agent admin "回滚我的 LLM 配置"     # 撤销上一次变更

通过对话修改的配置会先对真实 provider 验证再落盘——坏 key 或错误的模型名会带着 provider 的真实报错被拒绝，你正在使用的配置不受影响。每次生效的变更都会先快照旧配置，因此一句话回滚永远可用。

三种部署模式 — 按你的环境选

OLAV 设计了三档独立可切的部署：Layer 1 全本地（无 cloud key）、Layer 2 LLM-only（极简，无 embed/rerank）、Layer 3 全 cloud（最高质量）。下面的 quickstart 示例侧重 cloud LLM；完整三档 ready-to-paste 配置见配置参考 → 部署模式。

api.json 中可以用 shared.api_key 统一管理密钥（homogeneous 部署）；多 provider 部署则在每个 section 的 api_key 单独配置（per-section 优先于 shared）：

OpenAIAnthropicOpenRouter（多模型聚合）Ollama（本地离线）

{
  "shared": { "api_key": "sk-..." },
  "llm": { "provider": "openai", "model": "gpt-4o" },
  "embedding": { "mode": "api", "api": { "model": "openai/text-embedding-3-small" } }
}

{
  "shared": { "api_key": "sk-ant-..." },
  "llm": { "provider": "anthropic", "model": "claude-3-5-sonnet-20241022" },
  "embedding": { "mode": "local" }
}

Anthropic 不提供 embedding API，使用本地模型（mode: local，自动下载 BAAI/bge）。

{
  "shared": { "api_key": "sk-or-..." },
  "llm": { "provider": "custom", "model": "openai/gpt-4o", "base_url": "https://openrouter.ai/api/v1" },
  "embedding": { "mode": "api", "api": { "model": "openai/text-embedding-3-small", "base_url": "https://openrouter.ai/api/v1" } }
}

{
  "llm": { "provider": "ollama", "model": "llama3.1", "base_url": "http://localhost:11434" },
  "embedding": { "mode": "local" }
}

完全离线，无需 API Key。

本地 embedding 模型与语言覆盖

零配置默认（embedding.mode: local）会自动下载 BAAI/bge-small-zh-v1.5——512 维、~90MB，为首次启动的最小体积而选。它中文优化、但英文也能处理，对大多数部署都是不错的起点。

对于英文为主或国际部署、英文配置/文档的检索质量很重要的场景，切换到多语言或英文模型——无需编辑文件，直接让 admin agent 处理（它会在保存前对新模型做实时校验，且一句话即可回滚）：

# 多语言（中英均衡），或指向本地 Ollama embedding 模型：
olav --agent admin "把 embedding 切换到多语言模型"
olav --agent admin "把 embedding 切到 api 模式，用本地 Ollama 的 \
  embeddinggemma，地址 http://localhost:11434/v1（api key 填 'ollama'）"
olav --agent admin "回滚我的 embedding 配置"   # 撤销

换模型会改变向量维度

不同模型输出不同维度（bge-small-zh = 512、bge-base-en = 768、 bge-m3 = 1024）。全新安装无影响；已有记忆表的安装上，OLAV 会以 EmbeddingDimMismatchError fail-fast 保护数据——刻意切换时需重新嵌入 / 重置记忆库。

保护你的密钥

api.json 包含 API 密钥，务必加入 .gitignore（olav init 已自动处理）。

环境变量方式

不想在文件中存储密钥时，可通过环境变量覆盖（优先级高于 api.json）：

export OLAV_LLM_API_KEY="sk-..."       # 覆盖 shared.api_key
export OLAV_LLM_MODEL="gpt-4o"         # 覆盖 llm.model
export OPENAI_API_KEY="sk-..."          # OpenAI 快捷方式
export ANTHROPIC_API_KEY="sk-ant-..."   # Anthropic 快捷方式

创建的目录结构如下：

.olav/
├── config/
│   ├── api.json        ← LLM 和认证配置（包含密钥，不要提交到 git）
│   ├── services.yaml   ← 已注册的外部服务
│   └── settings.json   ← 平台设置（当前活跃 Agent 等）
├── databases/
│   ├── audit.duckdb    ← 审计日志（自动记录所有操作）
│   └── domain.duckdb   ← 业务数据（Agent 执行结果等）
└── workspace/
    └── core/           ← 预装的核心 Agent
        ├── AGENT.md    ← Agent 的能力定义
        └── MANIFEST.yaml ← 路由关键词和版本信息

第四步：安装领域技能（可选）¶

OLAV 核心提供数据库查询、API 集成、远程执行和平台管理。安装领域技能包可扩展专业能力：

网络运维企业功能可选依赖

pip install olav-netops
olav agent install olav-netops

pip install 从 PyPI 拉取包；olav agent install 随后解析已安装的包、部署其 workspace 并注册 agent（开发时也可传本地路径或 git URL：olav agent install /path/to/olav-netops/）。新增：SSH 采集（Nornir）、拓扑分析、漂移检测、ContainerLab 数字孪生、网络感知的审计健康检查。安装 netops agent，并让 audit 具备网络感知能力。用 olav list 验证（6 个 agent：admin、audit、core、devops、netops、services）。

pip install olav-ent

新增：SFT/trajectory 数据集导出、加密数据集、LDAP/OIDC 认证。

pip install olav[pdf]       # PDF 文档导入（知识库）
pip install olav[netops]    # 网络分析库（不含完整 olav-netops）
pip install olav[audit]     # ML 异常检测（scikit-learn, scipy）

验证 agent

安装后，检查可用 agent：

olav list
# 基础安装（5 个）：admin、audit、core、devops、services
# olav-netops 追加：netops   （并使 audit 具备网络感知能力）

第五步：设置 .gitignore¶

工作空间（workspace）可以安全提交到 git，与团队共享 Agent 定义。但配置和数据库不应提交：

# .gitignore
.olav/config/      # 包含 API 密钥
.olav/databases/   # 包含审计日志和业务数据
.olav/run/         # 运行时 PID 文件

git add .olav/workspace/
git commit -m "feat: init olav workspace"

下一步： 运行你的第一个查询 →

安装¶