梦行志Firecrawl MCP 接入 OpenClaw：从认证到排障的完整指南
Firecrawl API Key 配置、systemd 环境变量白名单、MCP 工具策略，一次搞懂
Firecrawl MCP 接入 OpenClaw：从认证到排障的完整指南
前言
Firecrawl 是专为 AI 代理设计的 Web 上下文 API，提供搜索、抓取、交互、文档解析和研究能力。当你把它接入 OpenClaw 作为 MCP 服务时，Agent 就拥有了直接访问互联网的能力。
但接入过程并不总是一帆风顺。本文记录了 2026 年 7 月 28 日将 Firecrawl MCP 接入 OpenClaw 的完整过程——从注册账号获取 API Key，到配置 systemd 环境变量文件，再到解决 OPENCLAW_SERVICE_MANAGED_ENV_KEYS 白名单导致的 Connection closed 错误。每一步都有详细的命令示例和根因分析。
一、Firecrawl 简介
核心功能
| 功能 | 说明 |
|---|---|
| 搜索 | 全网搜索，返回结构化结果 |
| 抓取 | 将网页转换为 Markdown 或结构化数据 |
| 交互 | 模拟点击、滚动、表单填写 |
| 文档解析 | PDF、Word、Excel 等格式提取 |
| 研究 | 深度调研，多源信息整合 |
| 监控 | 网页变更检测和通知 |
定价方案
| 方案 | 价格 | 额度 | 适用场景 |
|---|---|---|---|
| Free | $0 | 1,000 credits/月 | 个人试用、轻量使用 |
| Hobby | $16/月 | 5,000 credits | 个人开发者 |
| Standard | $83/月 | 100,000 credits | 团队/生产环境 |
注册网址：https://www.firecrawl.dev MCP 端点：
https://mcp.firecrawl.dev/v2/mcp
二、接入前的准备工作
1. 注册 Firecrawl 账号
- 访问 https://www.firecrawl.dev 注册账号
- 进入 Dashboard 获取 API Key（格式为
fc-开头的字符串） - 记录你的 API Key，后续配置需要用到
2. 确认 OpenClaw 环境
# 检查 OpenClaw 版本
openclaw --version
# 检查 Gateway 状态
systemctl --user status openclaw-gateway.service
# 预期输出：active (running)3. 安装 firecrawl-mcp
# 通过 npm 全局安装
npm install -g firecrawl-mcp
# 验证安装
which firecrawl-mcp
# 输出：/home/oklife/.local/bin/firecrawl-mcp三、配置 API Key：从 .env 到 systemd
第一步：添加环境变量到 ~/.openclaw/.env
最直觉的做法是把 API Key 写入 .env 文件：
echo 'FIRECRAWL_API_KEY=fc-your-api-key-here' >> ~/.openclaw/.env但这样不够。OpenClaw Gateway 作为 systemd 服务运行，它不会自动读取 .env 文件。
第二步：添加到 gateway.systemd.env
OpenClaw Gateway 的环境变量配置文件是 ~/.openclaw/gateway.systemd.env：
# 编辑环境变量文件
vim ~/.openclaw/gateway.systemd.env
# 添加以下内容
FIRECRAWL_API_KEY=fc-your-api-key-here第三步：热重载 vs 完整重启
修改环境变量后，需要让 Gateway 重新读取配置：
# 尝试热重载（SIGUSR1）
systemctl --user reload openclaw-gateway.service
# 如果热重载不生效，执行完整重启
systemctl --user restart openclaw-gateway.service⚠️ 注意：热重载（reload）不会重新读取
EnvironmentFile。修改环境变量后，必须使用restart。
四、排障：Connection closed 错误
问题现象
Gateway 日志反复出现：
failed to start server "firecrawl" (/home/oklife/.local/bin/firecrawl-mcp): McpError: MCP error -32000: Connection closedfirecrawl 搜索/爬取能力不可用，tavily 作为主搜索工具正常运行。
九步根因分析
| 步骤 | 检查项 | 结果 |
|---|---|---|
| 1 | firecrawl-mcp 是否安装 | ✅ 已安装，symlink 到 v24.15.0 的 node_modules |
| 2 | firecrawl-mcp 是否能运行 | ❌ 报错 “Either FIRECRAWL_API_KEY or FIRECRAWL_API_URL must be provided” |
| 3 | plugins.entries.firecrawl 配置 | enabled: true, config: {}（无 API key） |
| 4 | ~/.openclaw/.env 是否包含 API Key | ✅ 已添加 |
| 5 | systemd 环境是否包含 API Key | ❌ gateway 读取的是 gateway.systemd.env，不是 .env |
| 6 | gateway.systemd.env 是否包含 API Key | ✅ 已添加 |
| 7 | 热重载（SIGUSR1） | ❌ 失败，热重载不重新读取 EnvironmentFile |
| 8 | 完整重启 systemd service | ❌ 仍然失败 |
| 9 | 检查 OPENCLAW_SERVICE_MANAGED_ENV_KEYS | ❌ API Key 不在白名单中 |
根因
OpenClaw Gateway 有一个安全机制：环境变量白名单。只有列入 OPENCLAW_SERVICE_MANAGED_ENV_KEYS 的变量才会被传递给 MCP 子进程。
即使 FIRECRAWL_API_KEY 存在于 Gateway 进程的环境中，如果不在白名单里，MCP 子进程也无法获取该变量。
五、修复步骤
1. 编辑 systemd 服务文件
vim ~/.config/systemd/user/openclaw-gateway.service找到 OPENCLAW_SERVICE_MANAGED_ENV_KEYS 行，添加 FIRECRAWL_API_KEY：
# 修改前
OPENCLAW_SERVICE_MANAGED_ENV_KEYS=ANOTHER_KEY,OTHER_KEY
# 修改后
OPENCLAW_SERVICE_MANAGED_ENV_KEYS=ANOTHER_KEY,OTHER_KEY,FIRECRAWL_API_KEY2. 重载 systemd 配置
systemctl --user daemon-reload3. 重启 Gateway 服务
systemctl --user restart openclaw-gateway.service4. 验证修复结果
# 查看启动日志，确认无 firecrawl 相关错误
journalctl --user -u openclaw-gateway.service --since "19:48:54"
# 确认 Gateway 进程正常运行
systemctl --user status openclaw-gateway.service
# 输出：active (running), pid 180097修复后再无 Firecrawl MCP 失败记录。
六、MCP 工具策略
可用工具
Firecrawl MCP 提供以下工具：
| 工具名 | 功能 |
|---|---|
firecrawl_scrape | 抓取网页并转换为 Markdown |
firecrawl_search | 全网搜索 |
工具访问控制
这些工具受 OpenClaw 的 tool policy 限制，只有特定 agent 可使用。例如 oc-engineer 的 messaging profile 不包含这些工具，这是正常的安全策略。
# 查看当前 agent 可用工具
openclaw doctor --check tools七、关键配置速查
| 配置项 | 路径/说明 |
|---|---|
| 环境变量文件 | ~/.openclaw/gateway.systemd.env |
| 服务文件 | ~/.config/systemd/user/openclaw-gateway.service |
| 白名单变量 | OPENCLAW_SERVICE_MANAGED_ENV_KEYS |
| API Key 格式 | fc- 开头的字符串 |
| MCP 端点 | https://mcp.firecrawl.dev/v2/mcp |
| 日志查看 | journalctl --user -u openclaw-gateway.service |
总结
Firecrawl MCP 接入 OpenClaw 的核心要点：
- 环境变量要写在
gateway.systemd.env，不是.env - 修改环境变量后必须
restart，reload不重新读取 EnvironmentFile - API Key 必须加入
OPENCLAW_SERVICE_MANAGED_ENV_KEYS白名单，这是最容易踩的坑 - MCP 工具受 tool policy 限制，不是所有 agent 都能使用
按照本文的步骤操作，你的 Firecrawl MCP 应该能在 10 分钟内完成接入。
关联阅读
- [[OpenClaw 生产环境运维全景：从健康审查到 Firecrawl MCP 修复的完整实战]]
- [[2026-06-05-2330-MCP安装与调试报告]]
- [[2026-05-16-memory-search-qmd-fallback-故障排除详细记录]]
参考来源
–全文完–
“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”
转载请注明来自https://oklife.me。
