企业官网建设流程全解析

CAI 网络安全 AI 框架实用 FAQ 指南：从模型接入、REPL 交互到会话续跑与能力扩展

【免费下载链接】caiCybersecurity AI (CAI), the framework for AI Security项目地址: https://gitcode.com/GitHub_Trending/cai3/cai

CAI（Cybersecurity AI）是一套面向渗透测试、漏洞赏金与安全研究场景的 AI Agent 框架。本指南以官方 FAQ 为核心，系统讲解 CAI 使用中最常见的环境配置、REPL 交互、会话管理与能力扩展问题，涵盖 Ollama 接入、Docker 网络、HITL 人机协作、模型切换、日志回放等高频场景，并辅以仓库源码佐证，帮助读者快速排障并充分释放 CAI 的实战能力。

一、模型接入与本地推理环境

1.1 解决 Ollama 的 404 错误：OLLAMA_API_BASE的正确写法

使用 Ollama 作为本地模型后端时，最典型的报错是请求返回 404。原因在于两者的 API 路径约定不同：

• Ollama 的 OpenAI 兼容模式使用/v1/chat/completions作为完整路径；
• 而openai库在拼接请求时会自动在base_url后追加/chat/completions。

CAI 选择与生成式 AI 社区整体对齐，采用base_url + /chat/completions的拼接方式，因此只需在base_url中自行补上v1段即可，即设置：

export OLLAMA_API_BASE=http://IP:PORT/v1

例如本地默认端口可写为http://localhost:11434/v1。这是接入 Ollama 时最容易踩的坑，配置正确后CAI_MODEL即可使用ollama/qwen2.5:72b之类的本地模型标识（详见 docs/environment_variables.md 中的本地开发示例）。

1.2 Docker host 网络失效：登录与端口转发的排查

在 macOS（OS X）的 Docker Desktop 中，如果未登录 Docker 账号，会出现提示：Host networking has been disabled because you are not signed in. Please sign in to enable it.，从而导致 CAI 无法通过 host 网络访问容器服务。排查步骤如下：

1. 确认 Docker 已登录，恢复 host 网络能力；
2. 检查 Dev Container 是否占用了 8000 端口转发，若有则在 VSCode 的 Ports 面板中点击 x 关闭转发；
3. 在 VSCode devcontainer 内部验证连通性：

curl -v http://host.docker.internal:8000/api/version

该命令用于确认容器与宿主机的网络链路是否正常，是定位容器化部署网络问题的基础手段。

二、REPL 交互核心操作

2.1 对任意目标发起攻击：一句话启动 Agent

CAI 的启动提示词即为任务描述。例如输入：

Target IP: 192.168.3.10, perform a full network scan

Agent 会自动调用 nmap 等工具开始侦察。你可以随时追加指令引导它，也可以放手让它自主探索下一个攻击面。这一交互形态在 docs/media/cai-004-first-message.png 中有直观展示。

从源码看，用户提示词会进入 user_master_template.md 模板进行渲染：模板会注入Instructions、Challenge、Target IP等字段，并根据CTF_INSIDE环境变量决定提示词强调"在目标容器内部执行（少用网络命令）"还是"在目标容器外部执行（可先用 nmap 侦察）"。

2.2 HITL 人机协作模式：连续按两次Ctrl + C

在 Agent 自主执行过程中，如果想随时介入，可连续按两次Ctrl + C进入 HITL（Human-In-The-Loop）模式，此时可以像普通聊天一样向 Agent 下发新的提示词。

关键设计在于：Agent 不会丢失之前的上下文。对话历史保存在history变量中，并会传递给当前 Agent 以及之后被调用的任何 Agent，从而保证后续操作能够基于先前信息做出更准确、更高效的决策。运行效果见 docs/media/cai-005-ctrl-c.png。

2.3 运行中切换模型：/model

在会话进行中随时可以通过/model命令更换模型，无需重启。执行/model可查看当前模型及可用列表，/model <模型名>或/model <编号>均可完成切换。

从源码看（src/cai/repl/commands/help.py 的模型帮助面板），模型信息存储在CAI_MODEL环境变量中，切换会在下一次 Agent 交互时生效；各提供方 API Key 遵循PROVIDER_API_KEY的命名模式，例如OPENAI_API_KEY、ANTHROPIC_API_KEY。交互界面见 docs/media/cai-007-model-change.png。

2.4 查看可用 Agent：/agent

使用/agent可列出框架内置的全部 Agent，并通过编号快速选择。框架提供的 Agent 包括但不限于：

• one_tool_agent：基础 CTF 求解器；
• red_teamer：攻击性安全专家；
• blue_teamer：防御性安全专家；
• bug_bounter：漏洞赏金猎手；
• dfir：数字取证与应急响应；
• network_traffic_analyzer：网络流量分析；
• flag_discriminator：CTF Flag 提取与校验；
• codeagent：代码生成与分析；
• thought：战略规划。

列表见 docs/media/cai-010-agents-menu.png。对应实现位于 src/cai/agents 目录，例如 red_teamer.py、bug_bounter.py 等；默认 Agent 类型由CAI_AGENT_TYPE环境变量控制。

2.5 查看与修改环境变量：/config

执行/config（或/config list）会以表格形式列出所有环境变量的当前值及其编号（供/config set使用），每行还包含变量默认值与说明。查看单变量可用/config get <编号>，修改则用/config set <编号> <值>。

该命令的底层实现在 src/cai/repl/commands/config.py：内置变量以字典ENV_VARS维护，启动时会动态追加CAI_<AGENT>_MODEL等按 Agent 生成的模型覆盖变量，并通过get_env_var_value/set_env_var读写os.environ。

更完整的参考表（默认值、取值约束、生效时机）可通过以下方式获得：

• 运行/help并翻过快速指南部分；
• 运行/help topics并读至末尾；
• 查看单个变量的深度说明：/help var VARIABLE_NAME（例如/help var CAI_DEBUG）。

Web 端权威参考见 docs/environment_variables.md。常用变量速览：

2.6 了解全部命令：/help

/help输出完整的命令分类概览（Agent 管理、记忆与历史、环境与配置、工具与集成、实用工具等），并提供命令别名（如/h、/?）、Tab 补全、方向键历史等快捷键提示。/help <topic>可查看某一主题的详细帮助，/help commands列出全部命令，/help quick给出快速参考。帮助系统实现在 src/cai/repl/commands/help.py，效果见 docs/media/cai-006-help.png。

三、会话延续：利用历史日志扩展 CAI 能力

3.1 用/load回放历史运行

每次成功运行后，会话日志会以.jsonl文件的形式保存，默认位于logs/目录（文件名形如logs/cai_20250408_111856.jsonl）。利用/load命令即可在针对同一目标的新会话中回放之前的完整上下文：

1. 对目标运行一次 CAI（假设目标名为target001）；
2. 找到日志文件路径，如logs/cai_20250408_111856.jsonl；
3. 重新启动 CAI，执行/load并选择该 jsonl 文件（界面见 docs/media/cai-011-load-command.png）。

/load的实现位于 src/cai/repl/commands/load.py，它支持多种用法：

• /load <文件>：加载到当前活跃 Agent；
• /load agent <Agent名> [文件]：加载到指定 Agent（如/load agent red_teamer logs/last）；
• /load <ID> [文件]：按并行 Agent 编号加载（如/load P2 logs/last）；
• /load load-all [文件]：将同一批消息载入全部并行 Agent。

此外，框架每次运行后会在logs/下创建指向最新日志的符号链接logs/last（见 src/cai/cli.py 的create_last_log_symlink），因此不带参数执行/load即可默认回放最近一次运行。加载时内置去重控制，已存在的消息不会重复注入，避免上下文膨胀。

3.2 用脚本与附加信息扩展 Agent 能力

当前 CAI 支持基于文本的信息注入。你可以把关于目标的任何额外信息直接粘贴进系统提示词或用户提示词中，具体做法是编辑两个模板：

• 系统提示词模板：system_master_template.md；
• 用户提示词模板：user_master_template.md。

也可以直接在会话中把文件路径告诉模型，它会用cat读取内容。从 system_master_template.md 的源码可以看到系统提示词由五层结构组成：Instructions（角色指令）、Compacted Summary（压缩摘要）、Memory（向量库记忆召回）、Reasoning（推理增强）、Environment（执行环境信息）——其中环境信息包含操作系统、主机名、本机 IP、tun0 地址以及/usr/share/wordlists下可用的字典列表，这些都会自动注入供 Agent 侦察时使用。

3.3 记忆模式与状态跟踪的联动

若在回放历史时配合记忆能力效果更佳：

export CAI_MEMORY=all # episodic / semantic / all / false export CAI_MEMORY_ONLINE=true # 在线记忆（默认每 5 轮更新一次） export CAI_STATE=true # 状态 Agent 跟踪网络状态与已发现 Flag

记忆开关在模板中被读取（CAI_MEMORY取值episodic/semantic/all时启用 RAG 召回），并会把历史经验写入<memory>上下文块，指导 Agent 复用已验证的成功路径、避免重复侦察。

四、开发环境与本地文档

4.1 为 GitLab 配置 SSH 访问

# 1. 生成 ed25519 密钥 ssh-keygen -t ed25519 # 2. 将私钥加入 SSH agent ssh-add ~/.ssh/id_ed25519 # 3. 查看公钥内容 cat ~/.ssh/id_ed25519.pub

将公钥粘贴到 GitLab 的 SSH Keys 设置页，然后验证：

ssh -T git@gitlab.com # 预期输出: Welcome to GitLab, @vmayoral!

4.2 清理 Python 缓存

开发迭代频繁时，可一次性删除全部编译缓存：

find . -name "*.pyc" -delete && find . -name "__pycache__" -delete

4.3 在本地运行文档站点

CAI 文档基于 MkDocs 构建，本地预览与编辑步骤如下：

# 1. 安装 MkDocs 与 Material 主题 pip install mkdocs mkdocs-material # 2. 本地启动文档服务（默认 http://127.0.0.1:8000） python -m mkdocs serve # 3. （可选）构建静态站点，生成 site/ 目录 mkdocs build

站点配置见仓库根目录 mkdocs.yml，文档源文件位于 docs 目录。

五、CAI 的许可证与使用边界

CAI 的许可证不限制研究用途：你可以自由使用它进行安全评估（渗透测试）、开发新功能，并将其整合进研究活动，前提是遵守当地法律。

需要说明的是：如果你或你的组织开始从 CAI 中获得商业收益（例如提供由 CAI 驱动的渗透测试服务），则需要商业许可证，以支持项目的可持续发展。CAI 本身并非盈利项目，其目标是构建可持续的开源项目，官方仅要求从 CAI 获益者能够回馈并支持项目的持续开发。

六、排障速查

以上所有排障与操作均可在 docs/cai_faq.md 官方 FAQ 及对应源码中得到印证，适合作为 CAI 日常使用的手边速查手册。

【免费下载链接】caiCybersecurity AI (CAI), the framework for AI Security项目地址: https://gitcode.com/GitHub_Trending/cai3/cai