知乎CLI来了，知乎 AI 工具 完整教程

Kelvin3.2万 曝光 · 164 收藏

从注册・配置・使用到进阶技巧，一篇讲透 请下载安装 zhihu-cli skill 并完成初始化配置

https://developer-cdn.zhihu.com/zhihu-cli/releases/stable/skill/zhihu-cli-skill.zip

知乎开放平台为 AI Agent 提供了官方 CLI、Skill 和 MCP 支持。本教程按实际使用流程，一步步带你从零上手。

1. 注册账号

打开 https://developer.zhihu.com 进入知乎数据开放平台。

点击右上角「注册」按钮，使用知乎账号登录并完成实名认证。

实名认证是必须的，否则无法获取 Access Secret。

注册完成后，进入「个人中心」，这里就是你后续所有操作的起点。

2. 获取 Access Secret

在个人中心页面，找到「Access Secret」相关入口，点击生成或查看密钥。

密钥格式类似 XXXX-XXXX-XXXX-XXXX，复制后妥善保存。

注意：Secret 只显示一次，建议立即复制并保存到安全位置。

这个 Secret 是你调用官方接口的唯一凭证，相当于 API 的密码。

3. 安装 CLI

官方推荐使用 uv 进行安装，这是目前最快的 Python 工具管理方式。

在终端执行：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后，推荐安装 klarkxy/zhihu-search 这个封装最好的工具：

uvx zhihu-search install-skill

安装 Skill 后，执行保存密钥命令：

uvx zhihu-search --save-token 你的AccessSecret

这一步只需做一次，之后所有 Agent 都能使用。

4. 验证使用

安装完成后，先验证是否成功：

uvx zhihu-search --probe

如果返回成功信息，说明配置无误。

常用命令示例：

# 知乎站内搜索 uvx zhihu-search search "RAG 评测方法" --count 5 # 全网搜索 uvx zhihu-search search global "Claude Code 使用技巧" --count 8 # 查看热榜 uvx zhihu-search trending --limit 10 # 直答（支持 thinking 模式） uvx zhihu-search ask "什么是 ReAct Agent？" --model thinking # 查看剩余额度 uvx zhihu-search --quota

5. 进阶技巧

Codex 配置（最推荐）

uvx zhihu-search install-skill --agent codex

或注册 MCP（更稳定）：

codex mcp add zhihu -- uvx zhihu-search serve --tools compact

Claude Code 配置

uvx zhihu-search install-skill --agent claude-code # 或 claude mcp add zhihu -- uvx zhihu-search serve --tools compact

Cursor 配置

在 Cursor Settings → MCP 中添加：

{ "mcpServers": { "zhihu": { "command": "uvx", "args": ["zhihu-search", "serve", "--tools", "compact"] } } }

六. 官方版 vs 社区版使用建议

  • 主要让 Agent 做研究、选题、内容输入 → 优先官方版
  • 需要发内容、点赞、看完整评论 → 使用 pyzhihu-cli
  • 两者结合使用效果最佳

1、先说结论：两条路，怎么选

现在的Agent 已经能帮你写稿、做研究、挖选题，知乎内容依然是很多垂直领域最硬的素材来源。问题只有一个：你让 Agent 怎么拿到这些内容，以及怎么把内容发出去？

终端里能用的知乎工具，分成两条完全不同的路线：

一个必须先纠正的常见误解：zhihu-search 不是知乎官方发布的 CLI。它是社区开源项目 （作者 klarkxy，SATA License v2.0），底层调用知乎数据开放平台的正式接口。准确说法是「基于知乎官方开放平台的社区封装」。知乎官方提供的是 developer.zhihu.com 的 API 体系，CLI / Skill / MCP 是社区在这套 API 上做的接入层。

按需求直接对号入座：

  • 你要让 Codex、Claude Code、Cursor 搜知乎、研究选题、拿热榜 → 只装路线一。
  • 你要在终端看完整回答和评论、发文章、点赞、关注 → 只装路线二。
  • 既要研究又要发布运营 → 两条都装，互补，本文第六部分给出组合工作流。

选错的典型后果：只装了路线一，Agent 搜资料很爽，但你让它发条想法，它会直接告诉你做不到；只装了路线二，终端里刷知乎没问题，但让 Agent 高频调用来做研究会踩风控雷。

2、三个概念：CLI、Skill 和 MCP

动手前先把三个词分清，后面所有配置都围绕它们展开。

1. CLI：你自己敲命令

命令行工具，装完直接在终端用，适合临时查询、测试功能、写脚本、排查问题：

uvx zhihu-search trending --limit 10 zhihu hot -l 10

2. Skill：Agent 知道该怎么用命令

Skill 是写给 AI Agent 的使用说明和操作规范。装好后你不必记命令，直接对 Agent 说自然语言：

  • 搜索知乎上关于 Claude Code 的高赞讨论
  • 查看今天的知乎热榜，找出适合写文章的选题

Agent 根据 Skill 判断该调哪个命令、传什么参数。

3. MCP：Agent 直接调用结构化工具

MCP 把外部能力注册成 AI 客户端可直接调用的工具，适合高频、长期使用。

一句话区分：

  • CLI：你自己敲命令。
  • Skill：Agent 知道该怎么使用命令。
  • MCP：Agent 能直接看到并调用结构化工具。

对 Codex / Claude Code 用户，最实用的配置是 Skill + MCP 组合：Skill 负责理解任务，MCP 负责稳定执行。zhihu-search 的 Skill 在检测到已注册 zhihu MCP 时会优先调用 MCP 工具，MCP 不可用才回退 CLI 命令。

3、环境准备 （两条路线共用）

3.1 安装 uv

zhihu-search 通过 uvx 运行，pyzhihu-cli 推荐用 uv tool 安装，所以先装 uv。

macOS / Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows 用户在 PowerShell 中按 uv 官方文档 执行对应命令，不要照抄 curl | sh。

装完关闭并重开终端，验证：

uv --version uvx --version

找不到命令 → 99% 是 PATH 没刷新，重开终端即可；仍不行按官方文档手动配 PATH。

3.2 确认 Node.js（只影响 zhihu-search 的 Skill 安装）

uvx zhihu-search install-skill 底层调用官方 npx skills，要求本机有 Node.js。这是最容易被忽略的卡点：

node --version # 有输出即可

只打算用 CLI / MCP、不装 Skill 的可以跳过。

3.3 确认 Python 版本 （只影响 pyzhihu-cli）

python3 --version # 需要 3.10 或更高

4、路线一：zhihu-search —— 给 Agent 喂知乎内容

4.1 能力清单

基于知乎数据开放平台，当前覆盖：

https://github.com/klarkxy/zhihu-search/blob/main/AGENT_SETUP.md

接入方式：CLI、Skill、MCP、OpenWebUI、DSH 插件 （DeepSeek Harness 用户可用 dsh plugin --profile web add "github:klarkxy/zhihu-search"）。

注意它的边界：不做账号操作——不发文章、不点赞、不看个人评论流。它的定位是给 Agent 提供知识输入，不是替你运营账号。

4.2 获取 Access Secret

  1. 打开知乎数据开放平台，注册并完成平台要求的认证。
  2. 进入个人中心 （developer.zhihu.com/personal） 创建 Access Secret。

关于免费额度：如前文核实说明，一切以个人中心当日显示为准，不要把任何具体数字当成长期承诺。

安全红线：

  • 不把完整 Access Secret 发到聊天窗口、截图、文章或 Git 仓库。
  • 不建议把密钥明文写进 MCP JSON 配置。
  • 怀疑泄露 → 立即到个人中心撤销并重建。
  • 凭证保存位置：~/.config/zhihu-search/credentials.json；也支持环境变量 ZHIHU_ACCESS_SECRET（优先级更高，适合服务器 / CI 场景）。

4.3 保存并验证凭证 （一次性）

在自己的本机终端执行：

# 保存 uvx zhihu-search --save-token "你的 AccessSecret" # 检查凭证是否已配置 （只报状态和来源，不消耗额度、不输出密钥） uvx zhihu-search --check-token # 真实连通性测试 （会请求一次热榜，消耗 1 次额度） uvx zhihu-search --probe # 查看额度使用 uvx zhihu-search --quota # 需要清除本机凭证时 uvx zhihu-search --clear-token

4.4 安装 Skill

# 默认：全局安装给 Codex（底层调用 npx skills，需要 Node.js） uvx zhihu-search install-skill # 同时给 Codex 和 Claude Code uvx zhihu-search install-skill --agent codex --agent claude-code # 只给某一个 uvx zhihu-search install-skill --agent codex uvx zhihu-search install-skill --agent claude-code # 只装到当前项目 （明确需要项目隔离时才用） uvx zhihu-search install-skill --project

Skill 安装后以 ~/.agents/skills 为统一来源，为目标 Agent 建立入口。日常用全局安装即可。

4.5 注册 MCP（推荐与 Skill 搭配）

Codex

codex mcp add zhihu -- uvx zhihu-search serve --tools compact # 验证，应看到 enabled: true、command: uvx、参数含 zhihu-search serve --tools compact codex mcp get zhihu

注册后新建或重开 Codex 任务；工具还没出现再重启客户端。

Claude Code

uvx zhihu-search install-skill --agent claude-code claude mcp add zhihu -- uvx zhihu-search serve --tools compact

重启 Claude Code 或新开会话，然后测试：

使用知乎搜索，查找关于 RAG 评测方法的高质量讨论，并总结不同观点。

Cursor

在 Settings → MCP 中添加：

{ "mcpServers": { "zhihu": { "command": "uvx", "args": ["zhihu-search", "serve", "--tools", "compact"] } } }

保存后重启 Cursor。前提：本机已经执行过 --save-token。

--tools 三种模式怎么选

https://github.com/BAIGUANGMEI/zhihu-cli

other 是 compact 模式下的低频工具开关，用来管理 9 个低频工具 （5 个用户数据 + 2 个 PDF + 2 个 PPT） 的展开 / 收起 / 重置。不建议一上来就用 full——工具太多会增加 Agent 的选择负担。

安全设计：PDF 本机上传和 OAuth token 交换只允许 CLI 执行，不会暴露成模型可调用的工具。也可用环境变量 ZHIHU_MCP_TOOLS 设默认模式，命令行 --tools 优先于环境变量。

4.6 常用 CLI 命令

# 站内搜索 uvx zhihu-search search "RAG 评测方法" --count 5 # 知乎直答 （三档模型：fast / thinking / agent） uvx zhihu-search ask "什么是 ReAct Agent？" --model thinking # 热榜 uvx zhihu-search trending --limit 10 # 输出 JSON 供脚本处理 （所有业务命令都支持） uvx zhihu-search search "AI Agent" --count 10 --format json # 低频能力 （CLI 直接调） uvx zhihu-search user-contents --content-type article --limit 10 uvx zhihu-search pdf-upload "./report.pdf" uvx zhihu-search ppt-create "https://zhuanlan.zhihu.com/p/123" --pages 12 uvx zhihu-search oauth-url "<app_id>" "<redirect_uri>" # 帮助 uvx zhihu-search --help uvx zhihu-search search --help # 全网搜索的具体子命令/参数以这里为准，不同版本可能有差异

注：全网搜索是 search 能力的一部分，具体子命令、参数不同版本可能调整，务必以 uvx zhihu-search search --help 的实际输出为准，不要死记某个具体子命令写法。

4.7 五分钟验收清单

按顺序跑完，路线一就通了：

uvx --version # ① uv 正常 uvx zhihu-search --check-token # ② 凭证已保存 uvx zhihu-search --probe # ③ 接口连通 codex mcp get zhihu # ④ MCP 已注册 （Codex 用户） # ⑤ 新建 Codex 任务，输入：搜知乎热榜并挑 5 个适合写长文的选题

5、路线二：pyzhihu-cli —— 在终端完整操作账号

5.1 能力清单

pyzhihu-cli（PyPI 包名，命令名为 zhihu） 是非官方知乎客户端，通过二维码或 Cookie 建立个人账号登录态，走知乎 V4 内部接口：

  • 认证：扫码登录 （终端渲染二维码） 或手动粘贴 Cookie
  • 阅读：搜索问题 / 回答 / 文章 / 话题 / 用户；热榜 （含热门回答）；问题详情、回答全文、评论；用户主页、回答、文章、粉丝、关注；推荐 Feed、话题详情
  • 互动：赞同 / 取消赞同、关注 / 取消关注问题、收藏夹、通知
  • 创作：发布提问、想法、文章 （图文混合、HTML 富文本）；删除自己发布的内容
  • 输出：所有数据命令支持 --json

它更像一个终端版知乎客户端，而不是知识检索 API。它也自带 Agent Skill（clawhub install pyzhihu-cli），装完 Agent 能自动获取完整命令说明。

  • 最新版本：v0.2.4
  • 许可证：Apache License 2.0

5.2 安装

要求 Python 3.10+：

python3 --version # 确认 3.10+ uv tool install pyzhihu-cli # 或 pipx install pyzhihu-cli zhihu --version zhihu --help # 已安装过，升级 uv tool upgrade pyzhihu-cli

5.3 登录 （推荐扫码）

zhihu login --qrcode

  • 二维码直接渲染在终端，同时保存为 ~/.zhihu-cli/login_qrcode.png（Windows：%USERPROFILE%\.zhihu-cli\login_qrcode.png）
  • 用知乎 App 扫码并在手机上确认，在二维码过期前完成
  • Agent 场景下，可以让 Agent 读取这张图片发给你扫码，形成登录闭环

zhihu status # 本地校验 Cookie 是否存在 （注意：不联网） zhihu whoami # 查看当前登录账号资料

备用方案——手动 Cookie 登录 （至少包含 z_c0、_xsrf、d_c0 三个字段）：

zhihu login --cookie "z_c0=xxx; _xsrf=yyy; d_c0=zzz"

Cookie 等同于账号凭证，只存在本机 ~/.zhihu-cli/cookies.json（权限 0600），不外传；不用了执行 zhihu logout 清除。

5.4 阅读类命令

# 搜索 zhihu search "Python 学习" zhihu search "机器学习" --type topic zhihu search "张三" --type people zhihu search "Python" --json # 热榜：默认 50 条、每条附 3 条热门回答 zhihu hot zhihu hot -l 10 # 只看 10 条 zhihu hot -a 5 # 每条附 5 条回答 zhihu hot -a 0 # 仅标题，不带回答 （最清爽） zhihu hot --json # 问题与回答 zhihu question <question_id> zhihu question <question_id> --answers --limit 10 zhihu answer <answer_id> zhihu answer <answer_id> --comments --limit 5 # 用户 （url_token 是个人主页 zhihu.com/people/xxx 里的 xxx） zhihu user <url_token> zhihu user-answers <url_token> --sort voteups zhihu user-articles <url_token> zhihu followers <url_token> zhihu following <url_token> # 推荐 Feed 与话题 zhihu feed --limit 5 # 仅列表 （ID、类型、标题、作者） zhihu feeds -l 3 -c 5 # 3 条推荐 + 全文 + 每条 5 条评论 zhihu topic <topic_id> --questions

5.5 互动类命令

# 赞同 / 取消赞同 zhihu vote <answer_id> zhihu vote <answer_id> --undo # 关注 / 取消关注问题 zhihu follow-question <question_id> zhihu follow-question <question_id> --undo

5.6 创作类命令

描述和正文均支持 HTML 富文本 （<p>、<strong>、<a> 等），-i 可重复使用添加多图：

# 发布提问 zhihu ask "如何学习 Python？" zhihu ask "什么是机器学习？" -d "请详细解释" -t 19550517 -t 19551275 # 发布想法 zhihu pin "今天天气真好！" zhihu pin "标题" -c "想法正文内容" -i image1.jpg -i image2.jpg # 发布文章 （可带封面） zhihu article "文章标题" "文章内容" zhihu article "标题" "内容" -t 19550517 -i cover.jpg # 删除自己发布的内容 （默认有确认提示） zhihu delete-question <问题 ID> zhihu delete-pin <想法 ID> zhihu delete-article <文章 ID>

删除不可逆，保留默认确认，不要习惯性加 -y 跳过。

5.7 给 AI Agent 用

clawhub install pyzhihu-cli

装完 Agent 能自动获取完整命令说明。扫码场景下，Agent 可以读取 ~/.zhihu-cli/login_qrcode.png 发给你，你在手机上扫码即可完成登录闭环。

5.8 风险与边界

  • 非官方客户端：知乎内部接口变化可能导致部分命令失效 （先 uv tool upgrade pyzhihu-cli，再查项目 Issues）。
  • 风控：高频抓取、批量点赞、频繁发布可能触发限制；账号被要求验证、限流的概率比开放平台路线高得多。
  • Cookie 会过期，过期重新扫码。
  • 不要用主账号跑大规模、无人值守的批量操作；写操作 （发布 / 删除 / 点赞 / 关注） 保留人工确认。
  • 自动化操作仍需遵守知乎平台规则。

6、两条路线完整对比

https://developer.zhihu.com/

7、组合工作流：研究 → 创作 → 审核 → 发布

两条线都装时，真正的价值才出来。推荐流程：

① 选题 zhihu-search trending / search → 让 Codex 归纳热榜和高赞讨论 ② 研究 zhihu-search search + ask → 收集观点、数据、案例 ③ 创作 Codex / Claude Code 根据材料出提纲和初稿 ④ 审核 人工核对事实、引用、标题、表达 （AI 不碰这步） ⑤ 发布 pyzhihu-cli article "标题" "正文" -i cover.jpg ⑥ 互动 少量、有人工确认的点赞和关注

对应到 Codex 里的实际提示词：

用知乎搜索查一下「Claude Code 使用经验」的高赞讨论， 按安装配置、模型选择、成本、效率四类整理痛点， 再从今天热榜里挑 3 个能结合这些痛点写文章的选题，给出标题建议。

审核完发布：

zhihu article "我把 Claude Code 用了三个月，这些坑你一定会踩" "<正文>" -i cover.jpg

这套组合的关键不是追求完全无人值守——AI 负责信息整理和重复劳动，人负责判断、审核和账号安全。分工记一句话：路线一负责「找什么写」，路线二负责「实际发出去和互动」。

两套工具的凭证彼此独立，不要混淆：

  • zhihu-search 用开放平台的 Access Secret
  • pyzhihu-cli 用个人账号的 Cookie 登录态
  • 任何一种凭证都不发给 Agent、不写进公开配置

8、快速上手路线图

方案 A：只给 Codex 增加知乎搜索能力

# 1. 装 uv（重开终端） curl -LsSf https://astral.sh/uv/install.sh | sh # 2. 确认 Node.js（Skill 安装需要） node --version # 3. 装 Skill uvx zhihu-search install-skill --agent codex # 4. 保存 Access Secret（developer.zhihu.com 个人中心获取） uvx zhihu-search --save-token "你的 AccessSecret" # 5. 连通测试 uvx zhihu-search --probe # 6. 注册 MCP 并验证 codex mcp add zhihu -- uvx zhihu-search serve --tools compact codex mcp get zhihu

完成后新建 Codex 任务，输入：

搜索知乎上关于 Claude Code 的讨论，找出 10 个高频痛点，并按安装、模型、成本、效率四类整理。

方案 B：只在终端使用知乎账号

uv tool install pyzhihu-cli zhihu login --qrcode zhihu whoami zhihu hot -l 10

方案 C：研究与发布都要

依次完成 A 和 B。两套凭证独立管理，互不通用。

七、排错手册

排错顺序永远是：运行时 （命令能不能跑）→ 凭证 （probe / status）→ 客户端配置 （MCP 注册、JSON 语法）→ 重启。

zhihu-search 侧

https://github.com/klarkxy/zhihu-search

能不能完全自动发布和互动

技术上可以调用相关命令，但不建议把发布、删除、点赞、关注设成无确认的自动流程。稳妥方案：AI 生成内容和参数，用户审核后再执行。

八、安全清单

  • [ ] Access Secret 只存在本机 ~/.config/zhihu-search/credentials.json 或环境变量 ZHIHU_ACCESS_SECRET
  • [ ] Cookie 只存在本机 ~/.zhihu-cli/cookies.json（权限 0600）
  • [ ] 两套凭证彼此独立，永不混淆、永不外发
  • [ ] 不把任何凭证发进聊天窗口、截图、文章或 Git 仓库
  • [ ] 删除、发布、点赞、关注保留人工确认
  • [ ] 不拿主账号做无人值守批量操作
  • [ ] 怀疑泄露立即处置：Secret 撤销重建 / Cookie 执行 logout

九、最终决策与总结

决策 checklist：

  • 主要用 Agent 做研究和写作辅助 → 优先路线一 （zhihu-search）
  • 需要终端发内容、点赞、看完整回答 → 必须上路线二 （pyzhihu-cli）
  • 两者都想要 → 路线一装 Skill + MCP，路线二扫码登录，两边命令都留着

一句话总结：

zhihu-search 负责找资料和做研究 pyzhihu-cli 负责账号读取与操作 人工负责审核和最终确认

这不是两个同类工具之间的竞争，而是两条不同的技术路线：一个连接官方开放平台，一个连接个人账号。理解这一点，后面的安装、配置和风险判断就都清晰了。

参考资料

  • 知乎数据开放平台
  • klarkxy/zhihu-search（v1.4.2 已确认，SATA License v2.0）
  • zhihu-search AGENT_SETUP.md
  • zhihu-search on PyPI
  • BAIGUANGMEI/zhihu-cli（v0.2.4，Apache-2.0 许可证）
  • pyzhihu-cli on PyPI
  • uv 官方安装文档

注：开放平台额度、接口权限、第三方项目命令及支持范围均可能更新，实际使用前建议再核对开发者后台和项目最新 README。本文所有版本号、命令语法均以核实时 （2026-08-16） 的公开信息为准。