Loading... # jina CLI 工具入门指南 # 一、概述 ## 1. 简介 ### A. 是什么 jina 是一个轻量级的命令行工具，封装了 Jina AI Reader API，可以将任意 URL 转换为 LLM 友好的输入格式。特别适合阅读 X（Twitter）、博客、新闻网站等复杂网页。 ### B. 为什么学 - 解决网页内容难以被 AI 读取的问题 - 提供统一的网络搜索和内容提取能力 - 支持多种输出格式，便于集成到各类 AI Agent 中 ### C. 学完能做什么 - 使用 jina 读取任意网页内容 - 使用 jina 进行 AI 驱动的网络搜索 - 将 jina 集成到 Claude Code、OpenClaw 等 AI 工具中 - 批量处理 URL 列表，自动化内容采集 ## 2. 前置知识 ### A. 必备技能 - 基本命令行操作 - 理解 URL 和 HTTP 请求概念 ### B. 推荐知识 - 使用过 AI 助理或 Claude Code - 了解 Markdown 格式 - 了解 JSON 数据结构 # 二、环境准备 ## 1. 系统要求 - Linux：主流发行版（Ubuntu、CentOS 等） - macOS：10.15 及以上版本 - Windows：10/11（需 WSL 或使用 Git Bash） - 对于 OpenClaw 或 Claude Code Skill 方式：需安装对应平台 ## 2. 安装步骤 jina 提供三种独立的安装方式，根据使用场景选择。 ### 方式一：OpenClaw Skill（推荐本地 AI 助理） 适用场景：本地 AI 助理、自动化工作流、需要文件系统操作 安装步骤： ```bash # 创建 jina-cli skill 目录并下载 mkdir -p ~/.openclaw/workspace/skills/jina-cli curl -o ~/.openclaw/workspace/skills/jina-cli/SKILL.md \ https://raw.githubusercontent.com/geekjourneyx/jina-cli/main/skills/jina-cli/SKILL.md ``` 验证安装： ```bash # 启动 OpenClaw openclaw # 在 OpenClaw 中直接使用 jina 命令 # skill 会自动从 ~/.openclaw/workspace/skills/jina-cli/ 加载 ``` ### 方式二：Claude Code Skill（推荐用于 AI 辅助开发） 适用场景：在 Claude Code 中使用 AI 协助处理网页内容 安装步骤： ```bash # 1. 确保已安装 Node.js 和 Claude Code node --version # v18.0.0 或更高版本 # 2. 安装 jina skill npx skills add https://github.com/geekjourneyx/jina-cli --skill jina-cli ``` 安装后验证： ```bash # 在 Claude Code 中可以直接使用 # 无需额外操作，skill 会自动加载 ``` ### 方式三：CLI 二进制文件（推荐用于终端使用） 适用场景：在终端/脚本中使用，或与其他工具集成 一键安装（Linux/macOS）： ```bash curl -fsSL https://raw.githubusercontent.com/geekjourneyx/jina-cli/main/scripts/install.sh | bash ``` 安装脚本会自动： - 检测系统架构（Linux/macOS，amd64/arm64） - 下载对应平台的二进制文件 - 安装到 ~/.local/bin/jina 或 ~/bin/jina - 提示如何添加到 PATH（如需要） 手动安装： ```bash # Linux amd64 wget https://github.com/geekjourneyx/jina-cli/releases/latest/download/jina-linux-amd64 -O jina chmod +x jina sudo mv jina /usr/local/bin/ # macOS ARM64 (Apple Silicon) wget https://github.com/geekjourneyx/jina-cli/releases/latest/download/jina-darwin-arm64 -O jina chmod +x jina sudo mv jina /usr/local/bin/ ``` 从源码构建： ```bash git clone https://github.com/geekjourneyx/jina-cli.git cd jina-cli go build -o jina ./cli sudo mv jina /usr/local/bin/ ``` ## 3. 验证安装 ```bash # 检查是否安装成功 jina --version # 预期输出: jina version 1.0.0 (构建时间: ..., 提交: ...) # 测试基本功能 jina read --url "https://example.com" ``` ## 4. 安装方式对比 | 特性 | OpenClaw Skill | Claude Code Skill | CLI 二进制 | |-----|----------------|------------------|-----------| | 安装位置 | ~/.openclaw/workspace/skills/jina-cli/ | ~/.claude/skills/ | ~/.local/bin/jina | | 使用环境 | OpenClaw 本地 AI 助理 | Claude Code | 任何终端/脚本 | | AI 集成 | AI 自动理解功能 | AI 自动理解功能 | 需要手动调用 | | 文件权限 | 可访问本地文件系统 | 受限 | 完整权限 | | 脚本执行 | 可执行脚本 | 受限 | 完整权限 | | 更新方式 | 重新下载/npx skills update | npx skills update | 重新运行安装脚本 | | 适用场景 | 本地 AI 助理、自动化 | AI 辅助开发 | 脚本集成、日常使用 | 推荐选择： - OpenClaw：最强能力，本地运行，可操作文件系统 - Claude Code：开发体验好，AI 辅助编码 - CLI 二进制：最轻量，适合脚本集成 注意：三种方式完全独立，可以同时安装，互不干扰。 # 三、核心概念 ## 1. 基本术语 - Jina AI Reader API：将网页转换为 LLM 友好格式的 API 服务 - read 命令：读取 URL 内容并转换为指定格式 - search 命令：执行网络搜索并处理结果 - config 命令：管理配置文件和参数 ## 2. 工作原理 ```mermaid graph LR subgraph 输入 A[URL] B[搜索关键词] end A -->|read 命令| C[Jina API] B -->|search 命令| C C -->|解析/搜索| D[LLM 友好格式] D --> E[输出] E -->|Markdown/Text/HTML| F[终端] E -->|JSON| G[AI Agent] ```   ## 3. 架构图 ```mermaid graph TD User[用户] -->|输入命令| CLI[jina CLI] CLI -->|发送请求| Config[配置管理] Config -->|读取/更新| ConfigFile[配置文件] CLI -->|HTTP 请求| API[Jina API] API -->|解析网页| Content[网页内容] API -->|AI 搜索| Results[搜索结果] Content -->|格式化| Output[输出] Results -->|格式化| Output Output --> CLI CLI --> User ```   # 四、快速开始 ## 1. 读取网页内容 ```bash # 读取单个 URL jina read --url "https://example.com" # 读取 X (Twitter) 帖子，启用图片描述 jina read -u "https://x.com/user/status/123456789" --with-alt # 输出 Markdown 格式 jina read -u "https://example.com" --output markdown # 保存到文件 jina read -u "https://example.com" --output-file result.md ``` ## 2. 批量处理 ```bash # 从文件读取 URL 列表 cat > urls.txt << EOF https://example.com/page1 https://example.com/page2 https://x.com/user/status/123 EOF jina read --file urls.txt ``` ## 3. 网络搜索 ```bash # 搜索关键词 jina search --query "golang latest news" # 限定搜索站点 jina search -q "AI developments" --site techcrunch.com --site theverge.com # 限制结果数量 jina search -q "climate change" --limit 10 ``` # 五、进阶内容 ## 1. 配置管理 配置文件位于 ~/.jina-reader/config.yaml： ```bash # 查看所有配置 jina config list # 设置配置项 jina config set timeout 60 jina config set with-generated-alt true # 获取单个配置 jina config get timeout # 查看配置文件路径 jina config path ``` ### 配置项说明 | 配置项 | 环境变量 | 默认值 | 说明 | |-------|---------|-------|------| | api_base_url | JINA_API_BASE_URL | https://r.jina.ai/ | Read API 地址 | | search_api_url | JINA_SEARCH_API_URL | https://s.jina.ai/ | Search API 地址 | | default_response_format | JINA_RESPONSE_FORMAT | markdown | 响应格式 | | default_output_format | JINA_OUTPUT_FORMAT | json | 输出格式 | | timeout | JINA_TIMEOUT | 30 | 请求超时（秒） | | with_generated_alt | JINA_WITH_GENERATED_ALT | false | 启用图片描述 | | proxy_url | JINA_PROXY_URL | "" | 代理服务器 | | api_key | JINA_API_KEY | "" | API 密钥（用于更高速率限制） | 优先级：命令行参数 > 环境变量 > 配置文件 > 默认值 ## 2. API Key 使用 添加 API Key 可以获得更高的速率限制： ```bash # 方式 1：配置文件设置 jina config set api_key jina_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 方式 2：环境变量 export JINA_API_KEY=jina_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 方式 3：命令行参数 jina read -u "https://example.com" -k jina_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` 获取 API Key：访问 Jina AI Reader 注册并获取。 ## 3. 输出格式 ### JSON 格式（默认） ```json { "success": true, "data": { "url": "https://example.com", "title": "Example Domain", "content": "# Example Domain\n\nThis domain is..." } } ``` ### Markdown 格式 ```bash jina read -u "https://example.com" --output markdown ``` 输出： ```markdown # Example Domain **Source**: https://example.com --- # Example Domain This domain is for use in illustrative examples... ``` # 六、高级用法 ## 1. 禁用缓存 ```bash jina read -u "https://example.com" --no-cache ``` ## 2. 使用代理 ```bash jina read -u "https://example.com" --proxy "http://proxy.com:8080" ``` ## 3. CSS 选择器提取 ```bash # 只提取指定元素 jina read -u "https://example.com" --target-selector "article.main" # 等待元素加载 jina read -u "https://example.com" --wait-for-selector "#content" ``` ## 4. 处理 SPA 应用 ```bash # 对于带 hash 路由的 SPA，使用 POST 方法 jina read -u "https://example.com/#/route" --post ``` ## 5. 设置 Cookie ```bash jina read -u "https://example.com" --cookie "session=abc123" ``` ## 6. 与 AI Agent 集成 ```bash # 在 Claude Code 或其他 AI 工具中使用 jina read -u "https://x.com/elonmusk/status/123456" --output json # 搜索最新信息 jina search -q "golang 1.24 release notes" --output json ``` # 七、命令参考 ## 1. 主命令 ```bash jina - CLI tool for Jina AI Reader and Search APIs Usage: jina [command] Available Commands: read Extract and convert content from URLs search Search the web with AI-powered results config Manage configuration completion Generate shell completion help Help about any command Flags: -a, --api-base string API base URL (overrides config) -k, --api-key string API key (overrides config) -o, --output string Output format: json, markdown (default "json") -v, --verbose Verbose output -h, --help help for jina --version version for jina ``` ## 2. read 命令 ```bash # 读取网页内容 jina read [flags] Flags: -u, --url string URL to read (required) -f, --file string File containing URLs to read --with-alt Include generated image descriptions --no-cache Disable caching --proxy string Proxy server URL --cookie string Cookie string --target-selector string CSS selector to extract --wait-for-selector string Wait for selector before extraction --post Use POST method --output-file string Save output to file -o, --output string Output format: json, markdown (default "json") ``` ## 3. search 命令 ```bash # 搜索网络 jina search [flags] Flags: -q, --query string Query to search (required) --site strings Limit search to specific sites --limit int Limit number of results (default 5) --with-alt Include generated image descriptions --no-cache Disable caching --proxy string Proxy server URL -o, --output string Output format: json, markdown (default "json") ``` ## 4. config 命令 ```bash # 管理配置 jina config [command] Available Commands: list List all configuration get Get a configuration value set Set a configuration value path Show config file path ``` # 八、常见问题 ## 1. 安装问题 ### Q：一键安装脚本执行后提示 command not found A：安装目录可能不在 PATH 中。手动添加： ```bash # 添加到 .bashrc 或 .zshrc export PATH="$PATH:$HOME/.local/bin" export PATH="$PATH:$HOME/bin" ``` ### Q：macOS 提示无法打开，因为来自身份不明的开发者 A：允许应用运行： ```bash xattr -d com.apple.quarantine /path/to/jina ``` ## 2. 配置问题 ### Q：API Key 不生效 A：检查优先级，命令行参数 > 环境变量 > 配置文件。确认没有在命令行或环境变量中覆盖配置。 ### Q：代理设置不生效 A：确认代理地址格式正确，建议使用完整的 URL 格式，如 http://proxy.example.com:8080。 ## 3. 运行问题 ### Q：读取某些网页失败 A：可能原因包括： - 网站有反爬虫机制 - URL 不存在或已被删除 - 超时设置过短 可尝试使用 --no-cache 禁用缓存，或增加 timeout 配置。 ### Q：搜索结果不准确 A：尝试： - 使用更精确的搜索关键词 - 使用 --site 参数限定搜索范围 - 增加 --limit 获取更多结果 # 九、开发 ## 1. 运行测试 ```bash # 运行测试 go test ./... # 运行测试并计算覆盖率 go test -cover ./... ``` ## 2. 构建 ```bash # 本地构建 go build -o jina ./cli # 交叉编译 GOOS=linux GOARCH=amd64 go build -o jina-linux-amd64 ./cli GOOS=darwin GOARCH=arm64 go build -o jina-darwin-arm64 ./cli GOOS=windows GOARCH=amd64 go build -o jina-windows-amd64.exe ./cli ``` ## 3. 项目结构 ```bash jina-cli/ ├── cli/ │ ├── main.go # 入口 │ ├── read.go # read 命令 │ ├── search.go # search 命令 │ ├── config.go # config 命令 │ └── pkg/ │ ├── api/ # HTTP 客户端 │ ├── config/ # 配置管理 │ └── output/ # 输出格式化 └── scripts/ └── install.sh # 安装脚本 ``` *** ## 参考资料 1. [jina-cli GitHub 仓库](https://github.com/geekjourneyx/jina-cli) 2. [Jina AI Reader API 文档](https://jina.ai/reader) 最后修改：2026 年 03 月 01 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏