内容
# @octen.ai/cli
Octen 命令行工具 — 网络搜索、内容提取、聊天、嵌入、以及 Claude Code、Cursor 等客户端的一键 MCP/Skills 配置。
## 安装
**使用 Node.js (npm)：**
```sh
npm i -g @octen.ai/cli
```
或者无需安装直接运行：`npx @octen.ai/cli <命令>`。需要 Node.js 18+。
卸载：`npm uninstall -g @octen.ai/cli`。
### 无 Node.js — Homebrew (macOS/Linux)
安装（一步到位，自动创建 tap）：
```sh
brew install Octen-Team/tap/octen
```
卸载：
```sh
brew uninstall octen
brew untap Octen-Team/tap # 可选 — 同时移除 tap
```
### 无 Node.js — 原始二进制文件
从 [最新版本](https://github.com/Octen-Team/octen-cli/releases/latest) 下载适用于您平台的二进制文件（`octen-darwin-arm64`、`octen-darwin-x64`、`octen-linux-x64`、`octen-linux-arm64`），执行 `chmod +x` 操作，并将其添加到您的 `PATH` 中。
然后启用 tab 补全（一次性操作；`bash` / `zsh` / `fish`）：
```sh
octen completion zsh --install # 写入 ~/.zshrc — 然后：source ~/.zshrc
```
## 身份验证
设置您的 API 密钥（在 https://octen.ai 获取）：
```sh
export OCTEN_API_KEY=您的密钥
```
您也可以在任何命令上传递 `--api-key <密钥>`。要指向自托管或临时端点，请设置 `OCTEN_API_URL` 或传递 `--base-url <网址>`。
## 命令
### `octen search`
实时网络搜索。
```sh
octen search "最新的 LLM 基准测试" -n 10 --topic news --highlight --time-range week
```
选项：`-n`（结果数量 1–100），`--topic`（general|news），`--highlight`（`--highlight-max-tokens`，最小 100），`--time-range`（day|week|month|year 或 d|w|m|y），`--start-time`/`--end-time`（YYYY-MM-DD 或 ISO 日期时间），`--include-domains`，`--exclude-domains`，`--full-content`，`--images`，`--videos`，`--format`（text|markdown），`--safesearch`。
---
### `octen news`
新闻聚焦的网络搜索（与 `search` 相同的标志，但无 `--topic`）。
```sh
octen news "OpenAI 公告" --highlight --time-range day
```
---
### `octen fetch`
从一个或多个网址提取内容（1–20）。
```sh
octen fetch https://example.com --query "pricing" --max-age 3600 --images
```
选项：`--query`（相关性提示），`--max-age <秒>`（缓存年龄，300–31536000），`--images`，`--videos`，`--audio`，`--favicon`，`--format`（markdown|text），`--fetch-timeout <秒>`（1–60），`--full`（打印完整页面内容）。
漂亮的输出将页面内容截断为约 500 个字符以提高可读性；传递 `--full` 以打印完整内容（或 `--json` 以获取原始响应）。
---
### `octen chat`
可选流式的聊天完成。
```sh
octen chat "总结 Octen 文档" -m anthropic/claude-haiku-4.5
```
默认情况下，当输出是 TTY 时，流式传输是开启的；使用 `--no-stream` 获取单个 JSON 响应。传递 `-i` 以交互式 REPL 模式。设置 `OCTEN_CHAT_MODEL` 以避免每次都指定 `-m`。
选项：`-m/--model`，`--system`，`--web-search`（on|off），`--temperature`，`--top-p`，`--max-tokens`，`--reasoning-effort`（low|medium|high），`--frequency-penalty`，`--presence-penalty`，`--stop`，`--seed`，`--no-stream`，`-i/--interactive`。
---
### `octen embed`
创建文本嵌入。
```sh
octen embed "语义搜索查询" -m 4b
```
接受多个位置参数，`--file <路径>`（每行一个文本），或 stdin。使用 `--json`（全局标志）打印原始向量数组。
选项：`-m/--model`（0.6b|4b|8b 或完整 ID），`--dimension`，`--input-type`（query|document），`--truncation`/`--no-truncation`。
---
### `octen vl-embed`
从文本、图像和/或视频创建多模态嵌入。
```sh
octen vl-embed "text:红色汽车" "image:https://example.com/car.jpg" -m base --fusion
```
内容令牌以 `text:`、`image:` 或 `video:` 为前缀。图像/视频值可以是 URL 或本地文件路径。
选项：`-m/--model`（base|large 或完整 ID），`--fusion`/`--no-fusion`，`--dimension`，`--fps`，`--instruct`。
---
### `octen configure-mcp`
在 AI 客户端中配置 Octen MCP 服务器（合并到现有配置中，不会覆盖）。
```sh
# 一次配置所有支持的客户端
octen configure-mcp --all
# 或选择特定客户端
octen configure-mcp --claude-code --cursor
# 固定到特定 octen-mcp 版本
octen configure-mcp --all --pin 0.2.1
```
支持的客户端：Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Codex。
仅检测到的客户端会被配置；`--all` 会跳过其余的客户端，而显式命名的客户端如果未检测到，则除非传递 `--force`，否则会被跳过。
选项：`--all`，`--claude-code`，`--cursor`，`--claude-desktop`，`--windsurf`，`--vscode`，`--codex`，`--scope`（user|project），`--pin <版本>`，`--force`（即使客户端未检测到，也要配置）。
运行不带标志以打印每个客户端的当前状态。
---
### `octen configure-skills`
将 Octen Agent Skills 安装到 AI 客户端中。
```sh
# 安装到所有支持的客户端（从上游获取最新技能）
octen configure-skills --all
# 使用捆绑技能 — 无需网络连接
octen configure-skills --all --offline
# 从特定 git ref 获取
octen configure-skills --claude-code --ref v0.3.0
# 同时将 OCTEN_API_KEY 写入客户端的环境配置中
octen configure-skills --claude-code --set-key --api-key <密钥>
```
支持的客户端：Claude Code、Cursor、Codex、OpenClaw、Hermes。
Claude Desktop 读取与 Claude Code 相同的 `~/.claude/skills`，因此 `--claude-code` 已经安装了桌面应用程序将使用的技能。`--claude-desktop` 被接受为该共享目标的显式别名。
`--set-key` 还将 OCTEN_API_KEY 写入客户端的环境配置（Claude Code `~/.claude/settings.json`，Codex `config.toml`，OpenClaw `.env`）；Cursor/Hermes 打印 shell-profile 提示。密钥来自 `--api-key` 或 `OCTEN_API_KEY` 环境变量。
仅检测到的客户端会被配置；`--all` 会跳过其余的客户端，而显式命名的客户端如果未检测到，则除非传递 `--force`，否则会被跳过。
选项：`--all`，`--claude-code`，`--cursor`，`--codex`，`--openclaw`，`--hermes`，`--scope`（user|project），`--ref <引用>`（默认：main），`--bundled`/`--offline`（使用预置技能），`--only <名称>`（逗号分隔的技能名称），`--skills-dir <路径>`（自定义源目录），`--set-key`（将 OCTEN_API_KEY 写入客户端的环境配置），`--force`（即使客户端未检测到，也要配置）。
运行不带标志以显示每个客户端已安装的技能。
---
### `octen reset`
从 AI 客户端中移除 Octen MCP 服务器和/或技能。
```sh
# 从所有客户端中移除所有内容
octen reset --all
# 仅移除 MCP 条目
octen reset --mcp
# 仅从特定客户端移除技能
octen reset --skills --claude-code
```
选项：`--all`（两个界面，所有客户端），`--mcp`，`--skills`，以及每个客户端的标志：`--claude-code`，`--cursor`，`--claude-desktop`，`--windsurf`，`--vscode`，`--codex`，`--openclaw`，`--hermes`，`--scope`（user|project）。
---
## Shell 补全
`octen completion <shell>`（bash | zsh | fish）设置子命令和标志的 tab 补全。
**最简单 — `--install`** 会为您写入 shell 配置中（幂等）：
```sh
octen completion zsh --install # 追加到 ~/.zshrc
octen completion bash --install # 追加到 ~/.bashrc
octen completion fish --install # 写入 ~/.config/fish/completions/octen.fish
```
然后 `source ~/.zshrc`（或打开新终端）以在当前会话中激活它。
**手动** — 打印脚本并自行加载（子进程无法更改正在运行的 shell，因此这是立即在当前 shell 中激活它的方式）：
```sh
eval "$(octen completion zsh)" # 将此行添加到 ~/.zshrc 以持久化
```
---
## 输出
所有命令在 stdout 为 TTY 时打印人类可读的输出。当 stdout 被管道传输或传递 `--json` 时，命令会发出原始 JSON。使用 `--pretty` 强制人类可读的输出，即使在管道传输时。`--no-color` 禁用 ANSI 颜色。
## 保持更新
- **MCP 服务器**：`octen-mcp` 通过 `npx` 调用，因此每次运行时会自动拉取最新版本。如果需要稳定性，请使用 `--pin` 固定版本。
- **技能**：重新运行 `octen configure-skills --all` 以从上游获取最新技能。
- **CLI 本身**：`npm i -g @octen.ai/cli@latest`
## 关于
`@octen.ai/cli` 封装了 Octen API（网络搜索、内容提取、聊天完成、文本和多模态嵌入），并处理 [Octen MCP 服务器](https://www.npmjs.com/package/octen-mcp) 和 Agent Skills 在 Claude Code（CLI 和桌面应用程序）、Cursor、Claude Desktop、Windsurf、VS Code、Codex、OpenClaw 和 Hermes 上的 一键配置。
