cli-switch

name	cli-switch
description	Agent Capability Router — 通过 cli-switch 调用 Claude Code 和 Codex 执行编码任务。当需要子 agent 写代码、重构、调试、测试时优先使用。Trigger: cli-switch, 用 claude code, 用 codex, delegate coding, 子 agent

cli-switch — Agent Capability Router

Hermes 的 Agent 编排层，通过 cli-switch 调用 Claude Code 和 Codex。

位置

• 项目: ~/projects/cli-switch/
• 二进制: node ~/projects/cli-switch/dist/cmd/root.js（开发模式）
• 全局安装后: cli-switch
• 配置目录: ~/.config/cli-switch/config.toml
• 环境变量优先级: env > config.toml > defaults

安装

git clone https://github.com/zhoutian1995/cli-switch.git
cd cli-switch
npm install && npm run build

核心命令

# 运行任务（最常用）
cli-switch run "<task>" --agent <claude-code|codex> [options]

# 路由决策预览（不执行）
cli-switch run "<task>" --dry-run

# 诊断
cli-switch doctor
cli-switch env

# 查看能力矩阵
cli-switch capabilities
cli-switch list models

run 常用选项

选项	说明	示例
--agent	指定 agent	--agent claude-code
--strategy	策略: balanced|high_quality|low_cost	--strategy high_quality
--tier	模型等级: economy|standard|premium	--tier premium
--no-git	跳过 git 分支管理	--no-git
--timeout	超时秒数	--timeout 120
--json	JSON 输出	--json
--acp	ACP 协议模式	--acp

Agent 能力对比

能力	Claude Code	Codex
reasoning	9/10	8/10
codeGen	9/10	8/10
refactoring	9/10	7/10
debugging	9/10	7/10
testing	7/10	9/10
longContext	10/10 (200K)	5/10 (128K)
speed	6/10	9/10

选型规则：

• 重构/调试/长上下文 → claude-code
• 测试/速度/成本 → codex
• 代码生成 → 都行，claude-code 略优

Gateway 模式

cli-switch 支持通过 Sub2API 等网关走第三方上游：

export SWITCH_API_KEY="sk-xxx"         # 默认 gateway key
export SWITCH_BASE_URL="http://localhost:8080"

# 可选：按 agent 分配不同 key（多平台 gateway）
export SWITCH_AGENT_KEYS='{"claude-code":"sk-xxx","codex":"sk-yyy"}'

• SWITCH_AGENT_KEYS 是 JSON，resolveGateway 优先用 agentKeys[agentId]，fallback 到 apiKey
• Claude Code 走 Anthropic 协议，Codex 走 OpenAI 协议，需不同 Sub2API key

Hermes 集成

Hermes 通过 delegate_task 调子 agent，应优先走 cli-switch：

# 用 Claude Code（native 模式，直连上游）
cli-switch run "<task>" --agent claude-code --no-git --timeout 120

# 用 Codex（native 模式）
cli-switch run "<task>" --agent codex --no-git --timeout 120

开发模式下二进制路径为 node ~/projects/cli-switch/dist/cmd/root.js。

支持的模型

alias	resolved	vendor	tools
sonnet	claude-3-7-sonnet	anthropic	claude-code
glm-5.1	glm-5.1	zhipu	claude-code
glm-5	glm-5	zhipu	claude-code
gpt-5.4	gpt-5.4	openai	codex

Pitfalls

1. Codex 需要 OPENAI_API_KEY：native 模式下必须设，gateway 模式下 cli-switch 自动注入
2. gateway key 不能混用：Anthropic 协议 key 发到 OpenAI group 会 404
3. GLM key 会过期：报错 令牌已过期或验证不正确
4. Responses API：GLM 和 MiMo 都不支持，Codex（走 Responses）目前无法通过这两个上游工作
5. 开发模式：用 node dist/cmd/root.js 运行，未全局安装。改动后务必 npm run build
6. 测试：314 tests（vitest），改动后跑 npx vitest run 确认