{"id":"19ccef4d-ddec-4bbe-9e9a-b3e57482a70f","entityType":"agent","slug":"clawhub-cn-big-cabbage-httpie","name":"Httpie","canonicalUrl":"https://www.xpersona.co/agent/clawhub-cn-big-cabbage-httpie","canonicalPath":"/agent/clawhub-cn-big-cabbage-httpie","generatedAt":"2026-10-12T14:35:48.665Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T23:35:43.302Z","emptyReason":null},"description":"HTTPie - 人性化的 HTTP 命令行客户端 Skill: Httpie Owner: cn-big-cabbage Summary: HTTPie - 人性化的 HTTP 命令行客户端 Tags: latest:0.1.1 Version history: v0.1.1 | 2026-06-16T06:50:52.712Z | auto - 元数据 now specifies required binary as http (was httpie). - Bumped version to 0.1.1. - Removed skill-card.md file. - No changes to user-facing commands or documentation content. v0.1.0 | 2026-04-15T01:01:42.210Z | user Initial release - HTTPie CLI skill for human-friendly","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 975 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17dbd0j0kazk5ay31x9kv1z3n84f04v:httpie","sourceUrl":"https://clawhub.ai/cn-big-cabbage/httpie","homepage":"https://clawhub.ai/cn-big-cabbage/skills/httpie","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/cn-big-cabbage/httpie","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/cn-big-cabbage/skills/httpie","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"HTTPie - 人性化的 HTTP 命令行客户端 Skill: Httpie Owner: cn-big-cabbage Summary: HTTPie - 人性化的 HTTP 命令行客户端 Tags: latest:0.1.1 Version history: v0.1.1 | 2026-06-16T06:50:5"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:35:43.302Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:35:43.302Z","emptyReason":null},"stars":null,"forks":null,"downloads":975,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"0.1.1","tractionLabel":"975 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:35:43.126Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T23:35:43.302Z","lastCrawledAt":"2026-10-11T23:35:43.126Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T23:35:43.126Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.1","createdAt":"2026-06-16T06:50:52.712Z","changelog":"- 元数据 now specifies required binary as http (was httpie). - Bumped version to 0.1.1. - Removed skill-card.md file. - No changes to user-facing commands or documentation content.","fileCount":7,"zipByteSize":18817},{"version":"0.1.0","createdAt":"2026-04-15T01:01:42.210Z","changelog":"Initial release - HTTPie CLI skill for human-friendly API testing","fileCount":7,"zipByteSize":18881}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17dbd0j0kazk5ay31x9kv1z3n84f04v:httpie","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cn-big-cabbage-httpie/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cn-big-cabbage-httpie/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cn-big-cabbage-httpie/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cn-big-cabbage-httpie/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cn-big-cabbage-httpie/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cn-big-cabbage-httpie/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T14:35:48.665Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cn-big-cabbage-httpie/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cn-big-cabbage-httpie/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cn-big-cabbage-httpie/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cn-big-cabbage-httpie/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T23:35:43.302Z","emptyReason":null},"readme":"Skill: Httpie\n\nOwner: cn-big-cabbage\n\nSummary: HTTPie - 人性化的 HTTP 命令行客户端\n\nTags: latest:0.1.1\n\nVersion history:\n\nv0.1.1 | 2026-06-16T06:50:52.712Z | auto\n\n- 元数据 now specifies required binary as http (was httpie).\n- Bumped version to 0.1.1.\n- Removed skill-card.md file.\n- No changes to user-facing commands or documentation content.\n\nv0.1.0 | 2026-04-15T01:01:42.210Z | user\n\nInitial release - HTTPie CLI skill for human-friendly API testing\n\nArchive index:\n\nArchive v0.1.1: 7 files, 18817 bytes\n\nFiles: guides/01-installation.md (5956b), guides/02-quickstart.md (7718b), guides/03-advanced-usage.md (10049b), skill-card.md (2380b), SKILL.md (4018b), troubleshooting.md (12572b), _meta.json (125b)\n\nFile v0.1.1:SKILL.md\n\n---\nname: httpie\ndescription: HTTPie - 人性化的 HTTP 命令行客户端\nversion: 0.1.1\nmetadata:\n openclaw:\n requires:\n bins:\n - http\n emoji: 🌐\n homepage: https://httpie.io\n---\n\n# HTTPie 人性化 HTTP 命令行客户端\n\n## 技能概述\n\n本技能帮助用户通过命令行发送 HTTP 请求，调试 API 接口，适用于以下场景：\n\n- **REST API 调试**: 发送 GET/POST/PUT/DELETE 等各类 HTTP 请求\n- **接口测试**: 快速验证 API 端点的请求与响应\n- **文件上传下载**: 通过命令行进行文件传输\n- **身份认证**: 支持 Basic、Bearer Token、Digest 等多种认证方式\n- **会话管理**: 跨请求保持 Cookie 与认证状态\n- **格式化输出**: 自动语法高亮显示 JSON、XML 响应体\n\n**主要特点**: 语法简洁、自动格式化、彩色输出、内置 JSON 支持、比 curl 更易读写\n\n## 使用流程\n\nAI 助手将引导你完成以下步骤：\n\n1. 安装 HTTPie（如未安装）\n2. 构建 HTTP 请求（方法、URL、请求头、请求体）\n3. 执行请求并查看格式化响应\n4. 根据响应调整请求参数\n5. 将成功的命令保存为可复用脚本\n\n## 关键章节导航\n\n- [安装指南](./guides/01-installation.md)\n- [快速开始](./guides/02-quickstart.md)\n- [高级用法](./guides/03-advanced-usage.md)\n- [常见问题](./troubleshooting.md)\n\n## AI 助手能力\n\n当你向 AI 描述请求需求时，AI 会：\n\n- 自动识别请求类型（GET/POST/PUT/PATCH/DELETE）\n- 根据描述构建正确的请求头和请求体\n- 执行请求命令并解析响应\n- 识别常见 HTTP 错误状态码并给出建议\n- 自动处理 JSON 数据序列化\n- 管理认证令牌和会话 Cookie\n- 将复杂请求转换为可读的 HTTPie 命令\n\n## 核心功能\n\n- 支持全部 HTTP 方法（GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS）\n- 自动 JSON 请求体序列化与响应格式化\n- 彩色语法高亮（请求头、响应头、响应体）\n- 内置多种认证方式（Basic、Digest、Bearer）\n- 持久化 Session 管理（跨请求 Cookie）\n- 文件上传与二进制下载支持\n- HTTPS 与 SSL 证书验证\n- 代理支持（HTTP/HTTPS/SOCKS）\n- 离线模式（仅打印请求不发送）\n- 与 curl 命令互转\n\n## 命令速查表\n\n### 基础请求\n\n```bash\n# GET 请求\nhttp GET https://api.example.com/users\n\n# 简写（默认 GET）\nhttp https://api.example.com/users\n\n# POST JSON（自动推断 Content-Type: application/json）\nhttp POST https://api.example.com/users name=\"张三\" age:=25\n\n# PUT 更新\nhttp PUT https://api.example.com/users/1 name=\"李四\"\n\n# PATCH 部分更新\nhttp PATCH https://api.example.com/users/1 email=\"li@example.com\"\n\n# DELETE 删除\nhttp DELETE https://api.example.com/users/1\n```\n\n### 请求参数与请求头\n\n```bash\n# URL 查询参数（== 语法）\nhttp https://api.example.com/search q==\"hello world\" page==2\n\n# 自定义请求头（: 语法）\nhttp https://api.example.com/users \"Authorization: Bearer mytoken123\"\n\n# 多个请求头\nhttp https://api.example.com/data \"X-API-Key: abc123\" \"Accept: application/json\"\n```\n\n### 认证\n\n```bash\n# Basic 认证\nhttp -a username:password https://api.example.com/protected\n\n# Bearer Token\nhttp https://api.example.com/me \"Authorization: Bearer \"\n\n# Digest 认证\nhttp --auth-type=digest -a user:pass https://api.example.com/secure\n```\n\n### 输出控制\n\n```bash\n# 仅显示响应体\nhttp --body https://api.example.com/users\n\n# 仅显示响应头\nhttp --headers https://api.example.com/users\n\n# 显示请求+响应（调试用）\nhttp --verbose https://api.example.com/users\n\n# 安静模式（无输出，只看退出码）\nhttp --quiet https://api.example.com/health\n\n# 保存响应到文件\nhttp https://api.example.com/file.pdf > file.pdf\n```\n\n## 安装要求\n\n- Python 3.7+ 或直接使用独立二进制包\n- 无其他强制依赖\n\n## 许可证\n\nBSD-3-Clause License\n\n## 项目链接\n\n- GitHub: https://github.com/httpie/cli\n- 官网: https://httpie.io\n- 文档: https://httpie.io/docs/cli\n\nFile v0.1.1:_meta.json\n\n{\n \"ownerId\": \"kn7c5ry95ff7x22mt3fx6j0q3d81p8t3\",\n \"slug\": \"httpie\",\n \"version\": \"0.1.1\",\n \"publishedAt\": 1781592652712\n}\n\nFile v0.1.1:guides/01-installation.md\n\n# 安装指南\n\n**适用场景**: 首次使用 HTTPie，需要在本地环境中完成安装和配置\n\n---\n\n## 一、安装前准备\n\n### 目标\n\n确保系统具备运行 HTTPie 的基础环境，选择最适合的安装方式\n\n### 前置条件\n\n- 操作系统：macOS、Linux（Ubuntu/Debian/Fedora/Arch）、Windows 10+\n- 网络连接（下载安装包）\n- （pip 方式）Python 3.7 或更高版本\n\n### 检查现有环境\n\n**AI 执行说明**: AI 将自动检查当前系统环境，判断最佳安装路径\n\n```bash\n# 检查是否已安装 httpie\nhttp --version\n\n# 检查 Python 版本（如使用 pip 安装）\npython3 --version\n\n# 检查 pip\npip3 --version\n```\n\n**期望结果**:\n- 若 `http --version` 有输出，说明已安装，无需重复安装\n- Python 3.7+ 可用 pip 安装方式\n- pip 3.x 可正常使用\n\n---\n\n## 二、安装方式选择\n\nHTTPie 提供多种安装方式，根据你的系统和偏好选择：\n\n| 安装方式 | 适用系统 | 优点 |\n|--------|--------|-----|\n| Homebrew | macOS / Linux | 最简单，自动管理依赖 |\n| pip | 全平台（需要 Python） | 版本最新，适合 Python 开发者 |\n| pipx | 全平台（需要 Python） | 隔离安装，推荐方式 |\n| apt/yum/pacman | Linux | 系统包管理，稳定 |\n| 独立二进制 | macOS / Linux | 无需 Python 依赖 |\n| Windows Installer | Windows | 官方安装包，最方便 |\n\n---\n\n## 三、各平台安装步骤\n\n### 方法 1: macOS 使用 Homebrew（推荐）\n\n**AI 执行说明**: AI 可以直接执行 Homebrew 安装命令\n\n```bash\n# 安装 HTTPie\nbrew install httpie\n\n# 验证安装\nhttp --version\n```\n\n**期望输出**:\n```\nHTTPie 3.x.x\n```\n\n如果未安装 Homebrew，先执行：\n\n```bash\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n```\n\n---\n\n### 方法 2: 使用 pip 安装（全平台）\n\n**AI 执行说明**: AI 可以直接执行 pip 安装命令\n\n```bash\n# 使用 pip 安装（推荐使用 pip3）\npip3 install httpie\n\n# 验证安装\nhttp --version\n\n# 如果 pip3 不可用，尝试 pip\npip install httpie\n```\n\n**注意**: 部分系统中 `http` 命令可能与系统命令冲突，可以使用完整路径：\n\n```bash\n# 查找安装路径\nwhich http\npython3 -m httpie --version\n```\n\n---\n\n### 方法 3: 使用 pipx 安装（推荐，隔离环境）\n\npipx 会将 HTTPie 安装在独立的虚拟环境中，避免依赖冲突：\n\n```bash\n# 先安装 pipx（如未安装）\npip3 install pipx\npipx ensurepath\n\n# 安装 HTTPie\npipx install httpie\n\n# 验证安装\nhttp --version\n```\n\n---\n\n### 方法 4: Linux 系统包管理器\n\n**Ubuntu / Debian**:\n\n```bash\nsudo apt update\nsudo apt install httpie\n\nhttp --version\n```\n\n**Fedora / RHEL / CentOS**:\n\n```bash\nsudo dnf install httpie\n\n# 或者使用 yum（旧版系统）\nsudo yum install httpie\n```\n\n**Arch Linux**:\n\n```bash\nsudo pacman -S httpie\n```\n\n**Alpine Linux**:\n\n```bash\napk add httpie\n```\n\n---\n\n### 方法 5: Windows 安装\n\n**方式 A - pip（推荐）**:\n\n```powershell\n# 在 PowerShell 或 CMD 中执行\npip install httpie\n\n# 验证\nhttp --version\n```\n\n**方式 B - Chocolatey**:\n\n```powershell\nchoco install httpie\n```\n\n**方式 C - Scoop**:\n\n```powershell\nscoop install httpie\n```\n\n---\n\n### 方法 6: 独立二进制安装（无需 Python）\n\nHTTPie 提供预编译的独立二进制文件，无需 Python 环境：\n\n```bash\n# macOS (Apple Silicon)\ncurl -SsL https://packages.httpie.io/mac/http.latest.arm64 -o /usr/local/bin/http\nchmod +x /usr/local/bin/http\n\n# macOS (Intel)\ncurl -SsL https://packages.httpie.io/mac/http.latest.x86_64 -o /usr/local/bin/http\nchmod +x /usr/local/bin/http\n\n# Linux (x86_64)\ncurl -SsL https://packages.httpie.io/linux/http.latest.x86_64 -o /usr/local/bin/http\nchmod +x /usr/local/bin/http\n```\n\n---\n\n## 四、验证安装\n\n**AI 执行说明**: AI 将验证安装是否成功并进行简单测试\n\n```bash\n# 检查版本\nhttp --version\n\n# 发送一个测试请求（HTTPie 官方测试端点）\nhttp GET https://httpie.io/hello\n```\n\n**期望输出（版本检查）**:\n```\nHTTPie 3.x.x\n```\n\n**期望输出（测试请求）**:\n```\nHTTP/1.1 200 OK\nContent-Type: application/json\n...\n\n{\n \"ahoy\": [\n \"Hello, World! 👋\"\n ],\n ...\n}\n```\n\n**成功标志**:\n- HTTPie 版本信息正确显示\n- 测试请求返回 200 状态码\n- 响应体 JSON 格式化输出（有缩进和高亮）\n\n---\n\n## 五、升级 HTTPie\n\n```bash\n# pip 升级\npip3 install --upgrade httpie\n\n# Homebrew 升级\nbrew upgrade httpie\n\n# pipx 升级\npipx upgrade httpie\n\n# 查看当前版本\nhttp --version\n```\n\n---\n\n## 六、卸载 HTTPie\n\n```bash\n# pip 卸载\npip3 uninstall httpie\n\n# Homebrew 卸载\nbrew uninstall httpie\n\n# pipx 卸载\npipx uninstall httpie\n```\n\n---\n\n## 七、常见安装问题\n\n### 问题 1: `http` 命令找不到\n\n**症状**: 安装后执行 `http` 提示 `command not found`\n\n**解决方案**:\n\n```bash\n# 检查 pip 安装位置\npython3 -m site --user-base\n\n# 将用户 bin 目录加入 PATH（添加到 ~/.zshrc 或 ~/.bashrc）\nexport PATH=\"$HOME/.local/bin:$PATH\"\n\n# 立即生效\nsource ~/.zshrc\n```\n\n### 问题 2: 权限不足\n\n**症状**: 安装时报 `Permission denied` 错误\n\n**解决方案**:\n\n```bash\n# 使用用户级安装（不需要 sudo）\npip3 install --user httpie\n\n# 或使用 pipx（推荐）\npip3 install pipx\npipx install httpie\n```\n\n### 问题 3: pip 网络超时\n\n**症状**: pip install 时网络连接失败或超时\n\n**解决方案**:\n\n```bash\n# 使用国内镜像\npip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple httpie\n\n# 或使用阿里云镜像\npip3 install -i https://mirrors.aliyun.com/pypi/simple/ httpie\n```\n\n---\n\n## 完成确认\n\n### 检查清单\n\n- [ ] HTTPie 已成功安装并可运行\n- [ ] `http --version` 显示正确版本号\n- [ ] 测试请求 `http GET https://httpie.io/hello` 返回 200\n- [ ] 响应体 JSON 已正确格式化和高亮显示\n\n### 下一步\n\n继续阅读 [快速开始](02-quickstart.md) 学习 HTTPie 的基本用法\n\nFile v0.1.1:guides/02-quickstart.md\n\n# 快速开始\n\n**适用场景**: 已安装 HTTPie，想快速学习基本用法发送 HTTP 请求\n\n---\n\n## 一、HTTPie 语法概览\n\n### 基本命令格式\n\n```\nhttp [选项] [方法] URL [请求项...]\n```\n\n| 部分 | 说明 | 示例 |\n|-----|-----|-----|\n| `选项` | 控制行为的标志 | `--verbose`, `--json`, `--follow` |\n| `方法` | HTTP 方法（可省略，默认 GET） | `GET`, `POST`, `PUT`, `DELETE` |\n| `URL` | 请求地址 | `https://api.example.com/users` |\n| `请求项` | 请求头、请求体、查询参数 | `name=\"张三\"`, `\"X-Token: abc\"` |\n\n### 请求项语法\n\nHTTPie 使用特殊符号区分不同类型的请求项：\n\n| 符号 | 类型 | 示例 |\n|-----|-----|-----|\n| `:` | 请求头 | `\"Content-Type: application/json\"` |\n| `==` | URL 查询参数 | `page==1` |\n| `=` | JSON 字符串字段 | `name=\"张三\"` |\n| `:=` | JSON 非字符串字段 | `age:=25`, `active:=true` |\n| `@` | 表单文件字段 | `file@photo.jpg` |\n| `=@` | JSON 文件内容（字符串） | `data=@content.txt` |\n| `:=@` | JSON 文件内容（解析） | `config:=@config.json` |\n\n---\n\n## 二、发送 GET 请求\n\n**AI 执行说明**: AI 可以直接执行以下命令并返回响应\n\n### 最简单的 GET 请求\n\n```bash\n# 发送 GET 请求（方法可省略）\nhttp https://httpbin.org/get\n\n# 显式指定方法\nhttp GET https://httpbin.org/get\n```\n\n**期望输出**（自动格式化 + 彩色高亮）:\n\n```\nHTTP/1.1 200 OK\nContent-Type: application/json\nDate: Mon, 01 Jan 2024 12:00:00 GMT\n...\n\n{\n \"args\": {},\n \"headers\": {\n \"Accept\": \"application/json, */*;q=0.5\",\n \"Host\": \"httpbin.org\",\n \"User-Agent\": \"HTTPie/3.x.x\"\n },\n \"url\": \"https://httpbin.org/get\"\n}\n```\n\n### 携带查询参数\n\n```bash\n# 单个查询参数（== 语法）\nhttp https://httpbin.org/get search==\"Hello World\" page==1\n\n# 等效的 URL 形式\nhttp \"https://httpbin.org/get?search=Hello+World&page=1\"\n```\n\n**AI 执行说明**: 推荐使用 `==` 语法，AI 会自动处理 URL 编码\n\n---\n\n## 三、发送 POST 请求\n\n### 发送 JSON 数据（自动推断）\n\n当请求项包含 `=` 或 `:=` 时，HTTPie 自动设置 `Content-Type: application/json`：\n\n```bash\n# 发送 JSON 对象\nhttp POST https://httpbin.org/post name=\"张三\" email=\"zhang@example.com\" age:=28\n\n# 等效的 JSON 内容：\n# {\"name\": \"张三\", \"email\": \"zhang@example.com\", \"age\": 28}\n```\n\n**注意**: 字符串用 `=`，数字/布尔/数组用 `:=`\n\n### 发送原始 JSON\n\n```bash\n# 使用管道传入原始 JSON\necho '{\"name\": \"李四\", \"roles\": [\"admin\", \"user\"]}' | http POST https://httpbin.org/post\n\n# 从文件读取 JSON\nhttp POST https://httpbin.org/post < data.json\n```\n\n### 发送表单数据\n\n使用 `--form` 或 `-f` 标志，Content-Type 变为 `application/x-www-form-urlencoded`：\n\n```bash\nhttp --form POST https://httpbin.org/post username=\"user1\" password=\"secret\"\n\n# 简写\nhttp -f POST https://httpbin.org/post username=\"user1\" password=\"secret\"\n```\n\n---\n\n## 四、自定义请求头\n\n**AI 执行说明**: AI 会根据 API 要求自动添加必要的请求头\n\n```bash\n# 添加自定义请求头（使用 : 语法）\nhttp https://api.example.com/users \"X-API-Key: abc123\" \"Accept: application/json\"\n\n# 发送带认证头的 POST 请求\nhttp POST https://api.example.com/data \\\n \"Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...\" \\\n \"Content-Type: application/json\" \\\n name=\"测试\"\n```\n\n---\n\n## 五、身份认证\n\n### Basic 认证\n\n```bash\n# -a 或 --auth 指定用户名:密码\nhttp -a admin:secret123 https://api.example.com/protected\n\n# 只指定用户名（会提示输入密码）\nhttp -a admin https://api.example.com/protected\n```\n\n### Bearer Token 认证\n\n```bash\n# 直接在请求头中传入 Token\nhttp https://api.example.com/me \"Authorization: Bearer my-access-token\"\n```\n\n### Digest 认证\n\n```bash\nhttp --auth-type=digest -a user:pass https://api.example.com/digest\n```\n\n---\n\n## 六、查看请求详情\n\n### 调试模式：显示请求和响应\n\n```bash\n# --verbose 显示完整的请求和响应（包含请求头）\nhttp --verbose GET https://httpbin.org/get\n\n# 简写 -v\nhttp -v GET https://httpbin.org/get\n```\n\n**期望输出**:\n\n```\nGET /get HTTP/1.1\nAccept: application/json, */*;q=0.5\nAccept-Encoding: gzip, deflate\nConnection: keep-alive\nHost: httpbin.org\nUser-Agent: HTTPie/3.x.x\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n...\n\n{\n ...\n}\n```\n\n### 离线模式：只打印请求不发送\n\n```bash\n# --offline 仅构建并打印请求，不实际发送\nhttp --offline POST https://api.example.com/users name=\"测试\" age:=20\n```\n\n**用途**: 在实际发送前检查请求格式是否正确\n\n---\n\n## 七、控制输出内容\n\n```bash\n# 只显示响应体（最常用）\nhttp --body https://httpbin.org/get\n# 简写\nhttp -b https://httpbin.org/get\n\n# 只显示响应头\nhttp --headers https://httpbin.org/get\n# 简写\nhttp -h https://httpbin.org/get\n\n# 同时显示请求头和响应头（不含响应体）\nhttp --print=Hh https://httpbin.org/get\n\n# 显示所有（请求头 + 请求体 + 响应头 + 响应体）\nhttp --print=HhBb https://httpbin.org/get\n```\n\n**`--print` 格式字符含义**:\n- `H` - 请求头\n- `B` - 请求体\n- `h` - 响应头\n- `b` - 响应体\n\n---\n\n## 八、处理 HTTPS\n\n```bash\n# HTTPie 默认验证 SSL 证书\nhttp https://api.example.com/secure\n\n# 跳过 SSL 验证（开发/测试环境，不推荐生产）\nhttp --verify=no https://self-signed.example.com/api\n\n# 使用自定义 CA 证书\nhttp --verify=/path/to/ca-bundle.crt https://internal.example.com/api\n\n# 使用客户端证书\nhttp --cert=/path/to/client.crt --cert-key=/path/to/client.key https://api.example.com\n```\n\n---\n\n## 九、实战示例\n\n### 示例 1: 查询用户列表\n\n```bash\n# 带分页和过滤的 GET 请求\nhttp https://jsonplaceholder.typicode.com/users\n```\n\n### 示例 2: 创建新资源\n\n```bash\n# POST 创建文章\nhttp POST https://jsonplaceholder.typicode.com/posts \\\n title=\"HTTPie 使用指南\" \\\n body=\"HTTPie 是一个人性化的 HTTP 客户端\" \\\n userId:=1\n```\n\n**期望响应**:\n```json\n{\n \"body\": \"HTTPie 是一个人性化的 HTTP 客户端\",\n \"id\": 101,\n \"title\": \"HTTPie 使用指南\",\n \"userId\": 1\n}\n```\n\n### 示例 3: 带认证的 API 请求\n\n```bash\n# 查询当前用户信息（Bearer Token）\nhttp https://api.github.com/user \"Authorization: Bearer ghp_xxxxx\"\n```\n\n### 示例 4: 下载文件\n\n```bash\n# 下载文件到当前目录（保留原始文件名）\nhttp --download https://example.com/image.png\n\n# 简写 -d\nhttp -d https://example.com/report.pdf\n\n# 指定保存路径\nhttp --download --output=/tmp/report.pdf https://example.com/report.pdf\n```\n\n---\n\n## 十、常用选项速查\n\n| 选项 | 简写 | 说明 |\n|-----|-----|-----|\n| `--verbose` | `-v` | 显示请求和响应的完整内容 |\n| `--headers` | `-h` | 只显示响应头 |\n| `--body` | `-b` | 只显示响应体 |\n| `--json` | `-j` | 强制 JSON 模式 |\n| `--form` | `-f` | 强制表单模式 |\n| `--download` | `-d` | 下载模式（保存到文件） |\n| `--auth` | `-a` | 身份认证 |\n| `--verify=no` | | 跳过 SSL 验证 |\n| `--follow` | | 跟随重定向 |\n| `--offline` | | 离线模式（不发送） |\n| `--quiet` | `-q` | 安静模式（无输出） |\n| `--timeout` | | 超时时间（秒） |\n\n---\n\n## 完成确认\n\n### 检查清单\n\n- [ ] 成功发送 GET 请求并看到格式化的 JSON 响应\n- [ ] 成功发送带 JSON 体的 POST 请求\n- [ ] 理解 `=`（字符串）和 `:=`（非字符串）的区别\n- [ ] 使用 `--verbose` 查看完整请求/响应\n- [ ] 使用 `--offline` 预览请求格式\n\n### 下一步\n\n继续阅读 [高级用法](03-advanced-usage.md) 学习会话管理、文件上传、代理设置等进阶功能\n\nFile v0.1.1:guides/03-advanced-usage.md\n\n# 高级用法\n\n**适用场景**: 已掌握 HTTPie 基础用法，需要使用会话管理、文件上传、代理、脚本集成等进阶功能\n\n---\n\n## 一、会话管理\n\nHTTPie 的 Session 功能可以在多个请求之间自动保持 Cookie、认证信息和请求头，非常适合需要登录状态的 API 测试。\n\n### 创建和使用具名 Session\n\n```bash\n# 第一次请求：登录并保存 Session\nhttp --session=my-api POST https://api.example.com/login \\\n username=\"admin\" password=\"secret\"\n\n# 后续请求：自动携带登录 Cookie\nhttp --session=my-api https://api.example.com/profile\n\n# Session 数据自动保存到 ~/.config/httpie/sessions/ 目录\n```\n\n**AI 执行说明**: AI 会在同一任务的多次请求中自动复用 Session，保持认证状态\n\n### 使用文件路径作为 Session\n\n```bash\n# 保存 Session 到指定文件\nhttp --session=/tmp/test-session.json POST https://api.example.com/login \\\n username=\"test\" password=\"123456\"\n\n# 从指定文件加载 Session\nhttp --session=/tmp/test-session.json https://api.example.com/dashboard\n```\n\n### 只读 Session（不修改 Session 文件）\n\n```bash\n# 使用 Session 但不更新它\nhttp --session-read-only=my-api https://api.example.com/data\n```\n\n### 查看 Session 文件内容\n\nSession 文件是 JSON 格式，可以直接查看：\n\n```bash\n# 查看保存的 Session 内容\ncat ~/.config/httpie/sessions/api.example.com/my-api.json\n```\n\nSession 文件结构示例：\n\n```json\n{\n \"__meta__\": {\n \"about\": \"HTTPie session file\"\n },\n \"auth\": {\n \"password\": null,\n \"type\": null,\n \"username\": null\n },\n \"cookies\": {\n \"session_id\": {\n \"expires\": null,\n \"path\": \"/\",\n \"secure\": false,\n \"value\": \"abc123xyz\"\n }\n },\n \"headers\": {}\n}\n```\n\n---\n\n## 二、文件上传\n\n### 单文件上传（multipart/form-data）\n\n```bash\n# 上传单个文件（@ 语法）\nhttp --form POST https://api.example.com/upload file@photo.jpg\n\n# 指定字段名\nhttp --form POST https://api.example.com/upload \\\n profile_picture@/path/to/avatar.png \\\n username=\"zhangsan\"\n```\n\n### 多文件上传\n\n```bash\n# 同时上传多个文件\nhttp --form POST https://api.example.com/upload \\\n file1@document.pdf \\\n file2@image.jpg \\\n description=\"批量上传测试\"\n```\n\n### 上传时指定 MIME 类型\n\n```bash\n# 指定文件的 Content-Type（格式：字段名@文件路径;type=MIME类型）\nhttp --form POST https://api.example.com/upload \\\n \"document@report.txt;type=text/plain\"\n```\n\n### 将文件内容作为 JSON 字段\n\n```bash\n# 将文件内容作为 JSON 字符串字段（=@ 语法）\nhttp POST https://api.example.com/data content=@message.txt\n\n# 将 JSON 文件内容解析后嵌入请求体（:=@ 语法）\nhttp POST https://api.example.com/config settings:=@config.json\n```\n\n---\n\n## 三、下载文件\n\n### 基本下载\n\n```bash\n# 下载文件（自动从 Content-Disposition 或 URL 推断文件名）\nhttp --download https://example.com/report.pdf\n\n# 简写\nhttp -d https://example.com/report.pdf\n\n# 指定保存文件名\nhttp --download --output=my-report.pdf https://example.com/report.pdf\n# 简写\nhttp -d -o my-report.pdf https://example.com/report.pdf\n```\n\n### 下载时显示进度条\n\n下载大文件时，HTTPie 会自动显示进度条：\n\n```bash\nhttp -d https://example.com/large-file.zip\n# 输出：Downloading 125.3 MB to \"large-file.zip\"\n# ████████████████████░░░░░░░░░░ 67% 84.0 MB/s 0:00:01\n```\n\n### 断点续传\n\n```bash\n# 从断点继续下载（如果服务器支持 Range 请求）\nhttp -d -c https://example.com/large-file.zip\n```\n\n---\n\n## 四、代理设置\n\n### 使用 HTTP/HTTPS 代理\n\n```bash\n# 指定 HTTP 代理\nhttp --proxy=http:http://proxy.example.com:8080 https://api.example.com/data\n\n# 指定 HTTPS 代理\nhttp --proxy=https:http://proxy.example.com:8080 https://api.example.com/data\n\n# 同时设置 HTTP 和 HTTPS 代理\nhttp \\\n --proxy=http:http://proxy.example.com:8080 \\\n --proxy=https:http://proxy.example.com:8080 \\\n https://api.example.com/data\n```\n\n### 使用 SOCKS 代理\n\n```bash\n# SOCKS5 代理（需要安装 requests[socks]）\npip3 install requests[socks]\n\nhttp --proxy=http:socks5://localhost:1080 https://api.example.com/data\nhttp --proxy=https:socks5://localhost:1080 https://api.example.com/data\n```\n\n### 通过环境变量设置代理\n\n```bash\n# 设置环境变量（对所有 HTTP 请求生效）\nexport HTTP_PROXY=http://proxy.example.com:8080\nexport HTTPS_PROXY=http://proxy.example.com:8080\n\n# 之后的 HTTPie 命令自动使用代理\nhttp https://api.example.com/data\n```\n\n---\n\n## 五、请求重定向与跟随\n\n```bash\n# 默认不跟随重定向，显示 301/302 响应\nhttp GET https://httpbin.org/redirect/3\n\n# 跟随重定向\nhttp --follow https://httpbin.org/redirect/3\n\n# 跟随重定向并查看所有中间请求\nhttp --follow --all https://httpbin.org/redirect/3\n\n# 限制最大重定向次数\nhttp --follow --max-redirects=5 https://httpbin.org/redirect/10\n```\n\n---\n\n## 六、超时控制\n\n```bash\n# 设置连接和读取超时（秒）\nhttp --timeout=10 https://api.example.com/slow-endpoint\n\n# 分别设置连接超时和读取超时（格式：连接超时,读取超时）\nhttp --timeout=2.5 https://api.example.com/data\n\n# 不设超时（谨慎使用）\nhttp --timeout=0 https://api.example.com/very-slow\n```\n\n---\n\n## 七、HTTPS 与证书\n\n### 使用自定义 CA 证书\n\n```bash\n# 使用 PEM 格式的 CA 证书\nhttp --verify=/etc/ssl/certs/ca-bundle.crt https://internal.example.com/api\n\n# 环境变量方式\nexport REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-bundle.crt\nhttp https://internal.example.com/api\n```\n\n### 客户端证书认证（mTLS）\n\n```bash\n# 使用客户端证书（cert 和 key 分开存储）\nhttp --cert=client.crt --cert-key=client.key https://api.example.com/mtls\n\n# 证书和私钥合并在一个 PEM 文件中\nhttp --cert=client.pem https://api.example.com/mtls\n```\n\n### 跳过证书验证（仅开发环境）\n\n```bash\n# 不验证服务器证书（有安全风险，仅用于开发测试）\nhttp --verify=no https://self-signed.dev.example.com/api\n```\n\n---\n\n## 八、输出格式化与着色\n\n### 控制格式化\n\n```bash\n# 强制格式化输出（即使重定向到文件）\nhttp --pretty=all https://api.example.com/data > output.txt\n\n# 仅着色不格式化\nhttp --pretty=colors https://api.example.com/data\n\n# 仅格式化不着色\nhttp --pretty=format https://api.example.com/data\n\n# 无格式化无着色（原始输出）\nhttp --pretty=none https://api.example.com/data\n```\n\n### 输出到文件（保留格式化）\n\n```bash\n# 响应体保存到文件，控制台显示元信息\nhttp --print=b https://api.example.com/data > response.json\n\n# 调试时保存完整响应\nhttp --verbose https://api.example.com/data > full-response.txt 2>&1\n```\n\n---\n\n## 九、与脚本集成\n\n### 在 Shell 脚本中使用\n\n```bash\n#!/bin/bash\n\n# 获取 Token\nTOKEN=$(http --body POST https://api.example.com/auth \\\n username=\"admin\" password=\"secret\" | python3 -c \"import sys,json; print(json.load(sys.stdin)['token'])\")\n\n# 使用 Token 请求数据\nhttp https://api.example.com/users \"Authorization: Bearer $TOKEN\"\n```\n\n### 检查 HTTP 状态码\n\n```bash\n# HTTPie 退出码：2xx 为 0，其他为非 0\nif http --check-status --quiet https://api.example.com/health; then\n echo \"服务正常\"\nelse\n echo \"服务异常\"\nfi\n\n# --check-status 在非 2xx 状态时返回非零退出码\n# 1: 网络错误\n# 2: 超时\n# 3: 意外 HTTP 3xx（不跟随重定向时）\n# 4: HTTP 4xx 客户端错误\n# 5: HTTP 5xx 服务端错误\n```\n\n### 批量请求\n\n```bash\n# 使用 for 循环批量请求\nfor id in 1 2 3 4 5; do\n echo \"--- 查询用户 $id ---\"\n http --body https://jsonplaceholder.typicode.com/users/$id\ndone\n\n# 从文件逐行读取 URL\nwhile read url; do\n http --check-status --quiet \"$url\" && echo \"OK: $url\" || echo \"FAIL: $url\"\ndone < urls.txt\n```\n\n---\n\n## 十、配置文件\n\nHTTPie 支持通过配置文件设置默认选项，避免每次重复输入。\n\n### 配置文件位置\n\n- **macOS/Linux**: `~/.config/httpie/config.json`\n- **Windows**: `%APPDATA%\\httpie\\config.json`\n- **自定义**: 通过环境变量 `HTTPIE_CONFIG_DIR` 指定\n\n### 配置示例\n\n```json\n{\n \"default_options\": [\n \"--style=monokai\",\n \"--verify=no\",\n \"--timeout=30\"\n ]\n}\n```\n\n**常用配置选项**:\n\n```json\n{\n \"default_options\": [\n \"--style=solarized\",\n \"--timeout=60\",\n \"--follow\"\n ]\n}\n```\n\n### 可用主题\n\n```bash\n# 查看所有可用主题\nhttp --style=UNKNOWN https://httpie.io 2>&1 | head -20\n\n# 常用主题：monokai, solarized, zenburn, vs, friendly\nhttp --style=monokai https://api.example.com/data\n```\n\n---\n\n## 十一、与 curl 互转\n\n### HTTPie 转 curl\n\n```bash\n# 生成等效的 curl 命令\nhttp --print=R https://api.example.com/users \"Authorization: Bearer token123\"\n\n# 或安装 httpie-to-curl 插件\npip3 install httpie-to-curl\n```\n\n### curl 转 HTTPie\n\n常用 curl 参数对应关系：\n\n| curl | HTTPie | 说明 |\n|-----|-------|-----|\n| `curl -X POST` | `http POST` | HTTP 方法 |\n| `curl -H \"Key: Val\"` | `http \"Key: Val\"` | 请求头 |\n| `curl -d '{\"k\":\"v\"}'` | `http k=v` | JSON 请求体 |\n| `curl -u user:pass` | `http -a user:pass` | Basic 认证 |\n| `curl -k` | `http --verify=no` | 跳过 SSL 验证 |\n| `curl -L` | `http --follow` | 跟随重定向 |\n| `curl -o file` | `http -d -o file` | 保存到文件 |\n| `curl -v` | `http -v` | 详细输出 |\n\n---\n\n## 完成确认\n\n### 检查清单\n\n- [ ] 使用 Session 完成登录并进行后续认证请求\n- [ ] 成功上传文件（multipart/form-data）\n- [ ] 配置代理并通过代理发送请求\n- [ ] 在 Shell 脚本中集成 HTTPie 并处理退出码\n- [ ] 创建配置文件设置默认选项\n\n### 参考资源\n\n- 官方文档: https://httpie.io/docs/cli\n- GitHub: https://github.com/httpie/cli\n- 常见问题: [troubleshooting.md](../troubleshooting.md)\n\nFile v0.1.1:skill-card.md\n\n## Description:\n\nHTTPie helps agents install and use the HTTPie command-line client to build, execute, debug, and troubleshoot HTTP requests.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cn-big-cabbage](https://clawhub.ai/user/cn-big-cabbage)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and API practitioners use this skill to construct HTTPie commands for REST API debugging, authentication, file transfer, formatted response inspection, session handling, and troubleshooting.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill may propose installation commands or mutable binary downloads.\n\nMitigation: Review commands before execution, prefer user-scoped or pinned installations, and avoid curl-to-shell patterns.\n\nRisk: HTTP requests can expose credentials, tokens, cookies, or sensitive request data.\n\nMitigation: Do not place real secrets directly in commands; use safer secret handling and redact tokens from shared output.\n\nRisk: Persistent HTTPie sessions can store authentication material on disk.\n\nMitigation: Treat HTTPie session files as sensitive credentials and avoid storing production secrets in reusable sessions.\n\nRisk: Disabling TLS verification can hide certificate or interception problems.\n\nMitigation: Keep TLS verification enabled except in isolated testing and prefer explicit CA configuration for trusted internal services.\n\n## Reference(s):\n\n- [HTTPie homepage](https://httpie.io)\n- [HTTPie CLI documentation](https://httpie.io/docs/cli)\n- [ClawHub skill page](https://clawhub.ai/cn-big-cabbage/skills/httpie)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with HTTPie command examples and troubleshooting steps]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May propose network requests, installation commands, authentication headers, session usage, and file upload or download commands for user review.]\n\n## Skill Version(s):\n\n0.1.1 (source: server release evidence and frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.1.1:troubleshooting.md\n\n# 常见问题与解决方案\n\n---\n\n## 问题分类说明\n\n**简单问题（1-2 步排查）**: 命令语法错误、环境配置问题等 \n**中等问题（3-5 步排查）**: 连接失败、SSL 错误、认证问题等 \n**复杂问题（5-10 步排查）**: 代理配置、会话异常、脚本集成问题等\n\n---\n\n## 安装问题\n\n### 1. 安装后 `http` 命令找不到【简单问题】\n\n**问题描述**: 执行 `pip3 install httpie` 成功，但运行 `http` 提示 `command not found`\n\n**排查步骤**:\n\n```bash\n# 检查 httpie 是否已安装\npip3 show httpie\n\n# 查找 http 可执行文件位置\npython3 -m site --user-base\n# 通常输出 /home/username/.local 或 /Users/username/Library/Python/3.x\n```\n\n**常见原因**:\n- pip 用户安装目录不在 PATH 中 (60%)\n- 多个 Python 版本冲突 (30%)\n- 使用 sudo pip 安装但非 root 用户 (10%)\n\n**解决方案**:\n\n**方案 A（推荐）**: 添加用户 bin 目录到 PATH\n\n```bash\n# 查看用户安装基础路径\npython3 -m site --user-base\n\n# 将 bin 目录加入 PATH（添加到 ~/.bashrc 或 ~/.zshrc）\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc\nsource ~/.zshrc\n\n# 验证\nhttp --version\n```\n\n**方案 B**: 使用 pipx（推荐长期方案）\n\n```bash\npip3 install pipx\npipx ensurepath\npipx install httpie\n```\n\n**方案 C**: 直接调用 Python 模块\n\n```bash\npython3 -m httpie GET https://httpie.io/hello\n```\n\n---\n\n### 2. pip 安装时提示权限错误【简单问题】\n\n**问题描述**: `pip install httpie` 报 `PermissionError` 或 `Access is denied`\n\n**排查步骤**:\n\n```bash\n# 检查当前用户\nwhoami\n\n# 检查 Python 安装位置\nwhich python3\n```\n\n**解决方案**:\n\n**方案 A（推荐）**: 用户级别安装\n\n```bash\npip3 install --user httpie\n```\n\n**方案 B**: 使用 pipx 隔离安装\n\n```bash\npip3 install --user pipx\npipx install httpie\n```\n\n**方案 C（不推荐）**: 使用 sudo（可能破坏系统 Python）\n\n```bash\n# 仅在确实需要系统级安装时使用\nsudo pip3 install httpie\n```\n\n---\n\n## 连接问题\n\n### 3. 连接超时或请求挂起【中等问题】\n\n**问题描述**: 发送请求后长时间无响应或提示 `Connection timed out`\n\n**排查步骤**:\n\n```bash\n# 1. 检查网络连通性\nping api.example.com\n\n# 2. 检查 DNS 解析\nnslookup api.example.com\n\n# 3. 尝试 curl 是否可以连接\ncurl -v --max-time 5 https://api.example.com/health\n\n# 4. 检查端口是否开放\ntelnet api.example.com 443\n```\n\n**常见原因**:\n- 网络不通或 DNS 解析失败 (40%)\n- 防火墙或安全组阻断 (30%)\n- 服务端响应慢（需要更长超时时间） (20%)\n- 需要使用代理 (10%)\n\n**解决方案**:\n\n**方案 A**: 设置合适的超时时间\n\n```bash\nhttp --timeout=30 https://api.example.com/data\n```\n\n**方案 B**: 通过代理访问\n\n```bash\nhttp --proxy=http:http://proxy.example.com:8080 https://api.example.com/data\n```\n\n**方案 C**: 检查并刷新 DNS 缓存\n\n```bash\n# macOS\nsudo dscacheutil -flushcache\n\n# Linux\nsudo systemd-resolve --flush-caches\n```\n\n---\n\n### 4. SSL/TLS 证书验证失败【中等问题】\n\n**问题描述**: 提示 `SSL: CERTIFICATE_VERIFY_FAILED` 或 `certificate verify failed`\n\n**排查步骤**:\n\n```bash\n# 1. 检查服务器证书\nopenssl s_client -connect api.example.com:443\n\n# 2. 检查证书有效期\necho | openssl s_client -connect api.example.com:443 2>/dev/null | openssl x509 -noout -dates\n\n# 3. 确认服务器主机名\necho | openssl s_client -connect api.example.com:443 2>/dev/null | openssl x509 -noout -subject\n```\n\n**常见原因**:\n- 使用自签名证书 (40%)\n- 证书已过期 (30%)\n- 证书与主机名不匹配 (20%)\n- 系统 CA 证书库过旧 (10%)\n\n**解决方案**:\n\n**方案 A（开发/测试环境）**: 跳过 SSL 验证\n\n```bash\nhttp --verify=no https://self-signed.dev.example.com/api\n```\n\n**方案 B（生产环境）**: 指定自定义 CA 证书\n\n```bash\n# 使用自定义 CA 证书文件\nhttp --verify=/path/to/ca-cert.pem https://internal.example.com/api\n```\n\n**方案 C**: 更新系统 CA 证书\n\n```bash\n# Ubuntu/Debian\nsudo apt update && sudo apt install ca-certificates\nsudo update-ca-certificates\n\n# macOS\nbrew install ca-certificates\n```\n\n---\n\n### 5. 响应乱码或编码错误【简单问题】\n\n**问题描述**: 响应中的中文或特殊字符显示为乱码\n\n**排查步骤**:\n\n```bash\n# 检查响应的 Content-Type 和 charset\nhttp --headers https://api.example.com/data\n\n# 查看原始响应字节\nhttp --pretty=none https://api.example.com/data | hexdump | head\n```\n\n**常见原因**:\n- 终端不支持 UTF-8 (50%)\n- 服务端未正确设置 charset (30%)\n- HTTPie 版本较旧 (20%)\n\n**解决方案**:\n\n**方案 A**: 设置终端编码\n\n```bash\n# 确保终端使用 UTF-8\nexport LANG=en_US.UTF-8\nexport LC_ALL=en_US.UTF-8\n\n# 重新执行请求\nhttp https://api.example.com/data\n```\n\n**方案 B**: 使用原始输出模式\n\n```bash\n# 禁用格式化，查看原始响应\nhttp --pretty=none https://api.example.com/data\n```\n\n---\n\n## 认证问题\n\n### 6. Basic 认证失败，返回 401【中等问题】\n\n**问题描述**: 使用 `-a username:password` 认证但服务器返回 401 Unauthorized\n\n**排查步骤**:\n\n```bash\n# 1. 确认用户名密码格式\nhttp -v -a username:password https://api.example.com/protected\n\n# 2. 检查服务器要求的认证类型\n# 在响应头中查找 WWW-Authenticate\nhttp https://api.example.com/protected\n\n# 3. 测试 Digest 认证\nhttp --auth-type=digest -a username:password https://api.example.com/protected\n```\n\n**常见原因**:\n- 密码包含特殊字符未转义 (40%)\n- 服务器使用 Digest 认证而非 Basic (30%)\n- 用户名或密码错误 (20%)\n- 认证令牌已过期 (10%)\n\n**解决方案**:\n\n**方案 A**: 密码包含特殊字符时用引号包裹\n\n```bash\n# 密码含有 @:/ 等特殊字符时\nhttp -a \"username:p@ssw0rd#123\" https://api.example.com/protected\n\n# 或使用环境变量避免转义问题\nexport API_PASS=\"p@ssw0rd#123\"\nhttp -a \"username:$API_PASS\" https://api.example.com/protected\n```\n\n**方案 B**: 切换为 Digest 认证\n\n```bash\nhttp --auth-type=digest -a username:password https://api.example.com/protected\n```\n\n**方案 C**: 使用 Bearer Token 替代\n\n```bash\nhttp https://api.example.com/protected \"Authorization: Bearer \"\n```\n\n---\n\n### 7. Bearer Token 自动刷新问题【复杂问题】\n\n**问题描述**: 使用 Session 时 Token 过期，后续请求返回 401\n\n**排查步骤**:\n\n```bash\n# 1. 检查 Session 文件中保存的 Token 是否过期\ncat ~/.config/httpie/sessions/api.example.com/my-session.json\n\n# 2. 解码 JWT Token 检查过期时间\necho \"\" | cut -d. -f2 | base64 --decode 2>/dev/null\n\n# 3. 重新登录获取新 Token\nhttp --session=my-session POST https://api.example.com/auth/login \\\n username=\"admin\" password=\"secret\"\n```\n\n**解决方案**:\n\n**方案 A**: 手动更新 Session 中的 Token\n\n```bash\n# 获取新 Token\nNEW_TOKEN=$(http --body POST https://api.example.com/auth/refresh \\\n refresh_token=\"\" | python3 -c \"import sys,json; print(json.load(sys.stdin)['access_token'])\")\n\n# 后续请求使用新 Token\nhttp --session=my-session https://api.example.com/profile \\\n \"Authorization: Bearer $NEW_TOKEN\"\n```\n\n**方案 B**: 在脚本中封装认证逻辑\n\n```bash\n#!/bin/bash\nTOKEN=$(http --body POST https://api.example.com/login \\\n username=\"$API_USER\" password=\"$API_PASS\" | \\\n python3 -c \"import sys,json; print(json.load(sys.stdin)['token'])\")\n\nhttp https://api.example.com/data \"Authorization: Bearer $TOKEN\"\n```\n\n---\n\n## 请求构建问题\n\n### 8. JSON 数据类型错误【简单问题】\n\n**问题描述**: 发送 POST 请求时，数字/布尔值被当做字符串处理\n\n**问题示例**:\n\n```bash\n# 错误：age 被发送为字符串 \"25\"，而非数字 25\nhttp POST https://api.example.com/users name=\"张三\" age=\"25\"\n\n# 服务器报错：age must be a number\n```\n\n**解决方案**:\n\n```bash\n# 正确：使用 := 语法发送非字符串类型\nhttp POST https://api.example.com/users \\\n name=\"张三\" \\ # 字符串：用 =\n age:=25 \\ # 数字：用 :=\n active:=true \\ # 布尔值：用 :=\n scores:='[1,2,3]' \\ # 数组：用 :=\n meta:='{\"key\":\"val\"}' # 嵌套对象：用 :=\n```\n\n**类型对应规则**:\n- 字符串 → `field=\"value\"`\n- 数字 → `field:=25`\n- 布尔 → `field:=true` 或 `field:=false`\n- null → `field:=null`\n- 数组 → `field:='[1,2,3]'`\n- 对象 → `field:='{\"k\":\"v\"}'`\n\n---\n\n### 9. 发送嵌套 JSON 对象【中等问题】\n\n**问题描述**: 需要发送多层嵌套的 JSON 结构，HTTPie 简单语法无法表达\n\n**问题示例**:\n\n```json\n{\n \"user\": {\n \"name\": \"张三\",\n \"address\": {\n \"city\": \"上海\",\n \"zip\": \"200000\"\n }\n }\n}\n```\n\n**解决方案**:\n\n**方案 A（推荐）**: 通过管道传入 JSON\n\n```bash\necho '{\"user\": {\"name\": \"张三\", \"address\": {\"city\": \"上海\", \"zip\": \"200000\"}}}' \\\n | http POST https://api.example.com/users\n```\n\n**方案 B**: 从 JSON 文件读取\n\n```bash\n# 创建 payload.json\ncat payload.json | http POST https://api.example.com/users\n\n# 或直接重定向\nhttp POST https://api.example.com/users < payload.json\n```\n\n**方案 C**: 使用 `--json` 强制 JSON 模式 + `:=@` 文件语法\n\n```bash\nhttp POST https://api.example.com/users body:=@payload.json\n```\n\n---\n\n## 输出与调试问题\n\n### 10. 响应不显示或显示不完整【简单问题】\n\n**问题描述**: 执行请求后没有任何输出，或只看到部分内容\n\n**排查步骤**:\n\n```bash\n# 1. 检查是否使用了 --quiet 模式\nhttp --quiet GET https://httpie.io/hello # 无输出是正常的\n\n# 2. 检查响应状态码\nhttp --check-status https://api.example.com/data\necho \"退出码: $?\"\n\n# 3. 强制显示所有内容\nhttp --print=HhBb https://api.example.com/data\n```\n\n**解决方案**:\n\n```bash\n# 显示完整请求和响应（调试首选）\nhttp --verbose https://api.example.com/data\n\n# 只显示响应体\nhttp --body https://api.example.com/data\n\n# 只显示响应头\nhttp --headers https://api.example.com/data\n\n# 显示所有（请求头+请求体+响应头+响应体）\nhttp --print=HhBb https://api.example.com/data\n```\n\n---\n\n### 11. 在脚本中使用 HTTPie 时返回值处理【复杂问题】\n\n**问题描述**: 在 Shell 脚本中无法正确判断请求是否成功\n\n**排查步骤**:\n\n```bash\n# 1. 检查退出码含义\nhttp https://api.example.com/data\necho \"退出码: $?\"\n# 0 = 成功（2xx）\n# 1 = 连接错误\n# 2 = 超时\n# 3 = 未预期的 HTTP 3xx\n# 4 = HTTP 4xx 错误\n# 5 = HTTP 5xx 错误\n```\n\n**解决方案**:\n\n**方案 A**: 使用 `--check-status` 让非 2xx 返回非零退出码\n\n```bash\n#!/bin/bash\nset -e # 任何命令失败即退出\n\n# 使用 --check-status 确保非 2xx 状态也触发错误\nif http --check-status --quiet GET https://api.example.com/health; then\n echo \"健康检查通过\"\nelse\n echo \"健康检查失败，退出码: $?\"\n exit 1\nfi\n```\n\n**方案 B**: 捕获响应并检查状态\n\n```bash\n#!/bin/bash\n\n# 捕获响应体和状态码\nRESPONSE=$(http --print=b GET https://api.example.com/status)\nSTATUS=$(http --print=h GET https://api.example.com/status | grep \"^HTTP\" | awk '{print $2}')\n\nif [ \"$STATUS\" = \"200\" ]; then\n echo \"成功: $RESPONSE\"\nelse\n echo \"失败，状态码: $STATUS\"\nfi\n```\n\n---\n\n## 获取帮助\n\n### 诊断命令汇总\n\n```bash\n# 检查 HTTPie 版本\nhttp --version\n\n# 检查 Python 环境\npython3 -m pip show httpie\n\n# 查看完整帮助\nhttp --help\n\n# 离线模式预览请求（不发送）\nhttp --offline POST https://api.example.com/test name=\"debug\" age:=1\n\n# 详细调试模式\nhttp --verbose --all https://api.example.com/data\n```\n\n### 常用调试技巧\n\n```bash\n# 技巧 1: 用 httpbin.org 作为测试端点\nhttp POST https://httpbin.org/post name=\"test\" age:=25\n\n# 技巧 2: 用 --offline 验证命令语法\nhttp --offline PUT https://api.example.com/users/1 name=\"New Name\"\n\n# 技巧 3: 保存完整调试输出\nhttp --verbose https://api.example.com/data > debug.txt 2>&1\n\n# 技巧 4: 检查 Session 状态\ncat ~/.config/httpie/sessions/*/my-session.json\n\n# 技巧 5: 重置 Session\nrm ~/.config/httpie/sessions/api.example.com/my-session.json\n```\n\n### 参考资源\n\n- 官方文档: https://httpie.io/docs/cli\n- GitHub Issues: https://github.com/httpie/cli/issues\n- GitHub 讨论: https://github.com/httpie/cli/discussions\n- 官方社区: https://httpie.io/discord\n\n---\n\n**提示**: 遇到本文档未涵盖的问题，请先使用 `http --verbose` 查看完整的请求和响应详情，然后在 GitHub Issues 中搜索或提问\n\nArchive v0.1.0: 7 files, 18881 bytes\n\nFiles: guides/01-installation.md (5956b), guides/02-quickstart.md (7718b), guides/03-advanced-usage.md (10049b), skill-card.md (2508b), SKILL.md (4006b), troubleshooting.md (12572b), _meta.json (125b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: httpie\ndescription: HTTPie - 人性化的 HTTP 命令行客户端\nversion: 0.1.0\nmetadata:\n openclaw:\n requires:\n - httpie\n emoji: 🌐\n homepage: https://httpie.io\n---\n\n# HTTPie 人性化 HTTP 命令行客户端\n\n## 技能概述\n\n本技能帮助用户通过命令行发送 HTTP 请求，调试 API 接口，适用于以下场景：\n\n- **REST API 调试**: 发送 GET/POST/PUT/DELETE 等各类 HTTP 请求\n- **接口测试**: 快速验证 API 端点的请求与响应\n- **文件上传下载**: 通过命令行进行文件传输\n- **身份认证**: 支持 Basic、Bearer Token、Digest 等多种认证方式\n- **会话管理**: 跨请求保持 Cookie 与认证状态\n- **格式化输出**: 自动语法高亮显示 JSON、XML 响应体\n\n**主要特点**: 语法简洁、自动格式化、彩色输出、内置 JSON 支持、比 curl 更易读写\n\n## 使用流程\n\nAI 助手将引导你完成以下步骤：\n\n1. 安装 HTTPie（如未安装）\n2. 构建 HTTP 请求（方法、URL、请求头、请求体）\n3. 执行请求并查看格式化响应\n4. 根据响应调整请求参数\n5. 将成功的命令保存为可复用脚本\n\n## 关键章节导航\n\n- [安装指南](./guides/01-installation.md)\n- [快速开始](./guides/02-quickstart.md)\n- [高级用法](./guides/03-advanced-usage.md)\n- [常见问题](./troubleshooting.md)\n\n## AI 助手能力\n\n当你向 AI 描述请求需求时，AI 会：\n\n- 自动识别请求类型（GET/POST/PUT/PATCH/DELETE）\n- 根据描述构建正确的请求头和请求体\n- 执行请求命令并解析响应\n- 识别常见 HTTP 错误状态码并给出建议\n- 自动处理 JSON 数据序列化\n- 管理认证令牌和会话 Cookie\n- 将复杂请求转换为可读的 HTTPie 命令\n\n## 核心功能\n\n- 支持全部 HTTP 方法（GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS）\n- 自动 JSON 请求体序列化与响应格式化\n- 彩色语法高亮（请求头、响应头、响应体）\n- 内置多种认证方式（Basic、Digest、Bearer）\n- 持久化 Session 管理（跨请求 Cookie）\n- 文件上传与二进制下载支持\n- HTTPS 与 SSL 证书验证\n- 代理支持（HTTP/HTTPS/SOCKS）\n- 离线模式（仅打印请求不发送）\n- 与 curl 命令互转\n\n## 命令速查表\n\n### 基础请求\n\n```bash\n# GET 请求\nhttp GET https://api.example.com/users\n\n# 简写（默认 GET）\nhttp https://api.example.com/users\n\n# POST JSON（自动推断 Content-Type: application/json）\nhttp POST https://api.example.com/users name=\"张三\" age:=25\n\n# PUT 更新\nhttp PUT https://api.example.com/users/1 name=\"李四\"\n\n# PATCH 部分更新\nhttp PATCH https://api.example.com/users/1 email=\"li@example.com\"\n\n# DELETE 删除\nhttp DELETE https://api.example.com/users/1\n```\n\n### 请求参数与请求头\n\n```bash\n# URL 查询参数（== 语法）\nhttp https://api.example.com/search q==\"hello world\" page==2\n\n# 自定义请求头（: 语法）\nhttp https://api.example.com/users \"Authorization: Bearer mytoken123\"\n\n# 多个请求头\nhttp https://api.example.com/data \"X-API-Key: abc123\" \"Accept: application/json\"\n```\n\n### 认证\n\n```bash\n# Basic 认证\nhttp -a username:password https://api.example.com/protected\n\n# Bearer Token\nhttp https://api.example.com/me \"Authorization: Bearer \"\n\n# Digest 认证\nhttp --auth-type=digest -a user:pass https://api.example.com/secure\n```\n\n### 输出控制\n\n```bash\n# 仅显示响应体\nhttp --body https://api.example.com/users\n\n# 仅显示响应头\nhttp --headers https://api.example.com/users\n\n# 显示请求+响应（调试用）\nhttp --verbose https://api.example.com/users\n\n# 安静模式（无输出，只看退出码）\nhttp --quiet https://api.example.com/health\n\n# 保存响应到文件\nhttp https://api.example.com/file.pdf > file.pdf\n```\n\n## 安装要求\n\n- Python 3.7+ 或直接使用独立二进制包\n- 无其他强制依赖\n\n## 许可证\n\nBSD-3-Clause License\n\n## 项目链接\n\n- GitHub: https://github.com/httpie/cli\n- 官网: https://httpie.io\n- 文档: https://httpie.io/docs/cli\n\nFile v0.1.0:_meta.json\n\n{\n \"ownerId\": \"kn7c5ry95ff7x22mt3fx6j0q3d81p8t3\",\n \"slug\": \"httpie\",\n \"version\": \"0.1.0\",\n \"publishedAt\": 1776214902210\n}\n\nFile v0.1.0:guides/01-installation.md\n\n# 安装指南\n\n**适用场景**: 首次使用 HTTPie，需要在本地环境中完成安装和配置\n\n---\n\n## 一、安装前准备\n\n### 目标\n\n确保系统具备运行 HTTPie 的基础环境，选择最适合的安装方式\n\n### 前置条件\n\n- 操作系统：macOS、Linux（Ubuntu/Debian/Fedora/Arch）、Windows 10+\n- 网络连接（下载安装包）\n- （pip 方式）Python 3.7 或更高版本\n\n### 检查现有环境\n\n**AI 执行说明**: AI 将自动检查当前系统环境，判断最佳安装路径\n\n```bash\n# 检查是否已安装 httpie\nhttp --version\n\n# 检查 Python 版本（如使用 pip 安装）\npython3 --version\n\n# 检查 pip\npip3 --version\n```\n\n**期望结果**:\n- 若 `http --version` 有输出，说明已安装，无需重复安装\n- Python 3.7+ 可用 pip 安装方式\n- pip 3.x 可正常使用\n\n---\n\n## 二、安装方式选择\n\nHTTPie 提供多种安装方式，根据你的系统和偏好选择：\n\n| 安装方式 | 适用系统 | 优点 |\n|--------|--------|-----|\n| Homebrew | macOS / Linux | 最简单，自动管理依赖 |\n| pip | 全平台（需要 Python） | 版本最新，适合 Python 开发者 |\n| pipx | 全平台（需要 Python） | 隔离安装，推荐方式 |\n| apt/yum/pacman | Linux | 系统包管理，稳定 |\n| 独立二进制 | macOS / Linux | 无需 Python 依赖 |\n| Windows Installer | Windows | 官方安装包，最方便 |\n\n---\n\n## 三、各平台安装步骤\n\n### 方法 1: macOS 使用 Homebrew（推荐）\n\n**AI 执行说明**: AI 可以直接执行 Homebrew 安装命令\n\n```bash\n# 安装 HTTPie\nbrew install httpie\n\n# 验证安装\nhttp --version\n```\n\n**期望输出**:\n```\nHTTPie 3.x.x\n```\n\n如果未安装 Homebrew，先执行：\n\n```bash\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n```\n\n---\n\n### 方法 2: 使用 pip 安装（全平台）\n\n**AI 执行说明**: AI 可以直接执行 pip 安装命令\n\n```bash\n# 使用 pip 安装（推荐使用 pip3）\npip3 install httpie\n\n# 验证安装\nhttp --version\n\n# 如果 pip3 不可用，尝试 pip\npip install httpie\n```\n\n**注意**: 部分系统中 `http` 命令可能与系统命令冲突，可以使用完整路径：\n\n```bash\n# 查找安装路径\nwhich http\npython3 -m httpie --version\n```\n\n---\n\n### 方法 3: 使用 pipx 安装（推荐，隔离环境）\n\npipx 会将 HTTPie 安装在独立的虚拟环境中，避免依赖冲突：\n\n```bash\n# 先安装 pipx（如未安装）\npip3 install pipx\npipx ensurepath\n\n# 安装 HTTPie\npipx install httpie\n\n# 验证安装\nhttp --version\n```\n\n---\n\n### 方法 4: Linux 系统包管理器\n\n**Ubuntu / Debian**:\n\n```bash\nsudo apt update\nsudo apt install httpie\n\nhttp --version\n```\n\n**Fedora / RHEL / CentOS**:\n\n```bash\nsudo dnf install httpie\n\n# 或者使用 yum（旧版系统）\nsudo yum install httpie\n```\n\n**Arch Linux**:\n\n```bash\nsudo pacman -S httpie\n```\n\n**Alpine Linux**:\n\n```bash\napk add httpie\n```\n\n---\n\n### 方法 5: Windows 安装\n\n**方式 A - pip（推荐）**:\n\n```powershell\n# 在 PowerShell 或 CMD 中执行\npip install httpie\n\n# 验证\nhttp --version\n```\n\n**方式 B - Chocolatey**:\n\n```powershell\nchoco install httpie\n```\n\n**方式 C - Scoop**:\n\n```powershell\nscoop install httpie\n```\n\n---\n\n### 方法 6: 独立二进制安装（无需 Python）\n\nHTTPie 提供预编译的独立二进制文件，无需 Python 环境：\n\n```bash\n# macOS (Apple Silicon)\ncurl -SsL https://packages.httpie.io/mac/http.latest.arm64 -o /usr/local/bin/http\nchmod +x /usr/local/bin/http\n\n# macOS (Intel)\ncurl -SsL https://packages.httpie.io/mac/http.latest.x86_64 -o /usr/local/bin/http\nchmod +x /usr/local/bin/http\n\n# Linux (x86_64)\ncurl -SsL https://packages.httpie.io/linux/http.latest.x86_64 -o /usr/local/bin/http\nchmod +x /usr/local/bin/http\n```\n\n---\n\n## 四、验证安装\n\n**AI 执行说明**: AI 将验证安装是否成功并进行简单测试\n\n```bash\n# 检查版本\nhttp --version\n\n# 发送一个测试请求（HTTPie 官方测试端点）\nhttp GET https://httpie.io/hello\n```\n\n**期望输出（版本检查）**:\n```\nHTTPie 3.x.x\n```\n\n**期望输出（测试请求）**:\n```\nHTTP/1.1 200 OK\nContent-Type: application/json\n...\n\n{\n \"ahoy\": [\n \"Hello, World! 👋\"\n ],\n ...\n}\n```\n\n**成功标志**:\n- HTTPie 版本信息正确显示\n- 测试请求返回 200 状态码\n- 响应体 JSON 格式化输出（有缩进和高亮）\n\n---\n\n## 五、升级 HTTPie\n\n```bash\n# pip 升级\npip3 install --upgrade httpie\n\n# Homebrew 升级\nbrew upgrade httpie\n\n# pipx 升级\npipx upgrade httpie\n\n# 查看当前版本\nhttp --version\n```\n\n---\n\n## 六、卸载 HTTPie\n\n```bash\n# pip 卸载\npip3 uninstall httpie\n\n# Homebrew 卸载\nbrew uninstall httpie\n\n# pipx 卸载\npipx uninstall httpie\n```\n\n---\n\n## 七、常见安装问题\n\n### 问题 1: `http` 命令找不到\n\n**症状**: 安装后执行 `http` 提示 `command not found`\n\n**解决方案**:\n\n```bash\n# 检查 pip 安装位置\npython3 -m site --user-base\n\n# 将用户 bin 目录加入 PATH（添加到 ~/.zshrc 或 ~/.bashrc）\nexport PATH=\"$HOME/.local/bin:$PATH\"\n\n# 立即生效\nsource ~/.zshrc\n```\n\n### 问题 2: 权限不足\n\n**症状**: 安装时报 `Permission denied` 错误\n\n**解决方案**:\n\n```bash\n# 使用用户级安装（不需要 sudo）\npip3 install --user httpie\n\n# 或使用 pipx（推荐）\npip3 install pipx\npipx install httpie\n```\n\n### 问题 3: pip 网络超时\n\n**症状**: pip install 时网络连接失败或超时\n\n**解决方案**:\n\n```bash\n# 使用国内镜像\npip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple httpie\n\n# 或使用阿里云镜像\npip3 install -i https://mirrors.aliyun.com/pypi/simple/ httpie\n```\n\n---\n\n## 完成确认\n\n### 检查清单\n\n- [ ] HTTPie 已成功安装并可运行\n- [ ] `http --version` 显示正确版本号\n- [ ] 测试请求 `http GET https://httpie.io/hello` 返回 200\n- [ ] 响应体 JSON 已正确格式化和高亮显示\n\n### 下一步\n\n继续阅读 [快速开始](02-quickstart.md) 学习 HTTPie 的基本用法\n\nFile v0.1.0:guides/02-quickstart.md\n\n# 快速开始\n\n**适用场景**: 已安装 HTTPie，想快速学习基本用法发送 HTTP 请求\n\n---\n\n## 一、HTTPie 语法概览\n\n### 基本命令格式\n\n```\nhttp [选项] [方法] URL [请求项...]\n```\n\n| 部分 | 说明 | 示例 |\n|-----|-----|-----|\n| `选项` | 控制行为的标志 | `--verbose`, `--json`, `--follow` |\n| `方法` | HTTP 方法（可省略，默认 GET） | `GET`, `POST`, `PUT`, `DELETE` |\n| `URL` | 请求地址 | `https://api.example.com/users` |\n| `请求项` | 请求头、请求体、查询参数 | `name=\"张三\"`, `\"X-Token: abc\"` |\n\n### 请求项语法\n\nHTTPie 使用特殊符号区分不同类型的请求项：\n\n| 符号 | 类型 | 示例 |\n|-----|-----|-----|\n| `:` | 请求头 | `\"Content-Type: application/json\"` |\n| `==` | URL 查询参数 | `page==1` |\n| `=` | JSON 字符串字段 | `name=\"张三\"` |\n| `:=` | JSON 非字符串字段 | `age:=25`, `active:=true` |\n| `@` | 表单文件字段 | `file@photo.jpg` |\n| `=@` | JSON 文件内容（字符串） | `data=@content.txt` |\n| `:=@` | JSON 文件内容（解析） | `config:=@config.json` |\n\n---\n\n## 二、发送 GET 请求\n\n**AI 执行说明**: AI 可以直接执行以下命令并返回响应\n\n### 最简单的 GET 请求\n\n```bash\n# 发送 GET 请求（方法可省略）\nhttp https://httpbin.org/get\n\n# 显式指定方法\nhttp GET https://httpbin.org/get\n```\n\n**期望输出**（自动格式化 + 彩色高亮）:\n\n```\nHTTP/1.1 200 OK\nContent-Type: application/json\nDate: Mon, 01 Jan 2024 12:00:00 GMT\n...\n\n{\n \"args\": {},\n \"headers\": {\n \"Accept\": \"application/json, */*;q=0.5\",\n \"Host\": \"httpbin.org\",\n \"User-Agent\": \"HTTPie/3.x.x\"\n },\n \"url\": \"https://httpbin.org/get\"\n}\n```\n\n### 携带查询参数\n\n```bash\n# 单个查询参数（== 语法）\nhttp https://httpbin.org/get search==\"Hello World\" page==1\n\n# 等效的 URL 形式\nhttp \"https://httpbin.org/get?search=Hello+World&page=1\"\n```\n\n**AI 执行说明**: 推荐使用 `==` 语法，AI 会自动处理 URL 编码\n\n---\n\n## 三、发送 POST 请求\n\n### 发送 JSON 数据（自动推断）\n\n当请求项包含 `=` 或 `:=` 时，HTTPie 自动设置 `Content-Type: application/json`：\n\n```bash\n# 发送 JSON 对象\nhttp POST https://httpbin.org/post name=\"张三\" email=\"zhang@example.com\" age:=28\n\n# 等效的 JSON 内容：\n# {\"name\": \"张三\", \"email\": \"zhang@example.com\", \"age\": 28}\n```\n\n**注意**: 字符串用 `=`，数字/布尔/数组用 `:=`\n\n### 发送原始 JSON\n\n```bash\n# 使用管道传入原始 JSON\necho '{\"name\": \"李四\", \"roles\": [\"admin\", \"user\"]}' | http POST https://httpbin.org/post\n\n# 从文件读取 JSON\nhttp POST https://httpbin.org/post < data.json\n```\n\n### 发送表单数据\n\n使用 `--form` 或 `-f` 标志，Content-Type 变为 `application/x-www-form-urlencoded`：\n\n```bash\nhttp --form POST https://httpbin.org/post username=\"user1\" password=\"secret\"\n\n# 简写\nhttp -f POST https://httpbin.org/post username=\"user1\" password=\"secret\"\n```\n\n---\n\n## 四、自定义请求头\n\n**AI 执行说明**: AI 会根据 API 要求自动添加必要的请求头\n\n```bash\n# 添加自定义请求头（使用 : 语法）\nhttp https://api.example.com/users \"X-API-Key: abc123\" \"Accept: application/json\"\n\n# 发送带认证头的 POST 请求\nhttp POST https://api.example.com/data \\\n \"Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...\" \\\n \"Content-Type: application/json\" \\\n name=\"测试\"\n```\n\n---\n\n## 五、身份认证\n\n### Basic 认证\n\n```bash\n# -a 或 --auth 指定用户名:密码\nhttp -a admin:secret123 https://api.example.com/protected\n\n# 只指定用户名（会提示输入密码）\nhttp -a admin https://api.example.com/protected\n```\n\n### Bearer Token 认证\n\n```bash\n# 直接在请求头中传入 Token\nhttp https://api.example.com/me \"Authorization: Bearer my-access-token\"\n```\n\n### Digest 认证\n\n```bash\nhttp --auth-type=digest -a user:pass https://api.example.com/digest\n```\n\n---\n\n## 六、查看请求详情\n\n### 调试模式：显示请求和响应\n\n```bash\n# --verbose 显示完整的请求和响应（包含请求头）\nhttp --verbose GET https://httpbin.org/get\n\n# 简写 -v\nhttp -v GET https://httpbin.org/get\n```\n\n**期望输出**:\n\n```\nGET /get HTTP/1.1\nAccept: application/json, */*;q=0.5\nAccept-Encoding: gzip, deflate\nConnection: keep-alive\nHost: httpbin.org\nUser-Agent: HTTPie/3.x.x\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n...\n\n{\n ...\n}\n```\n\n### 离线模式：只打印请求不发送\n\n```bash\n# --offline 仅构建并打印请求，不实际发送\nhttp --offline POST https://api.example.com/users name=\"测试\" age:=20\n```\n\n**用途**: 在实际发送前检查请求格式是否正确\n\n---\n\n## 七、控制输出内容\n\n```bash\n# 只显示响应体（最常用）\nhttp --body https://httpbin.org/get\n# 简写\nhttp -b https://httpbin.org/get\n\n# 只显示响应头\nhttp --headers https://httpbin.org/get\n# 简写\nhttp -h https://httpbin.org/get\n\n# 同时显示请求头和响应头（不含响应体）\nhttp --print=Hh https://httpbin.org/get\n\n# 显示所有（请求头 + 请求体 + 响应头 + 响应体）\nhttp --print=HhBb https://httpbin.org/get\n```\n\n**`--print` 格式字符含义**:\n- `H` - 请求头\n- `B` - 请求体\n- `h` - 响应头\n- `b` - 响应体\n\n---\n\n## 八、处理 HTTPS\n\n```bash\n# HTTPie 默认验证 SSL 证书\nhttp https://api.example.com/secure\n\n# 跳过 SSL 验证（开发/测试环境，不推荐生产）\nhttp --verify=no https://self-signed.example.com/api\n\n# 使用自定义 CA 证书\nhttp --verify=/path/to/ca-bundle.crt https://internal.example.com/api\n\n# 使用客户端证书\nhttp --cert=/path/to/client.crt --cert-key=/path/to/client.key https://api.example.com\n```\n\n---\n\n## 九、实战示例\n\n### 示例 1: 查询用户列表\n\n```bash\n# 带分页和过滤的 GET 请求\nhttp https://jsonplaceholder.typicode.com/users\n```\n\n### 示例 2: 创建新资源\n\n```bash\n# POST 创建文章\nhttp POST https://jsonplaceholder.typicode.com/posts \\\n title=\"HTTPie 使用指南\" \\\n body=\"HTTPie 是一个人性化的 HTTP 客户端\" \\\n userId:=1\n```\n\n**期望响应**:\n```json\n{\n \"body\": \"HTTPie 是一个人性化的 HTTP 客户端\",\n \"id\": 101,\n \"title\": \"HTTPie 使用指南\",\n \"userId\": 1\n}\n```\n\n### 示例 3: 带认证的 API 请求\n\n```bash\n# 查询当前用户信息（Bearer Token）\nhttp https://api.github.com/user \"Authorization: Bearer ghp_xxxxx\"\n```\n\n### 示例 4: 下载文件\n\n```bash\n# 下载文件到当前目录（保留原始文件名）\nhttp --download https://example.com/image.png\n\n# 简写 -d\nhttp -d https://example.com/report.pdf\n\n# 指定保存路径\nhttp --download --output=/tmp/report.pdf https://example.com/report.pdf\n```\n\n---\n\n## 十、常用选项速查\n\n| 选项 | 简写 | 说明 |\n|-----|-----|-----|\n| `--verbose` | `-v` | 显示请求和响应的完整内容 |\n| `--headers` | `-h` | 只显示响应头 |\n| `--body` | `-b` | 只显示响应体 |\n| `--json` | `-j` | 强制 JSON 模式 |\n| `--form` | `-f` | 强制表单模式 |\n| `--download` | `-d` | 下载模式（保存到文件） |\n| `--auth` | `-a` | 身份认证 |\n| `--verify=no` | | 跳过 SSL 验证 |\n| `--follow` | | 跟随重定向 |\n| `--offline` | | 离线模式（不发送） |\n| `--quiet` | `-q` | 安静模式（无输出） |\n| `--timeout` | | 超时时间（秒） |\n\n---\n\n## 完成确认\n\n### 检查清单\n\n- [ ] 成功发送 GET 请求并看到格式化的 JSON 响应\n- [ ] 成功发送带 JSON 体的 POST 请求\n- [ ] 理解 `=`（字符串）和 `:=`（非字符串）的区别\n- [ ] 使用 `--verbose` 查看完整请求/响应\n- [ ] 使用 `--offline` 预览请求格式\n\n### 下一步\n\n继续阅读 [高级用法](03-advanced-usage.md) 学习会话管理、文件上传、代理设置等进阶功能\n\nFile v0.1.0:guides/03-advanced-usage.md\n\n# 高级用法\n\n**适用场景**: 已掌握 HTTPie 基础用法，需要使用会话管理、文件上传、代理、脚本集成等进阶功能\n\n---\n\n## 一、会话管理\n\nHTTPie 的 Session 功能可以在多个请求之间自动保持 Cookie、认证信息和请求头，非常适合需要登录状态的 API 测试。\n\n### 创建和使用具名 Session\n\n```bash\n# 第一次请求：登录并保存 Session\nhttp --session=my-api POST https://api.example.com/login \\\n username=\"admin\" password=\"secret\"\n\n# 后续请求：自动携带登录 Cookie\nhttp --session=my-api https://api.example.com/profile\n\n# Session 数据自动保存到 ~/.config/httpie/sessions/ 目录\n```\n\n**AI 执行说明**: AI 会在同一任务的多次请求中自动复用 Session，保持认证状态\n\n### 使用文件路径作为 Session\n\n```bash\n# 保存 Session 到指定文件\nhttp --session=/tmp/test-session.json POST https://api.example.com/login \\\n username=\"test\" password=\"123456\"\n\n# 从指定文件加载 Session\nhttp --session=/tmp/test-session.json https://api.example.com/dashboard\n```\n\n### 只读 Session（不修改 Session 文件）\n\n```bash\n# 使用 Session 但不更新它\nhttp --session-read-only=my-api https://api.example.com/data\n```\n\n### 查看 Session 文件内容\n\nSession 文件是 JSON 格式，可以直接查看：\n\n```bash\n# 查看保存的 Session 内容\ncat ~/.config/httpie/sessions/api.example.com/my-api.json\n```\n\nSession 文件结构示例：\n\n```json\n{\n \"__meta__\": {\n \"about\": \"HTTPie session file\"\n },\n \"auth\": {\n \"password\": null,\n \"type\": null,\n \"username\": null\n },\n \"cookies\": {\n \"session_id\": {\n \"expires\": null,\n \"path\": \"/\",\n \"secure\": false,\n \"value\": \"abc123xyz\"\n }\n },\n \"headers\": {}\n}\n```\n\n---\n\n## 二、文件上传\n\n### 单文件上传（multipart/form-data）\n\n```bash\n# 上传单个文件（@ 语法）\nhttp --form POST https://api.example.com/upload file@photo.jpg\n\n# 指定字段名\nhttp --form POST https://api.example.com/upload \\\n profile_picture@/path/to/avatar.png \\\n username=\"zhangsan\"\n```\n\n### 多文件上传\n\n```bash\n# 同时上传多个文件\nhttp --form POST https://api.example.com/upload \\\n file1@document.pdf \\\n file2@image.jpg \\\n description=\"批量上传测试\"\n```\n\n### 上传时指定 MIME 类型\n\n```bash\n# 指定文件的 Content-Type（格式：字段名@文件路径;type=MIME类型）\nhttp --form POST https://api.example.com/upload \\\n \"document@report.txt;type=text/plain\"\n```\n\n### 将文件内容作为 JSON 字段\n\n```bash\n# 将文件内容作为 JSON 字符串字段（=@ 语法）\nhttp POST https://api.example.com/data content=@message.txt\n\n# 将 JSON 文件内容解析后嵌入请求体（:=@ 语法）\nhttp POST https://api.example.com/config settings:=@config.json\n```\n\n---\n\n## 三、下载文件\n\n### 基本下载\n\n```bash\n# 下载文件（自动从 Content-Disposition 或 URL 推断文件名）\nhttp --download https://example.com/report.pdf\n\n# 简写\nhttp -d https://example.com/report.pdf\n\n# 指定保存文件名\nhttp --download --output=my-report.pdf https://example.com/report.pdf\n# 简写\nhttp -d -o my-report.pdf https://example.com/report.pdf\n```\n\n### 下载时显示进度条\n\n下载大文件时，HTTPie 会自动显示进度条：\n\n```bash\nhttp -d https://example.com/large-file.zip\n# 输出：Downloading 125.3 MB to \"large-file.zip\"\n# ████████████████████░░░░░░░░░░ 67% 84.0 MB/s 0:00:01\n```\n\n### 断点续传\n\n```bash\n# 从断点继续下载（如果服务器支持 Range 请求）\nhttp -d -c https://example.com/large-file.zip\n```\n\n---\n\n## 四、代理设置\n\n### 使用 HTTP/HTTPS 代理\n\n```bash\n# 指定 HTTP 代理\nhttp --proxy=http:http://proxy.example.com:8080 https://api.example.com/data\n\n# 指定 HTTPS 代理\nhttp --proxy=https:http://proxy.example.com:8080 https://api.example.com/data\n\n# 同时设置 HTTP 和 HTTPS 代理\nhttp \\\n --proxy=http:http://proxy.example.com:8080 \\\n --proxy=https:http://proxy.example.com:8080 \\\n https://api.example.com/data\n```\n\n### 使用 SOCKS 代理\n\n```bash\n# SOCKS5 代理（需要安装 requests[socks]）\npip3 install requests[socks]\n\nhttp --proxy=http:socks5://localhost:1080 https://api.example.com/data\nhttp --proxy=https:socks5://localhost:1080 https://api.example.com/data\n```\n\n### 通过环境变量设置代理\n\n```bash\n# 设置环境变量（对所有 HTTP 请求生效）\nexport HTTP_PROXY=http://proxy.example.com:8080\nexport HTTPS_PROXY=http://proxy.example.com:8080\n\n# 之后的 HTTPie 命令自动使用代理\nhttp https://api.example.com/data\n```\n\n---\n\n## 五、请求重定向与跟随\n\n```bash\n# 默认不跟随重定向，显示 301/302 响应\nhttp GET https://httpbin.org/redirect/3\n\n# 跟随重定向\nhttp --follow https://httpbin.org/redirect/3\n\n# 跟随重定向并查看所有中间请求\nhttp --follow --all https://httpbin.org/redirect/3\n\n# 限制最大重定向次数\nhttp --follow --max-redirects=5 https://httpbin.org/redirect/10\n```\n\n---\n\n## 六、超时控制\n\n```bash\n# 设置连接和读取超时（秒）\nhttp --timeout=10 https://api.example.com/slow-endpoint\n\n# 分别设置连接超时和读取超时（格式：连接超时,读取超时）\nhttp --timeout=2.5 https://api.example.com/data\n\n# 不设超时（谨慎使用）\nhttp --timeout=0 https://api.example.com/very-slow\n```\n\n---\n\n## 七、HTTPS 与证书\n\n### 使用自定义 CA 证书\n\n```bash\n# 使用 PEM 格式的 CA 证书\nhttp --verify=/etc/ssl/certs/ca-bundle.crt https://internal.example.com/api\n\n# 环境变量方式\nexport REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-bundle.crt\nhttp https://internal.example.com/api\n```\n\n### 客户端证书认证（mTLS）\n\n```bash\n# 使用客户端证书（cert 和 key 分开存储）\nhttp --cert=client.crt --cert-key=client.key https://api.example.com/mtls\n\n# 证书和私钥合并在一个 PEM 文件中\nhttp --cert=client.pem https://api.example.com/mtls\n```\n\n### 跳过证书验证（仅开发环境）\n\n```bash\n# 不验证服务器证书（有安全风险，仅用于开发测试）\nhttp --verify=no https://self-signed.dev.example.com/api\n```\n\n---\n\n## 八、输出格式化与着色\n\n### 控制格式化\n\n```bash\n# 强制格式化输出（即使重定向到文件）\nhttp --pretty=all https://api.example.com/data > output.txt\n\n# 仅着色不格式化\nhttp --pretty=colors https://api.example.com/data\n\n# 仅格式化不着色\nhttp --pretty=format https://api.example.com/data\n\n# 无格式化无着色（原始输出）\nhttp --pretty=none https://api.example.com/data\n```\n\n### 输出到文件（保留格式化）\n\n```bash\n# 响应体保存到文件，控制台显示元信息\nhttp --print=b https://api.example.com/data > response.json\n\n# 调试时保存完整响应\nhttp --verbose https://api.example.com/data > full-response.txt 2>&1\n```\n\n---\n\n## 九、与脚本集成\n\n### 在 Shell 脚本中使用\n\n```bash\n#!/bin/bash\n\n# 获取 Token\nTOKEN=$(http --body POST https://api.example.com/auth \\\n username=\"admin\" password=\"secret\" | python3 -c \"import sys,json; print(json.load(sys.stdin)['token'])\")\n\n# 使用 Token 请求数据\nhttp https://api.example.com/users \"Authorization: Bearer $TOKEN\"\n```\n\n### 检查 HTTP 状态码\n\n```bash\n# HTTPie 退出码：2xx 为 0，其他为非 0\nif http --check-status --quiet https://api.example.com/health; then\n echo \"服务正常\"\nelse\n echo \"服务异常\"\nfi\n\n# --check-status 在非 2xx 状态时返回非零退出码\n# 1: 网络错误\n# 2: 超时\n# 3: 意外 HTTP 3xx（不跟随重定向时）\n# 4: HTTP 4xx 客户端错误\n# 5: HTTP 5xx 服务端错误\n```\n\n### 批量请求\n\n```bash\n# 使用 for 循环批量请求\nfor id in 1 2 3 4 5; do\n echo \"--- 查询用户 $id ---\"\n http --body https://jsonplaceholder.typicode.com/users/$id\ndone\n\n# 从文件逐行读取 URL\nwhile read url; do\n http --check-status --quiet \"$url\" && echo \"OK: $url\" || echo \"FAIL: $url\"\ndone < urls.txt\n```\n\n---\n\n## 十、配置文件\n\nHTTPie 支持通过配置文件设置默认选项，避免每次重复输入。\n\n### 配置文件位置\n\n- **macOS/Linux**: `~/.config/httpie/config.json`\n- **Windows**: `%APPDATA%\\httpie\\config.json`\n- **自定义**: 通过环境变量 `HTTPIE_CONFIG_DIR` 指定\n\n### 配置示例\n\n```json\n{\n \"default_options\": [\n \"--style=monokai\",\n \"--verify=no\",\n \"--timeout=30\"\n ]\n}\n```\n\n**常用配置选项**:\n\n```json\n{\n \"default_options\": [\n \"--style=solarized\",\n \"--timeout=60\",\n \"--follow\"\n ]\n}\n```\n\n### 可用主题\n\n```bash\n# 查看所有可用主题\nhttp --style=UNKNOWN https://httpie.io 2>&1 | head -20\n\n# 常用主题：monokai, solarized, zenburn, vs, friendly\nhttp --style=monokai https://api.example.com/data\n```\n\n---\n\n## 十一、与 curl 互转\n\n### HTTPie 转 curl\n\n```bash\n# 生成等效的 curl 命令\nhttp --print=R https://api.example.com/users \"Authorization: Bearer token123\"\n\n# 或安装 httpie-to-curl 插件\npip3 install httpie-to-curl\n```\n\n### curl 转 HTTPie\n\n常用 curl 参数对应关系：\n\n| curl | HTTPie | 说明 |\n|-----|-------|-----|\n| `curl -X POST` | `http POST` | HTTP 方法 |\n| `curl -H \"Key: Val\"` | `http \"Key: Val\"` | 请求头 |\n| `curl -d '{\"k\":\"v\"}'` | `http k=v` | JSON 请求体 |\n| `curl -u user:pass` | `http -a user:pass` | Basic 认证 |\n| `curl -k` | `http --verify=no` | 跳过 SSL 验证 |\n| `curl -L` | `http --follow` | 跟随重定向 |\n| `curl -o file` | `http -d -o file` | 保存到文件 |\n| `curl -v` | `http -v` | 详细输出 |\n\n---\n\n## 完成确认\n\n### 检查清单\n\n- [ ] 使用 Session 完成登录并进行后续认证请求\n- [ ] 成功上传文件（multipart/form-data）\n- [ ] 配置代理并通过代理发送请求\n- [ ] 在 Shell 脚本中集成 HTTPie 并处理退出码\n- [ ] 创建配置文件设置默认选项\n\n### 参考资源\n\n- 官方文档: https://httpie.io/docs/cli\n- GitHub: https://github.com/httpie/cli\n- 常见问题: [troubleshooting.md](../troubleshooting.md)\n\nFile v0.1.0:skill-card.md\n\n## Description:
\nHTTPie helps an agent build and run human-friendly HTTPie CLI requests for API debugging, testing, authentication, sessions, file transfers, and formatted response inspection.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[cn-big-cabbage](https://clawhub.ai/user/cn-big-cabbage)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and engineers use this skill to install HTTPie, construct HTTP requests, inspect responses, and troubleshoot API, authentication, session, proxy, upload, download, and TLS issues.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill can help an agent run live HTTPie commands against real services, including write or delete requests.
\nMitigation: Review every URL, method, header, body, file path, proxy, and output destination before execution; prefer test systems for validation.
\nRisk: Requests may involve OAuth tokens, API keys, passwords, cookies, or persisted sessions.
\nMitigation: Use least-privilege credentials, avoid inline secrets, avoid storing authenticated sessions in shared temporary paths, and redact sensitive values from logs.
\nRisk: Disabling TLS verification can hide certificate or endpoint problems.
\nMitigation: Do not use --verify=no except for temporary local testing; prefer valid certificates or a trusted custom CA file.
\n\n\n## Reference(s):
\n- [ClawHub HTTPie Skill](https://clawhub.ai/cn-big-cabbage/httpie)
\n- [HTTPie Homepage](https://httpie.io)
\n- [HTTPie CLI Documentation](https://httpie.io/docs/cli)
\n- [HTTPie CLI Project](https://github.com/httpie/cli)
\n\n\n## Skill Output:
\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration guidance]
\n**Output Format:** [Markdown guidance with inline shell command examples and HTTPie request snippets]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May include commands that send live HTTP requests, install packages, write files, upload or download data, and manage HTTPie sessions.]
\n\n## Skill Version(s):
\n0.1.0 (source: frontmatter and server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v0.1.0:troubleshooting.md\n\n# 常见问题与解决方案\n\n---\n\n## 问题分类说明\n\n**简单问题（1-2 步排查）**: 命令语法错误、环境配置问题等 \n**中等问题（3-5 步排查）**: 连接失败、SSL 错误、认证问题等 \n**复杂问题（5-10 步排查）**: 代理配置、会话异常、脚本集成问题等\n\n---\n\n## 安装问题\n\n### 1. 安装后 `http` 命令找不到【简单问题】\n\n**问题描述**: 执行 `pip3 install httpie` 成功，但运行 `http` 提示 `command not found`\n\n**排查步骤**:\n\n```bash\n# 检查 httpie 是否已安装\npip3 show httpie\n\n# 查找 http 可执行文件位置\npython3 -m site --user-base\n# 通常输出 /home/username/.local 或 /Users/username/Library/Python/3.x\n```\n\n**常见原因**:\n- pip 用户安装目录不在 PATH 中 (60%)\n- 多个 Python 版本冲突 (30%)\n- 使用 sudo pip 安装但非 root 用户 (10%)\n\n**解决方案**:\n\n**方案 A（推荐）**: 添加用户 bin 目录到 PATH\n\n```bash\n# 查看用户安装基础路径\npython3 -m site --user-base\n\n# 将 bin 目录加入 PATH（添加到 ~/.bashrc 或 ~/.zshrc）\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc\nsource ~/.zshrc\n\n# 验证\nhttp --version\n```\n\n**方案 B**: 使用 pipx（推荐长期方案）\n\n```bash\npip3 install pipx\npipx ensurepath\npipx install httpie\n```\n\n**方案 C**: 直接调用 Python 模块\n\n```bash\npython3 -m httpie GET https://httpie.io/hello\n```\n\n---\n\n### 2. pip 安装时提示权限错误【简单问题】\n\n**问题描述**: `pip install httpie` 报 `PermissionError` 或 `Access is denied`\n\n**排查步骤**:\n\n```bash\n# 检查当前用户\nwhoami\n\n# 检查 Python 安装位置\nwhich python3\n```\n\n**解决方案**:\n\n**方案 A（推荐）**: 用户级别安装\n\n```bash\npip3 install --user httpie\n```\n\n**方案 B**: 使用 pipx 隔离安装\n\n```bash\npip3 install --user pipx\npipx install httpie\n```\n\n**方案 C（不推荐）**: 使用 sudo（可能破坏系统 Python）\n\n```bash\n# 仅在确实需要系统级安装时使用\nsudo pip3 install httpie\n```\n\n---\n\n## 连接问题\n\n### 3. 连接超时或请求挂起【中等问题】\n\n**问题描述**: 发送请求后长时间无响应或提示 `Connection timed out`\n\n**排查步骤**:\n\n```bash\n# 1. 检查网络连通性\nping api.example.com\n\n# 2. 检查 DNS 解析\nnslookup api.example.com\n\n# 3. 尝试 curl 是否可以连接\ncurl -v --max-time 5 https://api.example.com/health\n\n# 4. 检查端口是否开放\ntelnet api.example.com 443\n```\n\n**常见原因**:\n- 网络不通或 DNS 解析失败 (40%)\n- 防火墙或安全组阻断 (30%)\n- 服务端响应慢（需要更长超时时间） (20%)\n- 需要使用代理 (10%)\n\n**解决方案**:\n\n**方案 A**: 设置合适的超时时间\n\n```bash\nhttp --timeout=30 https://api.example.com/data\n```\n\n**方案 B**: 通过代理访问\n\n```bash\nhttp --proxy=http:http://proxy.example.com:8080 https://api.example.com/data\n```\n\n**方案 C**: 检查并刷新 DNS 缓存\n\n```bash\n# macOS\nsudo dscacheutil -flushcache\n\n# Linux\nsudo systemd-resolve --flush-caches\n```\n\n---\n\n### 4. SSL/TLS 证书验证失败【中等问题】\n\n**问题描述**: 提示 `SSL: CERTIFICATE_VERIFY_FAILED` 或 `certificate verify failed`\n\n**排查步骤**:\n\n```bash\n# 1. 检查服务器证书\nopenssl s_client -connect api.example.com:443\n\n# 2. 检查证书有效期\necho | openssl s_client -connect api.example.com:443 2>/dev/null | openssl x509 -noout -dates\n\n# 3. 确认服务器主机名\necho | openssl s_client -connect api.example.com:443 2>/dev/null | openssl x509 -noout -subject\n```\n\n**常见原因**:\n- 使用自签名证书 (40%)\n- 证书已过期 (30%)\n- 证书与主机名不匹配 (20%)\n- 系统 CA 证书库过旧 (10%)\n\n**解决方案**:\n\n**方案 A（开发/测试环境）**: 跳过 SSL 验证\n\n```bash\nhttp --verify=no https://self-signed.dev.example.com/api\n```\n\n**方案 B（生产环境）**: 指定自定义 CA 证书\n\n```bash\n# 使用自定义 CA 证书文件\nhttp --verify=/path/to/ca-cert.pem https://internal.example.com/api\n```\n\n**方案 C**: 更新系统 CA 证书\n\n```bash\n# Ubuntu/Debian\nsudo apt update && sudo apt install ca-certificates\nsudo update-ca-certificates\n\n# macOS\nbrew install ca-certificates\n```\n\n---\n\n### 5. 响应乱码或编码错误【简单问题】\n\n**问题描述**: 响应中的中文或特殊字符显示为乱码\n\n**排查步骤**:\n\n```bash\n# 检查响应的 Content-Type 和 charset\nhttp --headers https://api.example.com/data\n\n# 查看原始响应字节\nhttp --pretty=none https://api.example.com/data | hexdump | head\n```\n\n**常见原因**:\n- 终端不支持 UTF-8 (50%)\n- 服务端未正确设置 charset (30%)\n- HTTPie 版本较旧 (20%)\n\n**解决方案**:\n\n**方案 A**: 设置终端编码\n\n```bash\n# 确保终端使用 UTF-8\nexport LANG=en_US.UTF-8\nexport LC_ALL=en_US.UTF-8\n\n# 重新执行请求\nhttp https://api.example.com/data\n```\n\n**方案 B**: 使用原始输出模式\n\n```bash\n# 禁用格式化，查看原始响应\nhttp --pretty=none https://api.example.com/data\n```\n\n---\n\n## 认证问题\n\n### 6. Basic 认证失败，返回 401【中等问题】\n\n**问题描述**: 使用 `-a username:password` 认证但服务器返回 401 Unauthorized\n\n**排查步骤**:\n\n```bash\n# 1. 确认用户名密码格式\nhttp -v -a username:password https://api.example.com/protected\n\n# 2. 检查服务器要求的认证类型\n# 在响应头中查找 WWW-Authenticate\nhttp https://api.example.com/protected\n\n# 3. 测试 Digest 认证\nhttp --auth-type=digest -a username:password https://api.example.com/protected\n```\n\n**常见原因**:\n- 密码包含特殊字符未转义 (40%)\n- 服务器使用 Digest 认证而非 Basic (30%)\n- 用户名或密码错误 (20%)\n- 认证令牌已过期 (10%)\n\n**解决方案**:\n\n**方案 A**: 密码包含特殊字符时用引号包裹\n\n```bash\n# 密码含有 @:/ 等特殊字符时\nhttp -a \"username:p@ssw0rd#123\" https://api.example.com/protected\n\n# 或使用环境变量避免转义问题\nexport API_PASS=\"p@ssw0rd#123\"\nhttp -a \"username:$API_PASS\" https://api.example.com/protected\n```\n\n**方案 B**: 切换为 Digest 认证\n\n```bash\nhttp --auth-type=digest -a username:password https://api.example.com/protected\n```\n\n**方案 C**: 使用 Bearer Token 替代\n\n```bash\nhttp https://api.example.com/protected \"Authorization: Bearer \"\n```\n\n---\n\n### 7. Bearer Token 自动刷新问题【复杂问题】\n\n**问题描述**: 使用 Session 时 Token 过期，后续请求返回 401\n\n**排查步骤**:\n\n```bash\n# 1. 检查 Session 文件中保存的 Token 是否过期\ncat ~/.config/httpie/sessions/api.example.com/my-session.json\n\n# 2. 解码 JWT Token 检查过期时间\necho \"\" | cut -d. -f2 | base64 --decode 2>/dev/null\n\n# 3. 重新登录获取新 Token\nhttp --session=my-session POST https://api.example.com/auth/login \\\n username=\"admin\" password=\"secret\"\n```\n\n**解决方案**:\n\n**方案 A**: 手动更新 Session 中的 Token\n\n```bash\n# 获取新 Token\nNEW_TOKEN=$(http --body POST https://api.example.com/auth/refresh \\\n refresh_token=\"\" | python3 -c \"import sys,json; print(json.load(sys.stdin)['access_token'])\")\n\n# 后续请求使用新 Token\nhttp --session=my-session https://api.example.com/profile \\\n \"Authorization: Bearer $NEW_TOKEN\"\n```\n\n**方案 B**: 在脚本中封装认证逻辑\n\n```bash\n#!/bin/bash\nTOKEN=$(http --body POST https://api.example.com/login \\\n username=\"$API_USER\" password=\"$API_PASS\" | \\\n python3 -c \"import sys,json; print(json.load(sys.stdin)['token'])\")\n\nhttp https://api.example.com/data \"Authorization: Bearer $TOKEN\"\n```\n\n---\n\n## 请求构建问题\n\n### 8. JSON 数据类型错误【简单问题】\n\n**问题描述**: 发送 POST 请求时，数字/布尔值被当做字符串处理\n\n**问题示例**:\n\n```bash\n# 错误：age 被发送为字符串 \"25\"，而非数字 25\nhttp POST https://api.example.com/users name=\"张三\" age=\"25\"\n\n# 服务器报错：age must be a number\n```\n\n**解决方案**:\n\n```bash\n# 正确：使用 := 语法发送非字符串类型\nhttp POST https://api.example.com/users \\\n name=\"张三\" \\ # 字符串：用 =\n age:=25 \\ # 数字：用 :=\n active:=true \\ # 布尔值：用 :=\n scores:='[1,2,3]' \\ # 数组：用 :=\n meta:='{\"key\":\"val\"}' # 嵌套对象：用 :=\n```\n\n**类型对应规则**:\n- 字符串 → `field=\"value\"`\n- 数字 → `field:=25`\n- 布尔 → `field:=true` 或 `field:=false`\n- null → `field:=null`\n- 数组 → `field:='[1,2,3]'`\n- 对象 → `field:='{\"k\":\"v\"}'`\n\n---\n\n### 9. 发送嵌套 JSON 对象【中等问题】\n\n**问题描述**: 需要发送多层嵌套的 JSON 结构，HTTPie 简单语法无法表达\n\n**问题示例**:\n\n```json\n{\n \"user\": {\n \"name\": \"张三\",\n \"address\": {\n \"city\": \"上海\",\n \"zip\": \"200000\"\n }\n }\n}\n```\n\n**解决方案**:\n\n**方案 A（推荐）**: 通过管道传入 JSON\n\n```bash\necho '{\"user\": {\"name\": \"张三\", \"address\": {\"city\": \"上海\", \"zip\": \"200000\"}}}' \\\n | http POST https://api.example.com/users\n```\n\n**方案 B**: 从 JSON 文件读取\n\n```bash\n# 创建 payload.json\ncat payload.json | http POST https://api.example.com/users\n\n# 或直接重定向\nhttp POST https://api.example.com/users < payload.json\n```\n\n**方案 C**: 使用 `--json` 强制 JSON 模式 + `:=@` 文件语法\n\n```bash\nhttp POST https://api.example.com/users body:=@payload.json\n```\n\n---\n\n## 输出与调试问题\n\n### 10. 响应不显示或显示不完整【简单问题】\n\n**问题描述**: 执行请求后没有任何输出，或只看到部分内容\n\n**排查步骤**:\n\n```bash\n# 1. 检查是否使用了 --quiet 模式\nhttp --quiet GET https://httpie.io/hello # 无输出是正常的\n\n# 2. 检查响应状态码\nhttp --check-status https://api.example.com/data\necho \"退出码: $?\"\n\n# 3. 强制显示所有内容\nhttp --print=HhBb https://api.example.com/data\n```\n\n**解决方案**:\n\n```bash\n# 显示完整请求和响应（调试首选）\nhttp --verbose https://api.example.com/data\n\n# 只显示响应体\nhttp --body https://api.example.com/data\n\n# 只显示响应头\nhttp --headers https://api.example.com/data\n\n# 显示所有（请求头+请求体+响应头+响应体）\nhttp --print=HhBb https://api.example.com/data\n```\n\n---\n\n### 11. 在脚本中使用 HTTPie 时返回值处理【复杂问题】\n\n**问题描述**: 在 Shell 脚本中无法正确判断请求是否成功\n\n**排查步骤**:\n\n```bash\n# 1. 检查退出码含义\nhttp https://api.example.com/data\necho \"退出码: $?\"\n# 0 = 成功（2xx）\n# 1 = 连接错误\n# 2 = 超时\n# 3 = 未预期的 HTTP 3xx\n# 4 = HTTP 4xx 错误\n# 5 = HTTP 5xx 错误\n```\n\n**解决方案**:\n\n**方案 A**: 使用 `--check-status` 让非 2xx 返回非零退出码\n\n```bash\n#!/bin/bash\nset -e # 任何命令失败即退出\n\n# 使用 --check-status 确保非 2xx 状态也触发错误\nif http --check-status --quiet GET https://api.example.com/health; then\n echo \"健康检查通过\"\nelse\n echo \"健康检查失败，退出码: $?\"\n exit 1\nfi\n```\n\n**方案 B**: 捕获响应并检查状态\n\n```bash\n#!/bin/bash\n\n# 捕获响应体和状态码\nRESPONSE=$(http --print=b GET https://api.example.com/status)\nSTATUS=$(http --print=h GET https://api.example.com/status | grep \"^HTTP\" | awk '{print $2}')\n\nif [ \"$STATUS\" = \"200\" ]; then\n echo \"成功: $RESPONSE\"\nelse\n echo \"失败，状态码: $STATUS\"\nfi\n```\n\n---\n\n## 获取帮助\n\n### 诊断命令汇总\n\n```bash\n# 检查 HTTPie 版本\nhttp --version\n\n# 检查 Python 环境\npython3 -m pip show httpie\n\n# 查看完整帮助\nhttp --help\n\n# 离线模式预览请求（不发送）\nhttp --offline POST https://api.example.com/test name=\"debug\" age:=1\n\n# 详细调试模式\nhttp --verbose --all https://api.example.com/data\n```\n\n### 常用调试技巧\n\n```bash\n# 技巧 1: 用 httpbin.org 作为测试端点\nhttp POST https://httpbin.org/post name=\"test\" age:=25\n\n# 技巧 2: 用 --offline 验证命令语法\nhttp --offline PUT https://api.example.com/users/1 name=\"New Name\"\n\n# 技巧 3: 保存完整调试输出\nhttp --verbose https://api.example.com/data > debug.txt 2>&1\n\n# 技巧 4: 检查 Session 状态\ncat ~/.config/httpie/sessions/*/my-session.json\n\n# 技巧 5: 重置 Session\nrm ~/.config/httpie/sessions/api.example.com/my-session.json\n```\n\n### 参考资源\n\n- 官方文档: https://httpie.io/docs/cli\n- GitHub Issues: https://github.com/httpie/cli/issues\n- GitHub 讨论: https://github.com/httpie/cli/discussions\n- 官方社区: https://httpie.io/discord\n\n---\n\n**提示**: 遇到本文档未涵盖的问题，请先使用 `http --verbose` 查看完整的请求和响应详情，然后在 GitHub Issues 中搜索或提问","readmeExcerpt":"Skill: Httpie Owner: cn-big-cabbage Summary: HTTPie - 人性化的 HTTP 命令行客户端 Tags: latest:0.1.1 Version history: v0.1.1 | 2026-06-16T06:50:52.712Z | auto - 元数据 now specifies required binary as http (was httpie). - Bumped version to 0.1.1. - Removed skill-card.md file. - No changes to user-facing commands or documentation content. v0.1.0 | 2026-04-15T01:01:42.210Z | user Initial release - HTTPie CLI skill for human-friendly","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# GET 请求\nhttp GET https://api.example.com/users\n\n# 简写（默认 GET）\nhttp https://api.example.com/users\n\n# POST JSON（自动推断 Content-Type: application/json）\nhttp POST https://api.example.com/users name=\"张三\" age:=25\n\n# PUT 更新\nhttp PUT https://api.example.com/users/1 name=\"李四\"\n\n# PATCH 部分更新\nhttp PATCH https://api.example.com/users/1 email=\"li@example.com\"\n\n# DELETE 删除\nhttp DELETE https://api.example.com/users/1"},{"language":"bash","snippet":"# URL 查询参数（== 语法）\nhttp https://api.example.com/search q==\"hello world\" page==2\n\n# 自定义请求头（: 语法）\nhttp https://api.example.com/users \"Authorization: Bearer mytoken123\"\n\n# 多个请求头\nhttp https://api.example.com/data \"X-API-Key: abc123\" \"Accept: application/json\""},{"language":"bash","snippet":"# Basic 认证\nhttp -a username:password https://api.example.com/protected\n\n# Bearer Token\nhttp https://api.example.com/me \"Authorization: Bearer \"\n\n# Digest 认证\nhttp --auth-type=digest -a user:pass https://api.example.com/secure"},{"language":"bash","snippet":"# 仅显示响应体\nhttp --body https://api.example.com/users\n\n# 仅显示响应头\nhttp --headers https://api.example.com/users\n\n# 显示请求+响应（调试用）\nhttp --verbose https://api.example.com/users\n\n# 安静模式（无输出，只看退出码）\nhttp --quiet https://api.example.com/health\n\n# 保存响应到文件\nhttp https://api.example.com/file.pdf > file.pdf"},{"language":"bash","snippet":"# 检查是否已安装 httpie\nhttp --version\n\n# 检查 Python 版本（如使用 pip 安装）\npython3 --version\n\n# 检查 pip\npip3 --version"},{"language":"bash","snippet":"# 安装 HTTPie\nbrew install httpie\n\n# 验证安装\nhttp --version"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: httpie\ndescription: HTTPie - 人性化的 HTTP 命令行客户端\nversion: 0.1.1\nmetadata:\n openclaw:\n requires:\n bins:\n - http\n emoji: 🌐\n homepage: https://httpie.io\n---\n\n# HTTPie 人性化 HTTP 命令行客户端\n\n## 技能概述\n\n本技能帮助用户通过命令行发送 HTTP 请求，调试 API 接口，适用于以下场景：\n\n- **REST API 调试**: 发送 GET/POST/PUT/DELETE 等各类 HTTP 请求\n- **接口测试**: 快速验证 API 端点的请求与响应\n- **文件上传下载**: 通过命令行进行文件传输\n- **身份认证**: 支持 Basic、Bearer Token、Digest 等多种认证方式\n- **会话管理**: 跨请求保持 Cookie 与认证状态\n- **格式化输出**: 自动语法高亮显示 JSON、XML 响应体\n\n**主要特点**: 语法简洁、自动格式化、彩色输出、内置 JSON 支持、比 curl 更易读写\n\n## 使用流程\n\nAI 助手将引导你完成以下步骤：\n\n1. 安装 HTTPie（如未安装）\n2. 构建 HTTP 请求（方法、URL、请求头、请求体）\n3. 执行请求并查看格式化响应\n4. 根据响应调整请求参数\n5. 将成功的命令保存为可复用脚本\n\n## 关键章节导航\n\n- [安装指南](./guides/01-installation.md)\n- [快速开始](./guides/02-quickstart.md)\n- [高级用法](./guides/03-advanced-usage.md)\n- [常见问题](./troubleshooting.md)\n\n## AI 助手能力\n\n当你向 AI 描述请求需求时，AI 会：\n\n- 自动识别请求类型（GET/POST/PUT/PATCH/DELETE）\n- 根据描述构建正确的请求头和请求体\n- 执行请求命令并解析响应\n- 识别常见 HTTP 错误状态码并给出建议\n- 自动处理 JSON 数据序列化\n- 管理认证令牌和会话 Cookie\n- 将复杂请求转换为可读的 HTTPie 命令\n\n## 核心功能\n\n- 支持全部 HTTP 方法（GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS）\n- 自动 JSON 请求体序列化与响应格式化\n- 彩色语法高亮（请求头、响应头、响应体）\n- 内置多种认证方式（Basic、Digest、Bearer）\n- 持久化 Session 管理（跨请求 Cookie）\n- 文件上传与二进制下载支持\n- HTTPS 与 SSL 证书验证\n- 代理支持（HTTP/HTTPS/SOCKS）\n- 离线模式（仅打印请求不发送）\n- 与 curl 命令互转\n\n## 命令速查表\n\n### 基础请求\n\n```bash\n# GET 请求\nhttp GET https://api.example.com/users\n\n# 简写（默认 GET）\nhttp https://api.example.com/users\n\n# POST JSON（自动推断 Content-Type: application/json）\nhttp POST https://api.example.com/users name=\"张三\" age:=25\n\n# PUT 更新\nhttp PUT https://api.example.com/users/1 name=\"李四\"\n\n# PATCH 部分更新\nhttp PATCH https://api.example.com/users/1 email=\"li@example.com\"\n\n# DELETE 删除\nhttp DELETE https://api.example.com/users/1\n```\n\n### 请求参数与请求头\n\n```bash\n# URL 查询参数（== 语法）\nhttp https://api.example.com/search q==\"hello world\" page==2\n\n# 自定义请求头（: 语法）\nhttp https://api.example.com/users \"Authorization: Bearer mytoken123\"\n\n# 多个请求头\nhttp https://api.example.com/data \"X-API-Key: abc123\" \"Accept: application/json\"\n```\n\n### 认证\n\n```bash\n# Basic 认证\nhttp -a username:password https://api.example.com/protected\n\n# Bearer Token\nhttp https://api.example.com/me \"Authorization: Bearer \"\n\n# Digest 认证\nhttp --auth-type=digest -a user:pass https://api.example.com/secure\n```\n\n### 输出控制\n\n```bash\n# 仅显示响应体\nhttp --body https://api.example.com/users\n\n# 仅显示响应头\nhttp --headers https://api.example.com/users\n\n# 显示请求+响应（调试用）\nhttp --verbose https://api.example.com/users\n\n# 安静模式（无输出，只看退出码）\nhttp --quiet https://api.example.com/health\n\n# 保存响应到文件\nhttp https://api.example.com/file.pdf > file.pdf\n```\n\n## 安装要求\n\n- Python 3.7+ 或直接使用独立二进制包\n- 无其他强制依赖\n\n## 许可证\n\nBSD-3-Clause License\n\n## 项目链接\n\n- GitHub: https://github.com/httpie/cli\n- 官网: https://httpie.io\n- 文档: https://httpie.io/docs/cli"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7c5ry95ff7x22mt3fx6j0q3d81p8t3\",\n \"slug\": \"httpie\",\n \"version\": \"0.1.1\",\n \"publishedAt\": 1781592652712\n}"},{"path":"guides/01-installation.md","content":"# 安装指南\n\n**适用场景**: 首次使用 HTTPie，需要在本地环境中完成安装和配置\n\n---\n\n## 一、安装前准备\n\n### 目标\n\n确保系统具备运行 HTTPie 的基础环境，选择最适合的安装方式\n\n### 前置条件\n\n- 操作系统：macOS、Linux（Ubuntu/Debian/Fedora/Arch）、Windows 10+\n- 网络连接（下载安装包）\n- （pip 方式）Python 3.7 或更高版本\n\n### 检查现有环境\n\n**AI 执行说明**: AI 将自动检查当前系统环境，判断最佳安装路径\n\n```bash\n# 检查是否已安装 httpie\nhttp --version\n\n# 检查 Python 版本（如使用 pip 安装）\npython3 --version\n\n# 检查 pip\npip3 --version\n```\n\n**期望结果**:\n- 若 `http --version` 有输出，说明已安装，无需重复安装\n- Python 3.7+ 可用 pip 安装方式\n- pip 3.x 可正常使用\n\n---\n\n## 二、安装方式选择\n\nHTTPie 提供多种安装方式，根据你的系统和偏好选择：\n\n| 安装方式 | 适用系统 | 优点 |\n|--------|--------|-----|\n| Homebrew | macOS / Linux | 最简单，自动管理依赖 |\n| pip | 全平台（需要 Python） | 版本最新，适合 Python 开发者 |\n| pipx | 全平台（需要 Python） | 隔离安装，推荐方式 |\n| apt/yum/pacman | Linux | 系统包管理，稳定 |\n| 独立二进制 | macOS / Linux | 无需 Python 依赖 |\n| Windows Installer | Windows | 官方安装包，最方便 |\n\n---\n\n## 三、各平台安装步骤\n\n### 方法 1: macOS 使用 Homebrew（推荐）\n\n**AI 执行说明**: AI 可以直接执行 Homebrew 安装命令\n\n```bash\n# 安装 HTTPie\nbrew install httpie\n\n# 验证安装\nhttp --version\n```\n\n**期望输出**:\n```\nHTTPie 3.x.x\n```\n\n如果未安装 Homebrew，先执行：\n\n```bash\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n```\n\n---\n\n### 方法 2: 使用 pip 安装（全平台）\n\n**AI 执行说明**: AI 可以直接执行 pip 安装命令\n\n```bash\n# 使用 pip 安装（推荐使用 pip3）\npip3 install httpie\n\n# 验证安装\nhttp --version\n\n# 如果 pip3 不可用，尝试 pip\npip install httpie\n```\n\n**注意**: 部分系统中 `http` 命令可能与系统命令冲突，可以使用完整路径：\n\n```bash\n# 查找安装路径\nwhich http\npython3 -m httpie --version\n```\n\n---\n\n### 方法 3: 使用 pipx 安装（推荐，隔离环境）\n\npipx 会将 HTTPie 安装在独立的虚拟环境中，避免依赖冲突：\n\n```bash\n# 先安装 pipx（如未安装）\npip3 install pipx\npipx ensurepath\n\n# 安装 HTTPie\npipx install httpie\n\n# 验证安装\nhttp --version\n```\n\n---\n\n### 方法 4: Linux 系统包管理器\n\n**Ubuntu / Debian**:\n\n```bash\nsudo apt update\nsudo apt install httpie\n\nhttp --version\n```\n\n**Fedora / RHEL / CentOS**:\n\n```bash\nsudo dnf install httpie\n\n# 或者使用 yum（旧版系统）\nsudo yum install httpie\n```\n\n**Arch Linux**:\n\n```bash\nsudo pacman -S httpie\n```\n\n**Alpine Linux**:\n\n```bash\napk add httpie\n```\n\n---\n\n### 方法 5: Windows 安装\n\n**方式 A - pip（推荐）**:\n\n```powershell\n# 在 PowerShell 或 CMD 中执行\npip install httpie\n\n# 验证\nhttp --version\n```\n\n**方式 B - Chocolatey**:\n\n```powershell\nchoco install httpie\n```\n\n**方式 C - Scoop**:\n\n```powershell\nscoop install httpie\n```\n\n---\n\n### 方法 6: 独立二进制安装（无需 Python）\n\nHTTPie 提供预编译的独立二进制文件，无需 Python 环境：\n\n```bash\n# macOS (Apple Silicon)\ncurl -SsL https://packages.httpie.io/mac/http.latest.arm64 -o /usr/local/bin/http\nchmod +x /usr/local/bin/http\n\n# macOS (Intel)\ncurl -SsL https://packages.httpie.io/mac/http.latest.x86_64 -o /usr/local/bin/http\nchmod +x /usr/local/bin/http\n\n# Linux (x86_64)\ncurl -SsL https://packages.httpie.io/linux/http.latest.x86_64 -o /usr/local/bin/http\nchmod +x /usr/local/bin/http\n```\n\n---\n\n## 四、验证安装\n\n**AI 执行说明**: AI 将验证安装是否成功并进行简单测试\n\n```bash\n# 检查版本\nhttp --version\n\n# 发送一个测试请求（HTTPie 官方测试端点）\nhttp GET https://httpie.io/hello\n```\n\n**期望输出（版本检查）**:\n```\nHTTPie 3.x.x\n```\n\n**期望输出（测试请求）**:\n```\nHTTP/1.1 200 OK\nContent-Type: application/json\n...\n\n{\n \"ahoy\": [\n \"Hello, World! 👋\"\n ],\n ...\n}\n```\n"},{"path":"guides/02-quickstart.md","content":"# 快速开始\n\n**适用场景**: 已安装 HTTPie，想快速学习基本用法发送 HTTP 请求\n\n---\n\n## 一、HTTPie 语法概览\n\n### 基本命令格式\n\n```\nhttp [选项] [方法] URL [请求项...]\n```\n\n| 部分 | 说明 | 示例 |\n|-----|-----|-----|\n| `选项` | 控制行为的标志 | `--verbose`, `--json`, `--follow` |\n| `方法` | HTTP 方法（可省略，默认 GET） | `GET`, `POST`, `PUT`, `DELETE` |\n| `URL` | 请求地址 | `https://api.example.com/users` |\n| `请求项` | 请求头、请求体、查询参数 | `name=\"张三\"`, `\"X-Token: abc\"` |\n\n### 请求项语法\n\nHTTPie 使用特殊符号区分不同类型的请求项：\n\n| 符号 | 类型 | 示例 |\n|-----|-----|-----|\n| `:` | 请求头 | `\"Content-Type: application/json\"` |\n| `==` | URL 查询参数 | `page==1` |\n| `=` | JSON 字符串字段 | `name=\"张三\"` |\n| `:=` | JSON 非字符串字段 | `age:=25`, `active:=true` |\n| `@` | 表单文件字段 | `file@photo.jpg` |\n| `=@` | JSON 文件内容（字符串） | `data=@content.txt` |\n| `:=@` | JSON 文件内容（解析） | `config:=@config.json` |\n\n---\n\n## 二、发送 GET 请求\n\n**AI 执行说明**: AI 可以直接执行以下命令并返回响应\n\n### 最简单的 GET 请求\n\n```bash\n# 发送 GET 请求（方法可省略）\nhttp https://httpbin.org/get\n\n# 显式指定方法\nhttp GET https://httpbin.org/get\n```\n\n**期望输出**（自动格式化 + 彩色高亮）:\n\n```\nHTTP/1.1 200 OK\nContent-Type: application/json\nDate: Mon, 01 Jan 2024 12:00:00 GMT\n...\n\n{\n \"args\": {},\n \"headers\": {\n \"Accept\": \"application/json, */*;q=0.5\",\n \"Host\": \"httpbin.org\",\n \"User-Agent\": \"HTTPie/3.x.x\"\n },\n \"url\": \"https://httpbin.org/get\"\n}\n```\n\n### 携带查询参数\n\n```bash\n# 单个查询参数（== 语法）\nhttp https://httpbin.org/get search==\"Hello World\" page==1\n\n# 等效的 URL 形式\nhttp \"https://httpbin.org/get?search=Hello+World&page=1\"\n```\n\n**AI 执行说明**: 推荐使用 `==` 语法，AI 会自动处理 URL 编码\n\n---\n\n## 三、发送 POST 请求\n\n### 发送 JSON 数据（自动推断）\n\n当请求项包含 `=` 或 `:=` 时，HTTPie 自动设置 `Content-Type: application/json`：\n\n```bash\n# 发送 JSON 对象\nhttp POST https://httpbin.org/post name=\"张三\" email=\"zhang@example.com\" age:=28\n\n# 等效的 JSON 内容：\n# {\"name\": \"张三\", \"email\": \"zhang@example.com\", \"age\": 28}\n```\n\n**注意**: 字符串用 `=`，数字/布尔/数组用 `:=`\n\n### 发送原始 JSON\n\n```bash\n# 使用管道传入原始 JSON\necho '{\"name\": \"李四\", \"roles\": [\"admin\", \"user\"]}' | http POST https://httpbin.org/post\n\n# 从文件读取 JSON\nhttp POST https://httpbin.org/post < data.json\n```\n\n### 发送表单数据\n\n使用 `--form` 或 `-f` 标志，Content-Type 变为 `application/x-www-form-urlencoded`：\n\n```bash\nhttp --form POST https://httpbin.org/post username=\"user1\" password=\"secret\"\n\n# 简写\nhttp -f POST https://httpbin.org/post username=\"user1\" password=\"secret\"\n```\n\n---\n\n## 四、自定义请求头\n\n**AI 执行说明**: AI 会根据 API 要求自动添加必要的请求头\n\n```bash\n# 添加自定义请求头（使用 : 语法）\nhttp https://api.example.com/users \"X-API-Key: abc123\" \"Accept: application/json\"\n\n# 发送带认证头的 POST 请求\nhttp POST https://api.example.com/data \\\n \"Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...\" \\\n \"Content-Type: application/json\" \\\n name=\"测试\"\n```\n\n---\n\n## 五、身份认证\n\n### Basic 认证\n\n```bash\n# -a 或 --auth 指定用户名:密码\nhttp -a admin:secret123 https://api.example.com/protected\n\n# 只指定用户名（会提示输入密码）\nhttp -a admin https://api.example.com/protected\n```\n\n### Bearer Token 认证\n\n```bash\n# 直接在请求头中传入 Token\nhttp https://api.example.com/me \"Authorization: Bearer my-access-token\"\n```\n\n### Digest 认证\n\n```bash\nhttp --auth-type=digest -a user:pass https://api.example.com/digest\n```\n\n---\n"},{"path":"guides/03-advanced-usage.md","content":"# 高级用法\n\n**适用场景**: 已掌握 HTTPie 基础用法，需要使用会话管理、文件上传、代理、脚本集成等进阶功能\n\n---\n\n## 一、会话管理\n\nHTTPie 的 Session 功能可以在多个请求之间自动保持 Cookie、认证信息和请求头，非常适合需要登录状态的 API 测试。\n\n### 创建和使用具名 Session\n\n```bash\n# 第一次请求：登录并保存 Session\nhttp --session=my-api POST https://api.example.com/login \\\n username=\"admin\" password=\"secret\"\n\n# 后续请求：自动携带登录 Cookie\nhttp --session=my-api https://api.example.com/profile\n\n# Session 数据自动保存到 ~/.config/httpie/sessions/ 目录\n```\n\n**AI 执行说明**: AI 会在同一任务的多次请求中自动复用 Session，保持认证状态\n\n### 使用文件路径作为 Session\n\n```bash\n# 保存 Session 到指定文件\nhttp --session=/tmp/test-session.json POST https://api.example.com/login \\\n username=\"test\" password=\"123456\"\n\n# 从指定文件加载 Session\nhttp --session=/tmp/test-session.json https://api.example.com/dashboard\n```\n\n### 只读 Session（不修改 Session 文件）\n\n```bash\n# 使用 Session 但不更新它\nhttp --session-read-only=my-api https://api.example.com/data\n```\n\n### 查看 Session 文件内容\n\nSession 文件是 JSON 格式，可以直接查看：\n\n```bash\n# 查看保存的 Session 内容\ncat ~/.config/httpie/sessions/api.example.com/my-api.json\n```\n\nSession 文件结构示例：\n\n```json\n{\n \"__meta__\": {\n \"about\": \"HTTPie session file\"\n },\n \"auth\": {\n \"password\": null,\n \"type\": null,\n \"username\": null\n },\n \"cookies\": {\n \"session_id\": {\n \"expires\": null,\n \"path\": \"/\",\n \"secure\": false,\n \"value\": \"abc123xyz\"\n }\n },\n \"headers\": {}\n}\n```\n\n---\n\n## 二、文件上传\n\n### 单文件上传（multipart/form-data）\n\n```bash\n# 上传单个文件（@ 语法）\nhttp --form POST https://api.example.com/upload file@photo.jpg\n\n# 指定字段名\nhttp --form POST https://api.example.com/upload \\\n profile_picture@/path/to/avatar.png \\\n username=\"zhangsan\"\n```\n\n### 多文件上传\n\n```bash\n# 同时上传多个文件\nhttp --form POST https://api.example.com/upload \\\n file1@document.pdf \\\n file2@image.jpg \\\n description=\"批量上传测试\"\n```\n\n### 上传时指定 MIME 类型\n\n```bash\n# 指定文件的 Content-Type（格式：字段名@文件路径;type=MIME类型）\nhttp --form POST https://api.example.com/upload \\\n \"document@report.txt;type=text/plain\"\n```\n\n### 将文件内容作为 JSON 字段\n\n```bash\n# 将文件内容作为 JSON 字符串字段（=@ 语法）\nhttp POST https://api.example.com/data content=@message.txt\n\n# 将 JSON 文件内容解析后嵌入请求体（:=@ 语法）\nhttp POST https://api.example.com/config settings:=@config.json\n```\n\n---\n\n## 三、下载文件\n\n### 基本下载\n\n```bash\n# 下载文件（自动从 Content-Disposition 或 URL 推断文件名）\nhttp --download https://example.com/report.pdf\n\n# 简写\nhttp -d https://example.com/report.pdf\n\n# 指定保存文件名\nhttp --download --output=my-report.pdf https://example.com/report.pdf\n# 简写\nhttp -d -o my-report.pdf https://example.com/report.pdf\n```\n\n### 下载时显示进度条\n\n下载大文件时，HTTPie 会自动显示进度条：\n\n```bash\nhttp -d https://example.com/large-file.zip\n# 输出：Downloading 125.3 MB to \"large-file.zip\"\n# ████████████████████░░░░░░░░░░ 67% 84.0 MB/s 0:00:01\n```\n\n### 断点续传\n\n```bash\n# 从断点继续下载（如果服务器支持 Range 请求）\nhttp -d -c https://example.com/large-file.zip\n```\n\n---\n\n## 四、代理设置\n\n### 使用 HTTP/HTTPS 代理\n\n```bash\n# 指定 HTTP 代理\nhttp --proxy=http:http://proxy.example.com:8080 https://api.example.com/data\n\n# 指定 HTTPS 代理\nhttp --proxy=https:http://proxy.example.com:80"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"HTTPie - 人性化的 HTTP 命令行客户端 Skill: Httpie Owner: cn-big-cabbage Summary: HTTPie - 人性化的 HTTP 命令行客户端 Tags: latest:0.1.1 Version history: v0.1.1 | 2026-06-16T06:50:52.712Z | auto - 元数据 now specifies required binary as http (was httpie). - Bumped version to 0.1.1. - Removed skill-card.md file. - No changes to user-facing commands or documentation content. v0.1.0 | 2026-04-15T01:01:42.210Z | user Initial release - HTTPie CLI skill for human-friendly","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":684,"uniquenessScore":54,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:35:43.302Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:35:43.302Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T14:35:48.665Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}