知乎 CLI 详细教程：用官方开放平台把知乎接入终端与 AI Agent

Smartpig7835 曝光 · 47 收藏

如果你想让终端、脚本或 AI Agent 搜索知乎、看热榜、调用知乎直答，还想读取自己的创作、关注和收藏，知乎数据开放平台现在提供了一条官方路径：Zhihu CLI。

这篇教程按知乎官方文档（鉴权、Zhihu CLI、HTTP API）整理，重点讲清楚：它是什么、如何安装、如何配置 Access Secret、常用命令怎么用、如何排错，以及什么时候应该改用 OAuth。

先说结论：Zhihu CLI 使用的是 Access Secret + Bearer 鉴权，不是网页登录 Cookie，也不是 OAuth Token。它主要服务于“让自己的 Agent 使用自己的知乎数据”。

一、Zhihu CLI 能做什么？

官方 CLI 将能力分成两类：公共知识和本人数据。

公共知识能力：

  • search zhihu：搜索知乎问题、回答、文章，返回标题、作者、摘要和原文链接。
  • search global：搜索知乎之外的全网资料，可按站点和发布时间筛选。
  • hot：读取当前知乎热榜，用来发现议题。
  • answer：调用知乎直答，获得检索增强的综合回答。

本人数据能力：

  • me contents：读取当前 Access Secret 所属账号的回答、文章、视频、想法和问题。
  • me followees：读取自己的关注列表。
  • me favorites lists/items：读取收藏夹和收藏夹中的公开内容。
  • me favorites recent：读取近期收藏。

边界也很明确：CLI 不接受“代查某个用户”的 user ID，也不接受 OAuth Token 作为本人数据命令的替代品。要访问其他用户已经授权的数据，应该开发 OAuth 应用。

二、准备工作：Access Secret 是什么？

Access Secret 是知乎开放平台给开发者的访问凭证。官方 HTTP 请求统一要求两个关键请求头：

<CLI> auth logout

其中：

  • Authorization 必须是 Bearer 加一个空格，再接 Access Secret。
  • X-Request-Timestamp 是秒级 Unix 时间戳，例如 date +%s 的输出。
  • JSON 接口建议带上 Content-Type: application/json。

申请步骤：

  1. 打开知乎开放平台个人中心：https://developer.zhihu.com/profile
  2. 使用知乎账号登录。
  3. 点击“申请新 Access Secret”。
  4. 复制凭证，并只在私密环境中交给 CLI 或 Agent。

Access Secret 等同于完整 API 访问权限，不要放进公开文章、Git 仓库、截图、群聊或前端代码。泄露后应在个人中心删除并重新申请；被删除的凭证无法恢复。

三、安装官方 Skill 与 CLI

知乎官方提供的是一个 Skill 压缩包，里面包含 CLI 的标准调用协议、命令参考、HTTP API 参考和跨平台安装脚本。把下面这段提示词发送给你的 AI Agent 即可开始：

请下载安装 zhihu-cli skill 并完成初始化配置 https://developer-cdn.zhihu.com/zhihu-cli/releases/stable/skill/zhihu-cli-skill.zip

如果你在本地手动安装 Skill，解压后先执行状态检查。假设 Skill 根目录是 <skill-dir>：

macOS / Linux：

<CLI> me contents \
  --type all \
  --sort ts \
  --order desc \
  --offset 0 \
  --limit 20

Windows PowerShell：

curl 'https://developer.zhihu.com/api/v1/content/hot_list?Limit=10' \
  -H 'Authorization: Bearer <your_access_secret>' \
  -H "X-Request-Timestamp: $(date +%s)" \
  -H 'Content-Type: application/json'

首次安装需要明确同意，因为 setup 会从官方 HTTPS manifest 下载当前平台 CLI。安装脚本会校验下载域名、文件大小、SHA-256、归档结构和二进制自报版本；不需要 sudo，也不会修改 PATH。

安装命令：

# macOS / Linux

bash <skill-dir>/scripts/setup.sh

setup 完成后会输出 JSON，其中最重要的是绝对路径：

<CLI> search global \
  --query 'RAG evaluation' \
  --filter 'host=="arxiv.org" AND publish_time>=1778494631'

后续建议始终使用这个 binary_path，不要假设 zhihu-cli 一定已经在 PATH 中。下文用 <CLI> 代指这条绝对路径。

查看能力清单和帮助：

<CLI> me contents --type all --limit 1

四、配置凭证：推荐 stdin，不要放进命令参数

把 Access Secret 交给 CLI 时，推荐使用标准输入：

<CLI> auth status

Agent 应启动命令后，把凭证通过进程 stdin 传入，而不是拼在命令行参数里。这样能避免凭证出现在 shell 历史、进程列表和日志中。

如果你已经在环境变量中安全注入凭证，也可以：

curl -G 'https://developer.zhihu.com/api/v1/content/zhihu_search' \
  --data-urlencode 'Query=怎么理解RAG' \
  --data-urlencode 'Count=5' \
  -H 'Authorization: Bearer <your_access_secret>' \
  -H "X-Request-Timestamp: $(date +%s)" \
  -H 'Content-Type: application/json'

CLI 的凭证读取顺序是：

  1. ZHIHU_ACCESS_SECRET 环境变量；
  2. 操作系统密钥链；
  3. 没有凭证时返回 AUTH_REQUIRED。

桌面系统会优先使用系统凭据存储：macOS Keychain、Windows Credential Manager，或 Linux 的 Secret Service。SSH、CI、容器通常没有可用的桌面密钥链，应由宿主 Secret Store 以进程级环境变量注入。

检查本地状态：

https://developer.zhihu.com/docs?key=authorization

这条命令只检查本地配置，不联网，不消耗额度。需要在线验证时显式加 --verify：

<CLI> search zhihu --query 'Agent Memory' --count 10

验证通过后，可以用一条最小业务请求验收：

curl 'https://developer.zhihu.com/v1/chat/completions' \
  -X POST \
  -H 'Authorization: Bearer <your_access_secret>' \
  -H "X-Request-Timestamp: $(date +%s)" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "zhida-fast-1p5",
    "messages": [{
      "role": "user",
      "content": "如何选择 RAG 评测方法？"
    }],
    "stream": false
  }'

即使内容列表为空，只要服务端返回成功，也说明初始化链路正常。

退出登录只会删除本机保存的凭证，不会撤销开放平台中的 Access Secret：

<CLI> hot --limit 20

五、最常用的命令

1. 搜索知乎

{
  "ok": true,
  "binary_path": "/absolute/path/to/zhihu-cli",
  "auth_configured": false,
  "next_action": "request_access_secret"
}

--count 范围是 1～10。结果包含 Title、ContentType、ContentText、AuthorName、Url、赞同数、评论数等字段。

摘要只是检索摘要，不等于完整原文。写报告或做事实核查时，应打开返回的 Url 阅读原文，并把原始链接保留下来。

2. 搜索全网

<CLI> auth status --verify

--count 最大为 20；--search-db 可以是 all、realtime 或 static。

高级筛选示例：

<CLI> me favorites items \
  --url-token 123456789 \
  --offset 0 \
  --limit 20

支持的过滤字段包括 host 和 publish_time，逻辑运算符使用大写的 AND、OR，复杂条件可以用括号。只想搜知乎站内时，直接使用 search zhihu，不要用全网搜索的 host 过滤去模拟。

3. 查看热榜

<CLI> capabilities
<CLI> --help
<CLI> search --help
<CLI> me favorites items --help

--limit 范围是 1～30，默认 30。热榜适合发现“现在大家在讨论什么”，不等于事实核查。发现主题后，再用知乎搜索和全网搜索交叉验证。

4. 调用知乎直答

https://developer.zhihu.com/profile

官方 CLI 支持三个模型档位：

  • zhida-fast-1p5：快速回答，适合简单问题；
  • zhida-thinking-1p5：深度思考，适合需要分析的问题；
  • zhida-agent：智能思考，适合更复杂的任务。

需要流式输出时：

<CLI> answer \
  --query '如何理解 Agent Memory？' \
  --model zhida-fast-1p5

直答适合快速获得综合答案；深度研究、观点比较和事实核查，仍然应该先搜索原始资料。

5. 查看自己的创作

https://developer.zhihu.com/docs

--type 可选：all、answer、article、zvideo、pin、question；--sort 可选 ts 或 like_count；--limit 最大 50。

返回的是标题和摘要，不是完整正文。如果 Paging.IsEnd=false，再使用 Paging.NextOffset 请求下一页。不要为了“备份所有内容”而默认遍历全部数据，按任务读取最小范围即可。

6. 查看关注与收藏

<CLI> search global \
  --query 'Agent Memory' \
  --count 10 \
  --search-db all

读取指定收藏夹时，先拿到收藏夹的 UrlToken，再查询内容：

Authorization: Bearer <your_access_secret>
X-Request-Timestamp: <Unix 秒级时间戳>

收藏内容支持分页，按 Paging.NextOffset 翻页。recent 只代表近期收藏，不是完整历史；收藏夹列表当前不承诺可通过 offset 遍历全部收藏夹。

六、脚本化：直接调用官方 HTTP API

如果你不是在使用 Agent，而是要把能力接进自己的脚本，可以直接按官方鉴权方式调用 HTTP API。

知乎搜索：

<CLI> me followees --offset 0 --limit 20

<CLI> me favorites lists --limit 20
<CLI> me favorites recent --limit 20

热榜：

https://developer.zhihu.com/docs?key=zhihu_cli

知乎直答是 POST：

bash <skill-dir>/scripts/run.sh status

搜索、热榜返回结构化 JSON；直答在 stream=false 时返回 JSON，stream=true 时返回 SSE。所有请求都应把时间戳设置为当前秒级 Unix 时间。

七、错误排查清单

CLI 自身会用稳定 JSON 和退出码报告错误。常见情况：

  • AUTH_REQUIRED：打开 https://developer.zhihu.com/profile 申请 Access Secret，然后执行 auth set --secret-stdin。
  • AUTH_INVALID：重新生成或重新配置凭证，不要把旧凭证回显到日志。
  • KEYCHAIN_UNAVAILABLE：桌面密钥链不可用，改用宿主 Secret Store 注入 ZHIHU_ACCESS_SECRET。
  • ENV_SHADOWS_KEYCHAIN：环境变量覆盖了密钥链中的值，先检查环境变量是否仍然存在。
  • 30001：频率限制，停止重复重试。
  • 30002：额度耗尽，等待额度恢复或联系开放平台。
  • NETWORK_ERROR / TIMEOUT：检查网络；只对搜索、热榜等幂等 GET 做有限重试，不要对直答 POST 盲目重试。

一个容易踩坑的点：有些 GET API 即使 HTTP 状态是 200，也可能在 JSON 中返回业务错误。判断成功要同时看 CLI 退出码和响应里的 Code，不能把 Code: 20001 当成“搜索无结果”。

八、额度、数据边界与安全实践

官方开放平台文档当前列出的邀测额度是：全网搜索每日 5000 次、知乎搜索每日 5000 次、热榜每日 100 次、知乎直答每日 100 次。同一账号下多个 Access Secret 共享额度池，页面测试与 API 调用也共享额度。额度和规则可能调整，最终以个人中心的用量统计为准。

建议把下面几条当作生产环境底线：

  1. Access Secret 只通过 stdin、操作系统密钥链或进程级 Secret Store 传递。
  2. 不把凭证放进 .env、仓库、容器镜像、前端 bundle 或日志。
  3. 不在 --verbose、错误堆栈和调试输出中打印 Authorization。
  4. 只读取完成任务所需的最小数据，不默认遍历全部关注和收藏。
  5. 摘要不等于原文，重要结论要回到返回的知乎链接核对。
  6. 凭证泄露后立即在个人中心删除并重新申请。

九、Access Secret 与 OAuth 怎么选？

可以用一句话区分：

  • “我的 Agent 访问我的知乎数据”——用 Access Secret + Zhihu CLI。
  • “我的网站让很多知乎用户登录，并代表他们访问各自数据”——接入知乎 OAuth。

不要把 Access Secret 分发给你的应用用户，也不要把 OAuth Token 填进 CLI 的本人数据命令。第三方 Web 应用应走独立的 OAuth 授权流程，并按最小权限、用户同意和安全存储的原则实现。

十、一个实用的 Agent 工作流

最后给一个可以直接复制给 Agent 的任务模板：

先用知乎热榜发现与“AI 搜索”相关的话题； 再用 zhihu-cli search zhihu 搜索知乎社区观点； 然后用 search global 补充官方资料和新闻； 最后给我一份 5 条以内的总结，每条保留原始链接， 并明确区分“知乎社区观点”和“外部资料”。

这个流程的关键不是“让 AI 直接给答案”，而是把发现、检索、交叉验证和溯源拆开：热榜负责发现，搜索负责取证，直答负责在需要时快速汇总，原始 URL 负责最终核验。

官方入口：

  • 文档中心：https://developer.zhihu.com/docs
  • 鉴权说明：https://developer.zhihu.com/docs?key=authorization
  • CLI 文档：https://developer.zhihu.com/docs?key=zhihu_cli
  • 个人中心：https://developer.zhihu.com/profile
  • Skill 下载：https://developer-cdn.zhihu.com/zhihu-cli/releases/stable/skill/zhihu-cli-skill.zip

如果你准备把知乎接进自己的 Agent、脚本或知识工作流，建议先从 capabilities 和 --help 开始，再按任务选择最小权限和最小数据范围。

本文依据知乎数据开放平台官方文档整理，命令和字段以当前文档与 CLI 版本为准。