4.1 环境搭建：布置会场

4.1 环境搭建：布置会场

本节摘要：布置会场分三步：备好解释器与依赖、装浏览器驱动、配密钥。本节给出完整命令序列、三类常见安装故障的排查表，以及"最小可开会环境"的验收清单——按清单逐项打勾，再开首次会，能省掉大量无效折腾。

本节是动手章的第一节。环境问题的特点是报错离根因很远：一个缺密钥的配置错误，可能表现为三十轮之后模型忽然答非所问。所以本节的立场是先验收、后开会——五分钟的环境自检，换一个干净的首次会议。

一、三步走：从零到可开会

第一步：解释器与依赖

OWL 推荐 Python 3.10 或更高版本，依赖管理建议用现代工具（比如 uv 或标准虚拟环境）。完整序列如下（以通用环境为例）：

# 1. 获取框架源码
git clone https://github.com/camel-ai/owl.git
cd owl

# 2. 创建独立虚拟环境（版本务必 3.10+）
python -m venv .venv
# Windows 激活：
.venv\Scripts\activate
# macOS / Linux 激活：
source .venv/bin/activate

# 3. 安装框架本体与依赖
pip install -e .

# 4. 安装浏览器自动化驱动（外联部要用）
playwright install

# 5. 验证安装
python -c "import owl; print('owl ready')"
​

命令序列里第 4 步最容易被漏掉——漏装的典型症状是首次会跑到网页操作环节报"未找到浏览器可执行文件"，而前几轮一切正常。装完第 3 步顺手跑第 4 步，别等报错。

第二步：密钥配置

框架从环境变量读取模型服务与外部工具的凭据。做法是把模板文件复制为配置文件，填入自己的密钥：

# 从模板创建配置
cp .env_example .env

# 编辑 .env，至少配置一项模型服务凭据，例如：
# QWEN_API_KEY=你的密钥
# 如需搜索情报员，配置搜索服务凭据：
# GOOGLE_API_KEY=你的密钥
# SEARCH_ENGINE_ID=你的引擎标识
​

密钥管理的三条纪律：配置文件不进版本库（模板文件里通常已写好忽略规则）；密钥不写进代码正文；多项目共机时，确认激活的是正确目录下的配置——"密钥读到空值"的故障里，大半是开会时不在正确的工作目录。

第三步：最小验收清单

def env_check() -> list:
    """开会前环境自检：返回未通过项。空列表即可开会。"""
    checks = []
    import sys
    if sys.version_info < (3, 10):
        checks.append(f"解释器版本 {sys.version_info[:2]} 低于 3.10")
    try:
        import owl  # noqa: F401
    except ImportError:
        checks.append("owl 未安装或虚拟环境未激活")
    import shutil
    if not shutil.which("playwright"):
        checks.append("浏览器驱动未安装（playwright）")
    import os
    if not any(os.environ.get(k) for k in
               ("QWEN_API_KEY", "OPENAI_API_KEY")):
        checks.append("未配置任何模型服务密钥")
    return checks

# 输出：
# env_check()  （环境完好时）
#   -> []
# env_check()  （漏装驱动时）
#   -> ['浏览器驱动未安装（playwright）']
​

二、三类安装故障排查表

环境故障九成落进下面三类。对照症状找根因，比逐行读报错快：

三、配置进阶：换模型与换搜索源

默认配置跑通即可开首次会，但两处配置值得在首次会前想清楚。其一是模型选择：框架为多个模型服务提供了启动脚本（如通义千问、DeepSeek、任何兼容 OpenAI 接口的服务），选型逻辑看两件事——你的任务语言与模型的匹配度、以及单次调用成本；首次会建议用低成本模型跑通流程，正式任务再换强模型。其二是搜索源：情报员的表现高度依赖搜索服务，没有搜索服务凭据时，情报议题会在会中受阻，宁可先配好。

def pick_run_script(budget: str, lang: str) -> str:
    """按预算与语言选择启动脚本（示意决策）。"""
    if budget == "低成本试跑":
        return "默认脚本：先验证流程，不追质量"
    if lang == "中文任务":
        return "国内模型脚本：中文任务匹配度高，凭据用对应服务"
    return "通用接口脚本：任何兼容 OpenAI 接口的服务均可"

# 输出：
# pick_run_script("低成本试跑", "中文任务") -> '默认脚本：先验证流程，不追质量'
# pick_run_script("正式任务", "中文任务")   -> '国内模型脚本：中文任务匹配度高，凭据用对应服务'
​

⚠️ 配置文件里别堆满"以后可能用到"的密钥占位。空值密钥会让对应工具箱在会中静默失效（工具挂载了但调用全失败），排查时极难发现——需要哪个工具，配哪个的密钥。

案例展开：一次"装完即炸"的完整排查

背景：某团队在干净服务器上布置会场，安装顺利，首次会跑到第 9 轮报浏览器启动失败。操作：对照排查表先查驱动——命令行里确实有 playwright 命令；再查浏览器内核——发现系统缺浏览器内核库，驱动命令只装了绑定层没装内核。结果：补装内核后复跑，全程无阻。解读：这类故障的排查要点是区分"驱动命令存在"与"驱动可用"，安装脚本的退出码要看，装完的验收（env_check）更要看。

变式：团队多人共用一套环境时，把密钥配置与安装步骤写成组内交接文档（含 env_check 脚本），新人布置会场的失败率会从"每次都踩"降到"看文档就过"。

本节要点回顾

• 三步走：解释器与依赖、浏览器驱动、密钥配置，顺序不可倒；
• 最容易漏的一步：浏览器驱动，漏装的症状会迟到十几轮才出现；
• 密钥纪律：配置文件不进版本库、密钥不进代码、空值密钥必清理；
• 先验收后开会：五项自检清单跑过再开首次会；
• 下一节正式开第一次会，并教你把日志读出味道来。