octen-search

Octen 搜索

Octen 的搜索技能。它提供实时网页搜索和广泛（多查询）搜索（见下方的广泛搜索）。图片和视频搜索由单独的 octen-image-search 和 octen-video-search 技能提供。

需要 API 密钥：前往 https://octen.ai 获取

设置密钥：export OCTEN_API_KEY=your-api-key

API 密钥设置

搜索前，请确保已设置 OCTEN_API_KEY。如果未设置，或任何调用返回 401，请停止操作，不要盲目重试：告知用户需要密钥，引导用户前往 https://octen.ai 获取，并协助用户为其 Agent 配置密钥（见下文），然后在密钥设置完成后继续。

为相应的 Agent／运行环境配置密钥：

• Claude Code — 将 { "env": { "OCTEN_API_KEY": "your-key" } } 添加到 ~/.claude/settings.json（临时的 shell export 不会持久生效）
• Cursor / Hermes / 通用 shell — 在 ~/.zshrc 或 ~/.bashrc 中执行 export OCTEN_API_KEY="your-key"
• Codex — 在 ~/.codex/config.toml 的 [shell_environment_policy] 中设置 set = { OCTEN_API_KEY = "your-key" }
• OpenClaw — 将 OCTEN_API_KEY=your-key 添加到 ~/.openclaw/.env

完整的各 Agent 配置说明请参阅 README。

快速开始（cURL）

基本搜索

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{"query": "latest AI research 2026", "count": 5}'

添加高亮和时间筛选

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "summary judgment",
    "count": 10,
    "time_basis": "published",
    "start_time": "2025-01-01T00:00:00Z",
    "end_time": "2026-01-01T00:00:00Z",
    "highlight": {"enable": true, "max_tokens": 300}
  }'

添加域名筛选

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "climate change policy",
    "count": 5,
    "include_domains": ["nature.com", "science.org"],
    "exclude_domains": ["spam.com"]
  }'

添加语言筛选

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "climate change 2026",
    "count": 5,
    "language": ["ja", "zh"]
  }'

获取完整内容

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "latest WHO guidance on influenza vaccination",
    "count": 5,
    "full_content": {"enable": true, "max_tokens": 1000}
  }'

端点

POST https://api.octen.ai/search

身份验证：X-Api-Key: <API_KEY> 请求头

Content-Type：application/json

参数

Parameter	Type	Required	Default	Description
query	string	是	-	搜索查询（最多 500 个字符）
topic	string	否	general	搜索垂直领域：general 或 news
count	integer	否	5	结果数量（1–100）
include_domains	string[]	否	-	仅包含来自这些域名的结果（最多 1200 个域名，每个最多 60 个字符）
exclude_domains	string[]	否	-	排除来自这些域名的结果（最多 1200 个域名，每个最多 60 个字符）
include_text	string[]	否	-	结果页面文本中必须出现的字符串（最多 5 项，每项最多 30 个字符）
exclude_text	string[]	否	-	结果页面文本中不得出现的字符串（最多 5 项，每项最多 30 个字符）
language	string[]	否	[]	将结果筛选为这些语言，使用 ISO 639-1 代码（例如 ["en", "ja"]）。支持：ar、de、en、es、fr、hi、id、it、ja、ko、nl、pl、pt、ru、th、tr、vi、zh。留空 = 不按语言筛选。参见 https://localizely.com/iso-639-1-list/
time_basis	string	否	auto	用于筛选的时间字段：auto、published、crawled
start_time	string	否	-	开始时间筛选，采用 ISO 8601 格式（例如 2025-01-01T00:00:00Z）
end_time	string	否	-	结束时间筛选，采用 ISO 8601 格式（必须晚于 start_time）
highlight	object	否	{"enable": true}	高亮选项（见下文）
format	string	否	text	高亮内容的输出格式：text 或 markdown
safesearch	string	否	strict	成人内容筛选：off 或 strict
full_content	object	否	{"enable": false}	完整内容选项（见下文）
include_images	boolean	否	false	为每条结果返回页面封面图片和正文图片（见“响应字段”）。如需搜索图片，请改用 octen-image-search 技能

高亮选项

Field	Type	Default	Description
enable	boolean	true	返回每条结果中与查询相关的高亮内容
max_tokens	integer	512	每条高亮内容的最大 token 数（100–20000）

完整内容选项

Field	Type	Default	Description
enable	boolean	false	返回每条结果对应的完整原始页面内容
max_tokens	integer	2048	每条结果的最大 token 数（100–100000）

响应格式

响应字段

字段	类型	描述
code	integer	状态码。0 = 成功
msg	string	人类可读的状态消息
request_id	string	唯一请求标识符
data.query	string	原始查询
data.results[]	array	搜索结果列表
data.results[].title	string	页面标题
data.results[].url	string	页面 URL
data.results[].highlight	string?	与查询相关的摘要（当 highlight.enable 为 true 时）
data.results[].full_content	string?	完整页面内容（当 full_content.enable 为 true 时）
data.results[].authors	string?	网站名称或作者
data.results[].time_published	string?	发布时间，ISO 8601 格式
data.results[].time_last_crawled	string?	最近一次抓取时间，ISO 8601 格式
data.results[].favicon	string?	结果网站的 Favicon URL
data.results[].cover_image	object?	页面封面图片 {url, description}（当 include_images 为 true 且页面包含封面图片时）
data.results[].images[]	array?	页面正文中的图片，按出现顺序排列，格式为 {url, description}（当 include_images 为 true 时）
meta.usage.num_search_queries	integer	执行的搜索查询数量
meta.usage.full_content_tokens	integer	full_content 中返回的令牌总数
meta.latency	number	响应时间，单位为毫秒
meta.warning	string?	警告消息（如有）

JSON 示例

{
  "code": 0,
  "msg": "success",
  "request_id": "req_abc123def456",
  "data": {
    "query": "latest WHO guidance on influenza vaccination",
    "results": [
      {
        "title": "Influenza (Seasonal) - World Health Organization (WHO)",
        "url": "https://www.who.int/news-room/fact-sheets/detail/influenza-(seasonal)",
        "highlight": "WHO recommends annual vaccination for high-risk groups\n\n...\n\nSeasonal influenza vaccination policies vary by region...",
        "authors": "World Health Organization",
        "time_published": "2024-10-15T00:00:00Z",
        "time_last_crawled": "2026-01-20T02:12:34Z"
      }
    ]
  },
  "meta": {
    "usage": {
      "num_search_queries": 1,
      "full_content_tokens": 0
    },
    "latency": 237,
    "warning": null
  }
}

广泛搜索

广泛搜索会从不同角度将你的查询扩展为多个相关的子查询，并并发搜索，然后按子查询分组返回结果（不同组之间不会去重），可直接用于构建完整答案。

适用场景：单次 /search 只能触及少数相关子主题时：

• 跨多个来源进行比较（价格、产品、供应商）
• 综述 / 深入研究
• 涉及多个方面的多角度问题

对于单一且明确的查询，请改用普通的 /search。

按原样传入原始查询——Octen 会为你生成子查询，因此不要改写问题，也不要拆分成多个调用；如需扩大覆盖范围，请提高 max_queries（默认值为 5；综述 / 研究最多可设为 30，若要缩小搜索范围则调低）。

端点

POST https://api.octen.ai/broad-search

示例

curl -s -X POST "https://api.octen.ai/broad-search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "compare cloud GPU pricing across major providers",
    "max_queries": 5,
    "search_options": {"count": 10, "highlight": {"enable": true}}
  }'

参数

参数	类型	必填	默认值	描述
query	string	是	-	原始搜索查询（最多 500 个字符）
max_queries	integer	否	5	生成的子查询数量上限（1–30）；综述 / 研究可提高至 30，若要缩小搜索范围则调低
search_options	object	否	-	应用于每个子查询的选项——字段和默认值与上方参数表格相同（topic、count、include_domains、language、时间筛选条件、highlight、full_content、include_images 等）

响应

与 Search 使用相同的封装结构（code、msg、request_id、meta）。data 包含：

字段	类型	描述
data.query	string	原始查询
data.queries[]	string[]	生成的子查询
data.search_results[]	array	每个子查询对应一个结果组
data.search_results[].query	string	此结果组对应的子查询
data.search_results[].results[]	array	此子查询的结果（结构与 Search 的 data.results[] 相同）
data.search_results[].latency	integer	此子查询的延迟，单位为毫秒

错误代码

HTTP 状态	描述
400	缺少参数或参数无效
401	API 密钥无效或缺失
403	余额不足
429	请求过于频繁
500	内部服务器错误

安全

• API 密钥仅通过 HTTPS 发送至硬编码端点 https://api.octen.ai/search
• 身份验证使用标准的 X-Api-Key 标头
• 不会将任何环境变量发送至其他端点或外部服务

说明

• 默认启用高亮——设置 "highlight": {"enable": false} 可将其禁用
• 默认禁用完整内容——启用后可获取用于 RAG/grounding 的原始页面文本
• 使用 include_domains / exclude_domains 将结果限定为可信来源
• 使用 language（ISO 639-1 代码，例如 ["ja", "zh"]）按语言筛选结果——在 Broad Search 中，请将其设置在 search_options 内，而非顶层
• 使用 start_time / end_time 配合 time_basis，按发布时间或抓取时间筛选
• format: "markdown" 以 Markdown 格式返回高亮内容；format: "text" 返回纯文本