如何使用 Claude 的工具调用 API 在 Python 中构建自主的 OSINT 代理

标题：如何使用 Claude 的工具调用 API 在 Python 中构建自主 OSINT 智能体

文章来源：https://www.freecodecamp.org/news/build-autonomous-agent-in-python-using-claude/

发布时间：2026-05-15T00:19:42.195Z

当我开始学习 OSINT 时，总觉得自己只是在向软件中输入随机值，而没有真正理解自己在做什么。在这个领域摸爬滚打数月后，我意识到自己并非在进行真正的调查——只是在执行遵循可预测模式的步骤。而这正是 AI 智能体所擅长的。所以我决定自己构建一个。

在本教程中，你将学习如何搭建 OpenOSINT——一个以 AI 智能体为核心的开源 Python OSINT 框架。你将了解 Claude 原生工具调用 API 的工作原理，如何使用交互式 AI REPL 在终端运行自主调查，如何使用直接 CLI 进行脚本编写，以及如何通过 MCP 服务器将所有工具暴露给 Claude Code 或 Claude Desktop。

目录

什么是 OSINT 以及为何手动工作流程效率低下

开源情报（OSINT）是指从公开可用来源收集和分析信息的实践。安全研究人员在渗透测试中使用它，记者用它来验证身份和追踪关联，威胁分析师则用它来分析基础设施。

典型的 OSINT 工作流程如下：

1. 你获得一个目标邮箱地址
2. 运行 holehe 查找该邮箱在哪些平台注册过
3. 在输出中发现一个用户名
4. 手动复制该用户名并运行 sherlock 搜索 300+ 个平台
5. 切换到浏览器查看 HaveIBeenPwned
6. 打开另一个标签页进行 WHOIS 查询
7. 记录笔记并重复以上步骤

每个工具都是孤立的。每次转换都需要手动操作。调查逻辑——下一步该运行什么、如何串联工具、发现结果意味着什么——完全存在于你的脑海中。

当你关闭终端时，这些信息就消失了。

本教程将带你使用 OpenOSINT 来改变这种碎片化的工作流程。这个开源 Python 框架通过 AI 智能体自主串联工具、对真实二进制文件执行操作，并保存结构化的 Markdown 报告。

更重要的是，你将学习到使其在安全研究中值得信赖的核心设计原则：在工具结果中出现幻觉在结构上是不可能的。

你将构建什么

完成本教程后，你将拥有一个可用的 OSINT 智能体，可以通过三种方式使用：

• 交互式 AI REPL — 用自然语言输入目标，智能体决定运行什么
• 直接 CLI — 无需 AI 单独运行各个工具，适用于脚本编写
• MCP 服务器 — 将所有工具暴露给 Claude Code 或 Claude Desktop

以下是实际会话示例：

$ openosint
openosint ❯ investigate target@example.com

  → generate_dorks('target@example.com')
  → search_email('target@example.com')
  ✓ Found: Spotify, WordPress, Gravatar, Office365

  → search_breach('target@example.com')
  ✓ Found in 2 breaches: LinkedIn (2016), Adobe (2013)

  → search_username('target_handle')
  ✓ Found on: GitHub, Reddit, HackerNews, Twitter

  ╭──────────────── Report ────────────────╮
  │ ## Online Presence                     │
  │ Spotify · WordPress · Gravatar         │
  │                                        │
  │ ## Data Breaches                       │
  │ LinkedIn (2016) · Adobe (2013)         │
  ╰────────────────────────────────────────╯

  ✓ Report saved → reports/2026-05-11_report.md

该智能体从邮箱→关联账户→用户名转换→跨平台搜索，全程无需人工干预。

前置要求

要完成本教程，你需要：

• 在机器上安装 Python 3.10 或更高版本
• 对命令行有基本了解
• 一个 Anthropic API 密钥 — 仅 AI REPL 需要，CLI 或 MCP 服务器不需要
• 已安装 Git

你不需要有 OSINT 工具或 Anthropic SDK 的使用经验。

在开始安装之前，有必要了解让这个框架在安全研究中值得信赖的机制。

大多数封装外部工具的 AI 应用通过生成描述工具_可能_返回结果的文本来工作。这在需要准确性时会产生问题——模型可能会幻觉出看似合理的用户名、虚假子域名或从未发生过的数据泄露。

Claude 的工具调用 API 工作方式不同。当模型决定需要调用工具时，它不会生成输出。它会停止并发出结构化的 tool_use 块，其中包含工具名称和要传递的参数。

然后你的代码运行实际的二进制文件——holehe、sherlock 或其他任何工具——并将真实输出作为 tool_result 发送回去。模型读取这些真实输出并决定下一步行动。

流程如下：

用户提示
    ↓
模型决定调用 search_email()
    ↓
硬停止 — 模型发出 tool_use 块
    ↓
你的代码对真实目标运行 holehe
    ↓
真实输出作为 tool_result 发送回去
    ↓
模型读取实际结果，决定下一步
    ↓
重复直到调查完成

模型从不生成工具输出。它只读取输出。如果 sherlock 找到 12 个个人资料，这 12 个 URL 会原样返回给上下文。模型无法添加第 13 个不存在的资料。

这不是提示技巧或系统提示指令。这是 API 的架构设计方式。在阅读本教程后面的智能体循环代码时，请记住这一点。

如何安装 OpenOSINT

首先克隆仓库并安装包：

git clone https://github.com/OpenOSINT/OpenOSINT.git
cd OpenOSINT
pip install -e .

或者，如果你只想使用工具而不修改源码，可以直接从 PyPI 安装：

pip install openosint

接下来设置你的 Anthropic API 密钥。这仅适用于交互式 AI REPL——直接 CLI 和 MCP 服务器无需此密钥即可工作：

export ANTHROPIC_API_KEY=sk-ant-...

如何安装外部工具依赖

OpenOSINT 封装了多个独立的 OSINT 工具。请安装你计划使用的工具：

pip install holehe            # 邮箱账户枚举
pip install sherlock-project  # 在 300+ 平台上搜索用户名
pip install sublist3r         # 子域名枚举

对于手机情报，phoneinfoga 是一个独立的二进制文件。请从其 GitHub 发布页面下载适用于你平台的版本，并将其放在你的 PATH 中的某个位置。

如何配置可选 API 密钥

两个工具在使用可选 API 密钥时具有更高的速率限制：

export HIBP_API_KEY=your_key    # 通过 HaveIBeenPwned v3 进行泄露检查所需
export IPINFO_TOKEN=your_token  # 可选——提高 ipinfo.io 的速率限制

如果缺少二进制文件或未配置 API 密钥，该特定工具将返回描述性错误字符串。所有其他工具继续正常工作。

如何使用交互式 AI REPL

不带参数运行 openosint 即可启动 AI 驱动的 REPL。你也可以使用 openosint shell——两者等效：

$ openosint
# 或
$ openosint shell

如果你倾向于内联传递 API 密钥而不是通过环境变量，请使用 --api-key 标志：

$ openosint --api-key sk-ant-...

你将得到一个提示符，可以在其中用自然语言输入目标或问题：

openosint ❯ investigate target@example.com
openosint ❯ 查找 johndoe99 的所有账户
openosint ❯ example.com 有哪些子域名？
openosint ❯ 检查 +14155552671 是否为手机号码

代理会根据你的输入决定运行哪些工具。你无需指定使用哪些工具或使用顺序。如果你输入电子邮件地址，代理将运行电子邮件枚举。如果找到关联的用户名，它可能会转向并在其他平台上搜索该用户名。

每次产生结构化结果的调查后，报告会自动保存到 reports/ 目录。

以下是 REPL 内部可用的命令：

| 命令 | 描述 | | --- | --- | | clear | 重置对话记忆 | | save | 手动保存上次报告 | | tools | 显示可用工具及其状态 | | config | 显示当前配置 | | help | 列出所有命令 | | exit 或 Ctrl-D | 退出 |

如何从 CLI 运行单个工具

如果你想在没有 AI 层的情况下运行单个工具——用于脚本编写、自动化或快速查询——请使用直接 CLI：

# 邮箱账户枚举（默认超时：120 秒）
openosint email target@example.com

# 使用自定义超时（秒）
openosint email target@example.com -t 60

# 在 300+ 平台上搜索用户名（默认超时：180 秒）
openosint username johndoe99

# 启用详细输出以进行调试
openosint -v email target@example.com

直接 CLI 不需要 Anthropic API 密钥。它运行底层二进制文件并将输出打印到终端。

当你需要可预测、可编写脚本的行为时，此模式非常有用——例如，将输出传输到另一个工具或运行自动化检查。

如何设置 MCP 服务器

OpenOSINT 还作为模型上下文协议（MCP）服务器提供。这将所有 9 个工具暴露给任何 MCP 兼容的 AI 客户端。

如何注册到 Claude Code

claude mcp add openosint python /absolute/path/to/OpenOSINT/openosint/mcp_server.py

验证注册是否成功：

claude mcp list

注册后，你可以从 Claude Code 提示符驱动调查：

> 调查 target@example.com。如果找到关联的用户名，
  请在其他平台上追踪它并编制完整报告。

如何配置 Claude Desktop

将以下内容添加到你的 Claude Desktop 配置中，位置为 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "openosint": {
      "command": "python",
      "args": ["/absolute/path/to/OpenOSINT/openosint/mcp_server.py"]
    }
  }
}

保存文件后重启 Claude Desktop。这些工具将出现在 Claude 的工具列表中。

MCP 服务器使用 stdio 传输，不需要持久的后台进程。Claude Code 或 Claude Desktop 会根据需要启动它。

代理循环的工作原理

以下是 openosint/agent.py 中代理循环的简化版本：

import anthropic
import asyncio

client = anthropic.Anthropic()

async def run_investigation(user_prompt: str) -> str:
    messages = [{"role": "user", "content": user_prompt}]

    while True:
        response = client.messages.create(
            model="claude-...",   # 通过 --api-key / 环境变量配置的模型
            max_tokens=4096,
            tools=TOOL_SCHEMAS,   # 所有 9 个工具的 JSON 模式
            messages=messages
        )

        # 代理完成——提取并返回最终报告
        if response.stop_reason == "end_turn":
            return extract_text(response)

        # 代理需要使用工具——运行真实的二进制文件
        if response.stop_reason == "tool_use":
            tool_results = []

            for block in response.content:
                if block.type == "tool_use":
                    # 将 holehe、sherlock 等作为真实子进程运行
                    real_output = await execute_tool(block.name, block.input)

                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": real_output  # 真实输出，从不生成
                    })

# 将助手回复和实际工具结果添加到对话中
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})

这段代码中有几个重要要点需要理解：

1. 循环运行直到stop_reason == "end_turn"：智能体会自行判断何时收集到足够信息来撰写最终报告。根据发现的内容，它可能调用一个工具，也可能调用十个工具。

1. execute_tool()运行真实的子进程：这是对Python asyncio.create_subprocess_exec()的轻量异步封装，具有可配置的超时时间。整个过程没有任何模拟或伪造数据。

1. 在整个循环过程中维护对话历史：每个工具结果都会返回到messages中，因此模型在决定下一步运行时始终拥有完整的上下文信息。

1. 工具模式定义为JSON：每个工具都有名称、描述和参数模式。模型使用这些信息来了解可用工具及其接受的参数。以下是search_email的简化示例：

{
    "name": "search_email",
    "description": (
        "使用holehe枚举与电子邮件地址关联的在线服务和社交账户"
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "email": {
                "type": "string",
                "description": "目标电子邮件地址"
            }
        },
        "required": ["email"]
    }
}

所有9个工具都采用相同的模式。模型在每次请求开始时读取这些模式，并利用它们来决定可用工具及其调用方式。

项目架构

代码库分为五个层级。整个代码库的硬性规则是：任何层级都不能从上层导入：

openosint/tools/        核心工具
                        外部二进制文件和API的异步封装
                        无状态。无AI。无CLI。纯函数。

openosint/agent.py      AI智能体
                        Anthropic工具使用循环
                        每个会话的对话历史
                        从tools/导入。没有文件从agent.py导入

openosint/repl.py       交互式REPL (prompt_toolkit + Rich)
openosint/mcp_server.py MCP服务器 (stdio传输)
openosint/cli.py        CLI入口点

这种分离使每个层级都可以独立测试。核心工具是纯异步函数，接收字符串并返回字符串——你可以在不接触智能体或CLI的情况下对它们进行单元测试。

这也意味着AI层完全是可选的。如果你没有Anthropic API密钥，可以使用CLI并绕过智能体。MCP服务器也独立于智能体运行。

9个可用工具

| 工具 | 后端 | 返回内容 | | --- | --- | --- | | search_email | holehe | 与电子邮件关联的社交账户 | | search_username | sherlock | 300多个平台的账户信息 | | search_breach | HaveIBeenPwned v3 | 漏洞名称、日期、泄露数据类型 | | search_whois | python-whois | 注册人、注册商、创建/到期时间 | | search_ip | ipinfo.io | 地理位置、ASN、主机名、组织 | | search_domain | sublist3r | 子域名枚举 | | generate_dorks | 内置 | 12个定向Google搜索URL，无网络调用 | | search_paste | psbdmp.ws | Pastebin转储提及 | | search_phone | phoneinfoga | 运营商、国家、线路类型 |

结论

在本教程中，你学习了如何设置和使用OpenOSINT——一个基于Claude工具使用API构建的Python OSINT框架。

关键的设计原则是：通过使用原生工具调用，智能体从不生成工具输出。它只读取真实二进制文件的实际输出。这使得它适用于准确性至关重要、幻觉不可接受的安全研究场景。

回顾三种接口：

• 运行openosint进入交互式AI REPL——最适合自动链式调用的完整调查

• 运行openosint email或openosint username直接访问CLI——最适合脚本编写和自动化

• 在Claude Code或Claude Desktop中注册MCP服务器，在现有AI环境中运行调查

完整源代码可在GitHub上获取，采用MIT许可证。欢迎提交贡献和问题。

法律声明：OpenOSINT仅用于授权的安全研究、渗透测试和调查性新闻报道。用户需自行负责遵守适用法律，包括GDPR、CCPA和CFAA。完整声明请参阅DISCLAIMER.md。

• * *

• * *

免费学习编程。freeCodeCamp的开源课程已帮助超过40,000人获得开发人员工作。立即开始