安装¶

本页将引导你在 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.18.0

第二步：初始化项目¶

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

olav init

olav init 会自动创建 .olav/ 目录和配置骨架，包括 api.json（LLM 配置）、数据库和核心 Agent。

第三步：配置 API Key¶

编辑 olav init 生成的 .olav/config/api.json，填入你的 API Key。

api.json 使用 shared.api_key 统一管理密钥——LLM 和 Embedding 共用同一个 Key，无需分别配置：

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。

保护你的密钥

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 集成、远程执行和平台管理。安装领域技能包可扩展专业能力：

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

olav skill install /path/to/olav-netops/

一条命令完成所有操作：自动 pip install（检测 pyproject.toml）、workspace 部署、agent 注册。新增：SSH 采集（Nornir）、拓扑分析、漂移检测、ContainerLab 数字孪生、审计健康检查。安装 2 个 workspace：ops + audit。用 olav list 验证（3 个 agent：core、ops、audit）。

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
# core  — 平台 agent（始终存在）
# ops   — 网络运维（安装 olav-netops 后）
# audit — 健康检查与合规（安装 olav-netops 后）

第五步：设置 .gitignore¶

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

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

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

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