clinvoker 快速开始¶
欢迎使用 clinvoker - 一个用于编排多个 AI 编程助手的统一命令行界面。本综合教程将指导您完成安装、配置以及与工具的首次交互。
什么是 clinvoker？¶
clinvoker（发音为 "see-el-in-voker"）是一个通用网关，统一了多个 AI 编程助手的访问，包括 Claude Code、Codex CLI 和 Gemini CLI。您无需为每个 AI 工具学习不同的命令和接口，而是使用单一、一致的界面。
核心优势¶
- 统一接口：所有后端使用一套命令结构
- 会话管理：跨会话的持久化对话
- 并行执行：同时运行多个 AI 任务
- 链式工作流：将一个后端的输出传递给另一个后端
- HTTP API：作为服务部署以进行集成
前置要求¶
在安装 clinvoker 之前，请确保您具备以下条件：
系统要求¶
| 要求 | 版本 | 说明 |
|---|---|---|
| Go | 1.24+ | 仅从源码构建时需要 |
| 操作系统 | Linux、macOS、Windows | 支持 AMD64 和 ARM64 |
| 内存 | 最低 512MB | 用于运行 CLI |
| 磁盘空间 | 100MB | 用于二进制文件和配置 |
后端前置要求¶
clinvoker 需要至少一个 AI 后端才能发挥作用：
| 后端 | 安装命令 | 文档 |
|---|---|---|
| Claude Code | npm install -g @anthropic-ai/claude-code |
Claude.ai |
| Codex CLI | npm install -g @openai/codex |
GitHub |
| Gemini CLI | npm install -g @google/gemini-cli |
GitHub |
验证后端安装：
# 检查 Claude Code
which claude && claude --version
# 检查 Codex CLI
which codex && codex --version
# 检查 Gemini CLI
which gemini && gemini --version
安装方法¶
选择最适合您环境的安装方法：
方法对比¶
| 方法 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| 快速安装脚本 | 首次使用用户 | 设置最快，自动配置 PATH | 需要 curl/PowerShell |
| 包管理器 | 常规使用 | 易于更新，依赖管理 | 可能不是最新版本 |
| 手动下载 | 隔离网络系统 | 完全控制版本 | 需要手动更新 |
| 从源码构建 | 开发者 | 最新功能，可定制 | 需要 Go 工具链 |
1. 快速安装（推荐）¶
最快的开始方式：
此脚本将：
1. 检测您的操作系统和架构
2. 下载相应的二进制文件
3. 安装到 ~/.local/bin（或使用 sudo 安装到 /usr/local/bin）
4. 如有需要更新您的 PATH
2. 包管理器¶
Homebrew (macOS/Linux)¶
Scoop (Windows)¶
# 添加 bucket
scoop bucket add signalridge https://github.com/signalridge/scoop-bucket
# 安装
scoop install clinvk
# 升级
scoop update clinvk
Nix (Linux/macOS)¶
# 直接运行，无需安装
nix run github:signalridge/clinvoker
# 安装到 profile
nix profile install github:signalridge/clinvoker
# 在 flake.nix 中使用
{
inputs.clinvoker.url = "github:signalridge/clinvoker";
nixpkgs.overlays = [ clinvoker.overlays.default ];
}
Arch Linux (AUR)¶
Debian/Ubuntu¶
# 从 releases 页面下载
wget https://github.com/signalridge/clinvoker/releases/download/v0.1.0/clinvk_0.1.0_amd64.deb
sudo dpkg -i clinvk_*.deb
RPM 系 (Fedora/RHEL)¶
# 从 releases 页面下载
wget https://github.com/signalridge/clinvoker/releases/download/v0.1.0/clinvk-0.1.0-1.x86_64.rpm
sudo rpm -i clinvk-*.rpm
3. 手动下载¶
从 GitHub Releases 下载预构建的二进制文件：
下载 clinvoker_<version>_windows_amd64.zip 并解压到 PATH 中的某个目录。
4. 从源码构建¶
需要 Go 1.24 或更高版本：
# 使用 go install
go install github.com/signalridge/clinvoker/cmd/clinvk@latest
# 或克隆并构建
git clone https://github.com/signalridge/clinvoker.git
cd clinvoker
go build -o clinvk ./cmd/clinvk
sudo mv clinvk /usr/local/bin/
验证安装¶
安装完成后，验证一切正常：
预期输出：
检查检测到的后端：
您应该会看到根据系统上已安装内容列出的可用后端列表。
环境设置¶
API 密钥¶
每个后端都需要自己的 API 密钥配置：
| 后端 | 配置方法 | 环境变量 |
|---|---|---|
| Claude | claude config set api_key <key> |
ANTHROPIC_API_KEY |
| Codex | codex config set api_key <key> |
OPENAI_API_KEY |
| Gemini | gemini config set api_key <key> |
GOOGLE_API_KEY |
默认后端¶
设置您偏好的默认后端：
配置文件¶
创建 ~/.clinvk/config.yaml：
# 未指定 -b 时的默认后端
default_backend: claude
# 统一标志适用于所有后端
unified_flags:
approval_mode: default
sandbox_mode: default
# 后端特定设置
backends:
claude:
model: claude-sonnet-4-20250514
codex:
model: o3
gemini:
model: gemini-2.5-pro
# 会话管理
session:
retention_days: 30
您的第一个提示词¶
基本用法¶
使用默认后端运行您的第一个提示词：
这会将您的提示词发送到默认后端（默认是 Claude Code）并显示响应。
指定后端¶
使用不同的后端以发挥各自的优势：
# Claude 擅长复杂推理和架构设计
clinvk -b claude "为电商平台设计微服务架构"
# Codex 针对代码生成进行了优化
clinvk -b codex "用 Python 实现快速排序算法"
# Gemini 提供广泛的知识和解释
clinvk -b gemini "解释 SQL 和 NoSQL 数据库之间的权衡"
工作目录¶
通过设置工作目录提供上下文：
输出格式详解¶
clinvoker 支持三种输出格式，每种适用于不同的使用场景：
Text 格式（默认）¶
适合交互式使用的人类可读输出：
特点： - 干净、格式化的文本 - 无元数据或结构 - 最适合终端阅读 - 适合管道传递给其他工具
何时使用： 交互式会话、阅读响应、快速查询
JSON 格式¶
适合编程使用的结构化输出，包含元数据：
输出结构：
{
"output": "REST (Representational State Transfer)...",
"backend": "claude",
"model": "claude-sonnet-4-20250514",
"duration_ms": 2450,
"tokens_used": 450,
"session_id": "sess_abc123",
"timestamp": "2025-01-27T10:30:00Z"
}
何时使用： 脚本编写、日志记录、存储结果、API 集成
Stream JSON 格式¶
适用于长时间运行任务的实时流式输出：
特点： - 在内容可用时立即发出 JSON 对象 - 实时显示进度 - 每个块包含响应的一部分 - 最终对象包含完整的元数据
何时使用： 长格式内容、实时应用、进度监控
格式对比¶
| 格式 | 人类可读 | 机器可读 | 实时 | 元数据 |
|---|---|---|---|---|
| text | 是 | 否 | 否 | 否 |
| json | 否 | 是 | 否 | 是 |
| stream-json | 部分 | 是 | 是 | 是 |
会话管理基础¶
理解会话¶
会话是与 AI 后端的持久化对话上下文。clinvoker 会自动：
- 当您运行提示词时创建新会话
- 将后续提示词与同一会话关联
- 在多次交互中保持上下文
列会话¶
查看所有活动会话：
输出：
ID BACKEND CREATED STATUS TAGS
sess_abc12 claude 2025-01-27 10:00:00 active project-x
sess_def34 codex 2025-01-27 09:30:00 closed -
继续会话¶
恢复之前的对话：
# 继续最近的会话
clinvk --continue "那缓存策略呢？"
# 或使用 resume 命令
clinvk resume --last
# 恢复特定会话
clinvk resume sess_abc12
会话最佳实践¶
- 使用标签 按项目或主题组织会话
- 定期清理旧会话 以节省磁盘空间
- 使用
--ephemeral用于不需要持久化的一次性查询
故障排除¶
问题 1："Backend not available"¶
症状：
原因和解决方案：
-
后端未安装
-
后端不在 PATH 中
-
后端在配置中被禁用
问题 2："API key not configured"¶
症状：
解决方案：
# 为 Claude 配置 API 密钥
claude config set api_key $ANTHROPIC_API_KEY
# 或设置环境变量
export ANTHROPIC_API_KEY="sk-ant-..."
问题 3："Session not found"¶
症状：
说明： 首次运行时这是正常的。会话在第一次成功提示词后创建。
解决方案：
如果仍有问题：
后续步骤¶
现在您已安装并运行 clinvoker，根据您的目标探索以下路径：
用于代码审查自动化¶
用于工具集成¶
- LangChain 集成 - 连接到 LangChain
- HTTP 服务器 - 作为 API 服务部署
- Claude Code Skills - 构建自定义技能
用于复杂工作流¶
- 链式执行 - 创建多步骤流水线
- 构建 AI Skills - 开发专门的 AI 代理
- 架构概述 - 了解内部结构
快速参考¶
# 基本用法
clinvk "您的提示词"
clinvk -b codex "生成代码"
# 并行执行
clinvk parallel -f tasks.json
# 链式工作流
clinvk chain -f pipeline.json
# 服务器模式
clinvk serve --port 8080
# 会话管理
clinvk sessions list
clinvk resume --last
总结¶
您已成功完成：
- 使用您偏好的方法安装 clinvoker
- 配置 API 密钥和默认后端
- 使用不同后端运行第一个提示词
- 探索输出格式及其使用场景
- 学习会话管理基础
- 识别常见问题的解决方案
clinvoker 将多个 AI 助手统一在一个界面下，支持并行执行、链式处理和 CI/CD 集成等强大工作流。后续教程将向您展示如何利用这些功能应对实际场景。