Appearance
工具类问题
本页收录 GitHub Issues 中 edit、memory、web_fetch 等工具相关高频问题，精选有明确解决方案的案例。 编号格式
#NNNNN对应 GitHub issue，可直接在 issues 列表搜索去重。
问题 1：edit 工具报 "failed" 但文件已被修改
来源：GitHub #45770（2026-03）
现象：使用 edit 工具修改文件后，工具返回 ⚠️ Edit: in <file> failed，但用 grep 验证文件确实已成功修改。频繁出现误报失败提示，导致 Agent 重复尝试。
原因：沙箱（sandbox）模式下的 edit 工具缺少宿主（host）模式已有的写后恢复逻辑。当写操作成功但写后验证抛错时，沙箱路径没有走 recoverable-success 分支，而是直接返回失败——实际文件已改，反馈却说失败。
解决方法：
- 此为官方 Bug（#45964 PR 已提交修复），升级到最新版本通常可解决
- 短期规避：遇到 "failed" 后，手动用
grep或cat验证文件内容是否已更改，避免重复操作
bash
# 验证 edit 是否实际生效
grep "your_expected_text" /path/to/file提示：如果 grep 确认内容已更新，可以忽略工具的失败提示，继续下一步。
问题 2：edit 工具频繁报 "Missing required parameters"
来源：GitHub #52164（2026-03）
现象：让 AI 调用 edit 工具修改文件，Agent 频繁收到 Missing required parameters 错误，即使参数内容都提供了。常见于 Claude Sonnet / Opus 等模型。
原因：AI 模型生成的参数名（如 file、old_text、new_text）不在 edit 工具当前支持的别名列表中：
| AI 实际输出 | 工具期望 | 是否支持 |
|---|---|---|
file | path / file_path | ❌ 未收录 |
old_text | oldText / old_string | ❌ 未收录 |
new_text | newText / new_string | ❌ 未收录 |
解决方法：
此问题已在官方追踪，修复方案是在参数别名表中补充这三个变体。升级到最新版本后即可解决。
等待升级前，可在 Prompt 中明确告知模型使用规范参数名：
When using the edit tool, always use these exact parameter names:
- file_path (not "file")
- old_string (not "old_text")
- new_string (not "new_text")问题 3：memory status 始终显示 0 files / 0 chunks
来源：GitHub #53558 / #53666（2026-03）
现象：openclaw memory status 报告 Indexed: 0/N files · 0 chunks，但搜索功能正常、QMD 实际有数据。升级到 2026.3.23-2 后回退到 2026.3.12 则恢复正常。
原因：QmdStatusOnlyManager.status() 方法中 files 和 chunks 字段被硬编码为 0，从未实际查询 SQLite 索引。这是实现层面的 hardcoded 缺陷，不影响实际索引和搜索功能，只是状态显示错误。
解决方法：
验证数据是否实际存在（搜索是否正常）：
bash# 直接查询 QMD 状态 XDG_CACHE_HOME=~/.openclaw/agents/main/qmd/xdg-cache qmd status # 或测试搜索是否有效 openclaw memory search "test keyword"如果搜索正常，
status的 0 只是显示 Bug，不影响实际功能，等待官方修复即可如果搜索也无结果，手动重建索引：
bashopenclaw memory index --force
背景：此 Bug 在 2026.3.23-2 中被触发，2026.3.12 版本不受影响。
问题 4：web_fetch 在 TUN 模式代理下被 SSRF 检查拦截
来源：GitHub #44527 / #25215（2026-02）
现象：使用 Clash Verge、Mihomo、Surge 等 TUN 模式代理时，web_fetch 工具无法访问任何 URL，报错：
web_fetch failed: Blocked: resolves to private/internal/special-use IP address原因：TUN 模式劫持 DNS 解析，返回 fake-IP（通常是 198.18.x.x 或 198.19.x.x 段），这些地址属于 RFC 2544 测试地址段，被 OpenClaw 的 SSRF 安全检查识别为"私有/内部 IP"并拦截。
解决方法：
在 openclaw.json 中为 web_fetch 开启 RFC 2544 地址段放行：
json5
{
tools: {
web: {
fetch: {
ssrfPolicy: {
allowRfc2544BenchmarkRange: true
}
}
}
}
}安全说明：
allowRfc2544BenchmarkRange: true只放行198.18.0.0/15段（RFC 2544 benchmark range），不影响其他私有地址（10.x、172.16.x、192.168.x）的 SSRF 保护。
注意：
browser工具有类似问题，对应配置是browser.ssrfPolicy.dangerouslyAllowPrivateNetwork（放行范围更广，谨慎使用）。