Zhipu Tools Coding Plan

核心用法

智谱 Coding Plan 工具集是一组基于 MCP 协议的免费 API 工具，通过 Python 脚本和 Shell 快捷入口提供以下能力：

1. 网络搜索 (web_search_prime): 实时互联网搜索，支持关键词过滤，默认 MCP 模式免费调用
2. 网页读取 (webReader): 抓取网页标题、正文、元数据及链接列表
3. GitHub 仓库搜索 (zread): 包含文档搜索、目录结构查看、指定文件读取三项功能
4. 视觉理解 (vision): 基于 GLM-4.6V 的图像分析，支持本地图片和远程 URL
5. 文件解析: 支持 PDF/Word/Excel/PPT 等格式（Legacy 模式）

使用方式灵活，支持直接 Python 脚本调用 (python3 scripts/zhipu_tool.py <command>) 或 Shell 快捷入口 (./scripts/zhipu.sh)。配置简单，仅需在 openclaw.json 中设置 apiKey 或环境变量 ZHIPU_API_KEY。

显著优点

• 完全免费: Pro 套餐提供 1000 次/月额度，Max 套餐达 4000 次/月，远超常规需求
• 优先替代内置工具: 明确设计为优先于内置 web_search/web_fetch 使用，有效节省其他 API 配额
• MCP 协议原生支持: 采用 streamableHttp 标准协议，具备 session 管理和自动 fallback 机制
• 智能容错: MCP 连接失败时自动降级到 Legacy API；内容安全拦截时提示修改搜索词重试
• GitHub 深度集成: zread 功能支持仓库文档语义搜索、目录树浏览、文件内容读取，适合代码研究
• 视觉理解实用: GLM-4.6V 模型支持 UI 截图分析、错误识别、图片描述等场景

潜在缺点与局限性

• 视觉理解非官方实现: 通过逆向 npm 包提取 API 调用，官方未提供 MCP 端点，未来可能收费或受限
• 部分参数模拟实现: --recency 和 --domain 在 MCP 模式下通过注入 query 模拟（如 site:example.com），过滤效果依赖搜索引擎理解，不保证精确
• Legacy 模式余额风险: 降级到 Legacy API 时走账户余额，Coding Plan 用户通常余额为零，fallback 可能仍失败
• 内容安全策略限制: MCP 端点存在内容过滤，敏感词搜索会被拦截且不自动重试
• 文件解析仅限 Legacy: PDF/Word 等解析未接入 MCP，必须使用旧版 API
• 网络依赖性强: MCP 端点需稳定连接 api.z.ai，网络/SSL 问题会触发 fallback

适合人群

• AI 辅助开发用户: 需要频繁搜索技术文档、GitHub 仓库的开发者
• 配额敏感型用户: 希望减少内置搜索 API 调用，优化成本结构
• 中文开发者: 智谱模型对中文内容理解较好，国内访问稳定
• Coding Plan 订阅者: 已使用 Z.AI 服务的用户可无缝集成
• MCP 生态探索者: 希望实践 Model Context Protocol 协议的早期采用者

常规风险

• API Key 泄露: 需妥善保管 ZHIPU_API_KEY，避免提交到 Git 仓库
• 计费模式变更: 视觉理解当前可能免费，但逆向实现存在未来收费风险，需监控账户用量
• 服务稳定性: MCP 端点为较新服务，可能存在协议变更或 endpoint 调整
• 内容合规风险: 搜索内容受智谱内容安全策略约束，敏感领域查询可能被拦截
• 降级失效: 网络问题触发 Legacy fallback 时，若账户无余额则调用完全失败

安全评估

• 代码透明度: MIT 许可，源码可审计
• 密钥管理: 支持环境变量和配置文件两种方式，需用户自行保障安全
• 网络传输: 使用 HTTPS，但逆向实现的视觉理解端点未经官方认证
• 数据隐私: 搜索查询和图片上传发送至智谱服务器，需信任第三方数据处理

核心用法

智谱 Coding Plan 工具集是一套基于智谱 AI 官方 MCP 端点的多功能 Agent Skill，主要提供六大核心能力：网络搜索（web_search_prime）、网页读取（webReader）、GitHub 仓库文档搜索（search_doc）、仓库目录结构查看（get_repo_structure）、仓库文件读取（read_file）、视觉理解（GLM-4.6V）以及文件解析（PDF/Word/Excel/PPT）。

使用方法分为 Shell 快捷入口和 Python 脚本两种模式。Shell 脚本位于 scripts/ 目录下，包括 web_search.sh、web_reader.sh、zread.sh、vision.sh 等，适合快速命令行调用。Python 脚本 zhipu_tool.py 提供更丰富的参数控制，支持如 --recency、--domain、--prompt 等高级选项。所有工具均优先通过 Coding Plan MCP 端点调用，享受每月 100-4000 次的免费额度。

配置方式灵活，支持 openclaw.json 配置文件或 ZHIPU_API_KEY 环境变量。视觉理解功能支持本地图片路径和远程 URL，自动进行 base64 编码上传；仓库搜索支持 openai/openai 格式的仓库名，可进行全文检索、目录浏览和指定文件读取。

显著优点

成本优势突出是该 Skill 最核心的竞争力。智谱 Coding Plan 提供 Lite（100次/月）、Pro（1000次/月）、Max（4000次/月）三档免费套餐，对于个人开发者和小型团队而言，完全能够覆盖日常的网络搜索、文档查阅需求，显著节省其他商业搜索 API 的配额消耗。

功能集成度高，将搜索、网页抓取、GitHub 仓库文档检索、图像识别、文件解析等多种能力整合在一个 Skill 中，避免了为不同功能安装多个独立工具的繁琐。特别是对于需要频繁查阅开源项目文档的开发者，zread 系列的仓库搜索、结构查看、文件读取功能形成了完整的文档工作流。

架构设计合理，采用 MCP（Model Context Protocol）协议与 Legacy API 双模式架构，默认优先使用 MCP 免费端点，仅在连接失败时自动 fallback 到 Legacy 模式。这种设计既保证了免费额度的优先使用，又在必要时提供了可用性保障。

安全合规性良好，API Key 通过环境变量管理，无硬编码敏感信息；所有网络调用均采用 HTTPS 加密传输；代码中未发现危险函数调用或命令注入风险。

潜在缺点与局限性

视觉理解功能的长期稳定性存疑。该功能通过逆向分析官方 npm 包实现，直接调用底层 open.bigmodel.cn/api/paas/v4/chat/completions API，而非官方提供的 MCP 端点。虽然当前测试显示可能走 Coding Plan 资源池，但官方已明确未提供视觉 MCP 端点（返回 404），后续智谱可能调整计费策略或限制此类调用方式，存在功能突然收费或失效的风险。

部分参数的实现存在妥协。--recency（时间筛选）和 --domain（域名过滤）参数在 MCP 模式下并非原生支持，而是通过向搜索词注入前缀（如 site:example.com、最近一周）模拟实现，实际过滤效果取决于搜索引擎的理解，无法保证精确过滤。对于需要严格过滤场景的用户，这可能带来体验不一致。

来源可信度为 T3 级别。该 Skill 由 GitHub 个人开发者 wnzzer 维护，相比企业或知名组织背书的 T1/T2 级别项目，存在维护可持续性和账号安全风险，需要用户持续关注更新动态。

Legacy 模式的 fallback 策略存在隐患。当 MCP 因内容安全策略（content filter）拦截时，系统不会 fallback 到 Legacy 模式，而是返回空结果并提示修改搜索词。这意味着部分敏感词搜索在两种模式下都可能失败，且 Legacy 模式走账户余额，Coding Plan 用户通常余额不足，fallback 后仍可能失败。

适合的目标群体

该 Skill 最适合以下用户群体：

1. 个人开发者与独立开发者：需要网络搜索、文档查阅能力，但希望控制 API 成本的用户；
2. 开源项目贡献者：频繁需要搜索 GitHub 仓库文档、查看目录结构、读取特定文件的技术人员；
3. AI Agent 构建者：需要在 Agent 工作流中集成搜索、网页抓取、图像理解能力的开发者；
4. 学生与研究人员：预算有限，需要基础搜索和文档解析功能的学术场景用户。

不适合对服务稳定性有极高要求的企业生产环境，或需要严格合规审计的金融、医疗等敏感行业。

使用风险

性能风险：MCP 协议基于 HTTP 流式传输，在网络不稳定环境下可能出现 session 中断，虽然代码实现了自动重连，但仍会影响响应速度。视觉理解功能涉及图片 base64 编码传输，大图片可能导致请求体积过大、响应延迟。

依赖项风险：该 Skill 仅依赖 Python 标准库和 requests，依赖审计得分 90 分，无可疑依赖包，风险较低。但需注意 Python 版本兼容性，建议使用 Python 3.8+。

计费突变风险：视觉理解和文件解析功能当前通过 Legacy API 调用，虽然可能享受 Coding Plan 免费额度，但智谱官方未明确承诺长期免费。建议用户定期查看智谱账户用量，关注官方公告，避免因计费策略调整产生意外费用。

数据隐私风险：搜索关键词、网页内容、图片数据、文件内容均会传输至智谱 AI 服务器进行处理，虽然使用 HTTPS 加密，但用户需自行评估是否符合自身数据隐私要求。