第 1 章 安装与环境配置

学完本章，你将拥有一个可以正常对话的 GenericAgent（GA）运行环境。

学习目标

1. 在本地安装好 Python 并下载 GenericAgent 项目代码
2. 完成 mykey.py API 密钥配置，让 GA 能连接大模型
3. 成功启动 GA 并完成第一次对话

1.1 安装 Python

GA 依赖 Python 运行，我们先把它装好。

⚠️ 推荐 Python 3.11 或 3.12。不要使用 3.14（与 pywebview 等依赖不兼容）。

Windows

1. 打开下载链接：https://www.python.org/ftp/python/3.12.10/python-3.12.10-amd64.exe
2. 运行安装包，底部的 "Add python.exe to PATH" 一定要勾上，然后点击安装
3. 验证安装：按 Win + R 输入 cmd 打开终端，输入：

   python --version
​

看到 Python 3.x.x 就说明安装成功了。

macOS

macOS 和大多数 Linux 发行版自带 Python 3，打开终端（Terminal）验证：

python3 --version
​

看到 Python 3.x.x（3.11 或 3.12）即可。如果版本低于 3.10，前往 Python 官网 下载安装。

1. 打开下载链接：https://www.python.org/ftp/python/3.12.10/python-3.12.10-macos11.pkg
2. 运行安装包，一步一步跟着流程安装即可
3. 验证安装：打开系统自带终端，输入：

python3 --version
​

看到 Python 3.x.x 就说明安装成功了。

1.2 下载项目

我们需要把 GenericAgent 的代码下载到本地。两种方式任选其一：

方式一：下载 ZIP（推荐新手）

1. 打开 GitHub 仓库页面
2. 点绿色 Code 按钮 → Download ZIP
3. 解压到你喜欢的位置（例如 D:\GenericAgent）

方式二：Git Clone

如果已经安装了 Git，在终端执行：

git clone https://github.com/lsdefine/GenericAgent.git
​

1.3 安装最小依赖

打开终端，进入项目目录(运行以下命令)，安装两个核心依赖：

# 1. cd 到下载的 GA 文件目录
cd d:     (如果你的安装地址在D盘，终端打开后默认在c盘,安装在c盘跳过此步骤，仅限windows用户)
cd "你的GenericAgent路径"               （示例： cd D:/Document/GenericAgent-main） 

# 2. 安装最小环境依赖
pip install streamlit pywebview
# 如果你的 Python 3 对应 pip3，则用：pip3 install streamlit pywebview
​

其余依赖不用手动装——1.5 节会教你让 GA 自己把剩余的包全装好。

1.4 配置 API 密钥（mykey.py）

GA 需要连接大模型才能工作。我们通过 mykey.py 告诉它用哪个模型、怎么连。

mykey 配置最简流程（5 步搞定）

如果你是第一次接触，只需要跟着下面 5 步做：

第 1 步：复制模板文件
进入你下载的 GenericAgent 项目文件夹，找到 mykey_template.py 这个文件，复制一份，然后把副本重命名为 mykey.py。

第 2 步：编辑 mykey.py，填入你的 API 信息
用任意文本编辑器（记事本、VS Code 都行）打开 mykey.py。先找到 mykey 里你要用的模型 API 对应的格式模板，然后照着填。你会看到里面有很多 # 开头的行——这些是注释，程序运行时会自动忽略它们，相当于"说明书"。

填写 API 信息有两种方式，任选其一：

• 方式 A：找到对应的配置区域，把你的 API Key、地址等信息填好后，删掉该行最前面的所有 # 号，让这一行变成"真正的代码"。
• 方式 B：不动原来的注释，直接在文件里另起一行，把你的配置写上去（不加 #）。

简单来说：有 # 的行 = 不生效，没有 # 的行 = 会生效。

第 3 步：多个 API 怎么切换？
如果你填了不止一个 API 配置，GA 默认使用文件里第一个生效的配置（即第一个没被 # 注释掉的配置）。想切换模型有两种办法：

• 办法 A：启动 GA 后，点击界面侧边栏的切换模型按钮，直接切。
• 办法 B：回到 mykey.py，把你想用的那组配置挪到所有生效配置的最前面，保存后重启 GA。

第 4 步：保存文件
改完以后一定要保存！快捷键：Windows 按 Ctrl + S，Mac 按 Cmd + S。

第 5 步：重启 GA
每次修改 mykey.py 后，都需要关掉 GA 再重新启动，新的配置才会生效。

下面是更详细的配置说明和各渠道的具体写法：

1. 进入项目文件夹，把 mykey_template.py 复制一份，重命名为 mykey.py
2. 用任意文本编辑器打开 mykey.py，填入你的 API 信息。选一种填就行，不用的配置可以删掉或留着不管

新手推荐配置：Claude 主力 + GPT 兜底

直接复制到 mykey.py，替换两个 apikey / apibase：

# ── 主力：Claude Opus 4.6（CC switch 反代（Reverse Proxy），最常见）──
native_claude_config0 = {
    'name': 'claude-main',                        # /llms 显示名 & mixin 引用名
    'apikey': 'sk-user-<你的relay-key>',          # 非 sk-ant- 前缀 → Bearer 鉴权
    'apibase': 'https://<your-cc-switch-host>/claude/office',  # CC switch 端点
    'model': 'claude-opus-4-6',                
    'fake_cc_system_prompt': True,                # CC 透传渠道必须置 True
    'thinking_type': 'adaptive',               # 某些渠道必须要求填thinking_type字段
    'max_retries': 3,
    'read_timeout': 180,
}

# ── 备选：GPT-5.4 做兜底 ──
native_oai_config = {
    'name': 'gpt-backup',
    'apikey': 'sk-<你的 OpenAI key>',
    'apibase': 'https://api.openai.com/v1',
    'model': 'gpt-5.4',
    'reasoning_effort': 'high',
    'max_retries': 3,
    'read_timeout': 120,
}

# ── Mixin 自动切换（Failover）──
mixin_config = {
    'llm_nos': ['claude-main', 'gpt-backup'],
    'max_retries': 10,
    'base_delay': 0.5,
    'spring_back': 300,
}
​

每次启动GA默认读的是第一个api信息。可以点击设置切换。

所有内置渠道一览（点击展开）

一线直连渠道（填 apikey / apibase 即用）

反代 / 透传类渠道（需要 fake_cc_system_prompt = True）

本地模型

⚙️ 关键可调字段速查（点击展开）

DeepSeek V4 接入配置

DeepSeek 于 2026 年4月24日发布了 V4 系列模型，相比之前的 V3 / R1 有重大升级：

⚠️ 旧配置迁移提醒：如果你之前用的是 deepseek-chat / deepseek-reasoner，官方已宣布这两个模型名将逐步弃用。它们目前等价于 deepseek-v4-flash 的非思考 / 思考模式。建议尽早迁移到新模型名。

最简配置（推荐 V4-Pro）

native_oai_config_deepseek = {
    'name': 'deepseek-v4',
    'apikey': 'sk-<你的 DeepSeek API Key>',
    'apibase': 'https://api.deepseek.com',           # ⚠️ 不带 /v1
    'model': 'deepseek-v4-pro',
    'thinking_type': 'enabled',                      # 开启思考链（默认就是开）
    'reasoning_effort': 'high',                      # high 或 max
    'read_timeout': 180,                             # 思考模式耗时长，务必调大
    'stream': True,                                  # 推荐开启，实时显示回复
}
​

如何获取 API Key：前往 DeepSeek 开放平台 注册账号，在「API Keys」页面创建密钥即可。新用户通常有免费额度。

Native Claude 接口配置（推荐）

DeepSeek V4 支持 Anthropic 协议端点，GA 的 native_claude 接口对思考链和 Tool Calling 的处理更成熟，推荐优先使用此方式：

native_claude_config_deepseek = {
    'name': 'deepseek-v4-native',
    'apikey': 'sk-<你的 DeepSeek API Key>',
    'apibase': 'https://api.deepseek.com/anthropic',  # Anthropic 兼容端点
    'model': 'deepseek-v4-pro',
    'thinking_type': 'enabled',
    'reasoning_effort': 'high',
    'read_timeout': 180,
    'stream': True,
}
​

两种接口（OpenAI 格式 / Anthropic 格式）用同一个 sk- 开头的 API Key，不需要另外申请。

Mixin配置模式：允许GA在模型断开后自动切换模型

一次配好主 + 备 + 兜底，任何一个 429/5xx/超时都自动切下一个：

mixin_config = {
    'llm_nos': ['claude-main', 'claude-backup', 'gpt-backup'],  # 按优先级
    'max_retries': 10,      # 整个 rotation 总重试上限
    'base_delay': 0.5,      # 秒，指数退避起始
    'spring_back': 300,     # 秒，切到备用后多久尝试回到主
}
​

约束：llm_nos 中的名字必须精确匹配到其他 config 的 name 字段；所有被引用的 session 必须同属 Native 系列（NativeClaude + NativeOAI 可混）或全不属 Native 系列。

1.5 启动 GenericAgent

首次启动

在终端中执行：

# 1. cd 到项目目录
cd "你的GenericAgent路径"

# 2. 启动
python launch.pyw
​

如果是windows系统，可以双击launch.pyw启动。

看到浏览器弹出 Streamlit 聊天界面（或 pywebview 窗口），就说明启动成功了。如果用命令行模式 python agentmain.py，终端出现 >>> 提示符即为正常。

让 GA 自动安装剩余依赖

启动后，在对话框输入一句话，GA 会自己读代码、找出需要的包、全部装好：

请查看你的代码，安装所有用得上的 python 依赖
​

️ 推荐：提升使用体验的两个任务

建立 Git 连接（方便以后更新代码）：

请帮我建立 git 连接，方便以后更新代码
​

GA 会自动配好。如果你电脑上没有 Git，它也会帮你下载 portable 版。

创建桌面快捷方式（以后双击图标就能启动）：

请帮我在桌面创建一个 launch.pyw 的快捷方式
​

使用 Hub 总控台（可选）

hub.pyw 是 GA 的总控台——一键启动/停止所有后台服务，并实时查看日志。

启动方式：在终端执行 python3 hub.pyw，或直接双击 hub.pyw 文件。勾选想启动的服务即可，不用记命令行参数。

Hub 可管理的服务列表（点击展开）

1.6 常见问题排查

# 1. 看 Python 版本（建议 3.11 或 3.12）
python --version

# 2. 手动起 agentmain 看报错
cd <你的 GenericAgent 目录>
python agentmain.py

# 3. 看 launch.pyw 报什么（改后缀为 .py 才能看 stderr）
python launch.py
​

cd <GenericAgent 目录>
git pull
​

请帮我建立 git 连接，方便以后更新代码
​

请 git 更新你的代码，然后看看 commit 有什么新功能
​

native_oai_config_responses = {
    ...
    'api_mode': 'responses',
    'reasoning_effort': 'high',
}
​

native_claude_config = {
    ...
    'max_retries': 5,       # 429/5xx/超时自动退避重试
    'connect_timeout': 10,  # 连接超时 5 → 10 秒
    'read_timeout': 180,    # 流式读取 30 → 180 秒（思考模式必须加大）
}
​

小结

• 环境三步走：装 Python 3.11/3.12 → 下载项目 → pip install streamlit pywebview
• 配置只需一个文件：复制 mykey_template.py 为 mykey.py，填好 apikey 和 apibase 即可
• 启动后让 GA 自己装剩余依赖，不用手动折腾

下一章：第 2 章 浏览器能力解锁