mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
c3ddf7e322
- Add docs directory with VitePress configuration - Add GitHub Actions workflow for docs build and deploy - Support bilingual (English/Chinese) documentation - Include search, custom theme, and responsive design
395 lines
9.4 KiB
Markdown
395 lines
9.4 KiB
Markdown
# API 设置
|
||
|
||
## 一句话定位
|
||
|
||
**API 设置是统一的多端点配置管理** — 在一个地方配置所有 AI 服务商的 API Keys 和端点，支持多环境切换和密钥加密存储。
|
||
|
||
## 解决的痛点
|
||
|
||
| 痛点 | 现状 | API 设置方案 |
|
||
| --- | --- | --- |
|
||
| **配置分散** | API Keys 散落在各工具配置中 | 统一配置入口 |
|
||
| **安全性弱** | 明文存储密钥 | 支持密钥加密 |
|
||
| **切换困难** | 切换服务商需要修改多处 | 一个配置文件管理所有 |
|
||
| **环境隔离差** | 开发/生产环境混用 | 支持多环境配置 |
|
||
|
||
## 核心概念速览
|
||
|
||
| 概念 | 说明 | 位置 |
|
||
| --- | --- | --- |
|
||
| **API Keys** | 服务商认证密钥 | `settings.json` / `settings.local.json` |
|
||
| **Providers** | AI 服务提供商 | OpenAI, Anthropic, Gemini, LiteLLM |
|
||
| **Endpoints** | API 服务端点 | URL + 认证配置 |
|
||
| **LiteLLM** | 统一代理服务 | 支持 100+ 模型 |
|
||
| **本地配置** | 项目级配置 | `.cw/settings.json` |
|
||
| **全局配置** | 用户级配置 | `~/.claude/settings.json` |
|
||
|
||
## 配置层级
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 配置优先级 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 1. settings.local.json (最高优先级，不提交) │
|
||
│ └─ 本地开发配置，覆盖其他配置 │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 2. .cw/settings.json (项目配置) │
|
||
│ └─ 项目特定配置，团队成员共享 │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 3. ~/.claude/settings.json (全局配置) │
|
||
│ └─ 用户默认配置，所有项目共享 │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 4. 默认值 (最低优先级) │
|
||
│ └─ 系统内置默认配置 │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### settings.json 结构
|
||
|
||
```json
|
||
{
|
||
"$schema": "https://cdn.jsdelivr.net/gh/your-repo/schema/settings-schema.json",
|
||
"providers": {
|
||
"openai": {
|
||
"apiKey": "sk-...",
|
||
"baseURL": "https://api.openai.com/v1",
|
||
"models": {
|
||
"gpt-4": "gpt-4-turbo",
|
||
"gpt-3.5": "gpt-3.5-turbo"
|
||
}
|
||
},
|
||
"anthropic": {
|
||
"apiKey": "sk-ant-...",
|
||
"baseURL": "https://api.anthropic.com/v1",
|
||
"models": {
|
||
"claude-opus": "claude-3-opus-20240229",
|
||
"claude-sonnet": "claude-3-sonnet-20240229"
|
||
}
|
||
},
|
||
"gemini": {
|
||
"apiKey": "AIza...",
|
||
"baseURL": "https://generativelanguage.googleapis.com/v1beta",
|
||
"models": {
|
||
"gemini-pro": "gemini-pro",
|
||
"gemini-flash": "gemini-1.5-flash"
|
||
}
|
||
},
|
||
"litellm": {
|
||
"apiKey": "sk-...",
|
||
"baseURL": "https://litellm.example.com/v1",
|
||
"models": {
|
||
"qwen-embed": "qwen/qwen3-embedding-sf"
|
||
}
|
||
}
|
||
},
|
||
"cw": {
|
||
"defaultTool": "gemini",
|
||
"promptFormat": "plain",
|
||
"smartContext": {
|
||
"enabled": false,
|
||
"maxFiles": 10
|
||
},
|
||
"nativeResume": true,
|
||
"recursiveQuery": true,
|
||
"cache": {
|
||
"injectionMode": "auto",
|
||
"defaultPrefix": "",
|
||
"defaultSuffix": ""
|
||
},
|
||
"codeIndexMcp": "ace"
|
||
},
|
||
"hooks": {
|
||
"prePrompt": [],
|
||
"postResponse": []
|
||
}
|
||
}
|
||
```
|
||
|
||
### Providers 配置详解
|
||
|
||
#### OpenAI
|
||
|
||
```json
|
||
{
|
||
"providers": {
|
||
"openai": {
|
||
"apiKey": "sk-proj-...",
|
||
"baseURL": "https://api.openai.com/v1",
|
||
"organization": "org-...",
|
||
"timeout": 60000,
|
||
"maxRetries": 3
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Anthropic (Claude)
|
||
|
||
```json
|
||
{
|
||
"providers": {
|
||
"anthropic": {
|
||
"apiKey": "sk-ant-...",
|
||
"baseURL": "https://api.anthropic.com/v1",
|
||
"version": "2023-06-01",
|
||
"timeout": 60000,
|
||
"maxRetries": 3
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Gemini (Google)
|
||
|
||
```json
|
||
{
|
||
"providers": {
|
||
"gemini": {
|
||
"apiKey": "AIza...",
|
||
"baseURL": "https://generativelanguage.googleapis.com/v1beta",
|
||
"timeout": 60000
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### LiteLLM (统一代理)
|
||
|
||
```json
|
||
{
|
||
"providers": {
|
||
"litellm": {
|
||
"apiKey": "sk-...",
|
||
"baseURL": "https://litellm.example.com/v1",
|
||
"dropParams": ["max_tokens"],
|
||
"timeout": 120000
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### CCW 配置详解
|
||
|
||
```json
|
||
{
|
||
"cw": {
|
||
"defaultTool": "gemini",
|
||
"promptFormat": "plain",
|
||
"smartContext": {
|
||
"enabled": false,
|
||
"maxFiles": 10
|
||
},
|
||
"nativeResume": true,
|
||
"recursiveQuery": true,
|
||
"cache": {
|
||
"injectionMode": "auto",
|
||
"defaultPrefix": "",
|
||
"defaultSuffix": ""
|
||
},
|
||
"codeIndexMcp": "ace"
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `defaultTool` | string | `gemini` | 默认 CLI 工具 |
|
||
| `promptFormat` | string | `plain` | Prompt 格式: `plain` / `yaml` / `json` |
|
||
| `smartContext.enabled` | boolean | `false` | 智能上下文开关 |
|
||
| `smartContext.maxFiles` | number | `10` | 最大文件数量 |
|
||
| `nativeResume` | boolean | `true` | 本地会话恢复 |
|
||
| `recursiveQuery` | boolean | `true` | 递归查询 |
|
||
| `cache.injectionMode` | string | `auto` | 缓存注入模式 |
|
||
| `codeIndexMcp` | string | `ace` | 代码索引 MCP: `codexlens` / `ace` / `none` |
|
||
|
||
### Hooks 配置
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"prePrompt": [
|
||
{
|
||
"type": "command",
|
||
"command": "ccw",
|
||
"args": ["spec", "load", "--stdin"]
|
||
},
|
||
{
|
||
"type": "mcp",
|
||
"server": "cw-tools",
|
||
"tool": "core_memory",
|
||
"args": {
|
||
"operation": "search",
|
||
"query": "{{userPrompt}}",
|
||
"top_k": 5
|
||
}
|
||
}
|
||
],
|
||
"postResponse": [
|
||
{
|
||
"type": "command",
|
||
"command": "ccw",
|
||
"args": ["memory", "capture"]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 操作步骤
|
||
|
||
### 初始化配置
|
||
|
||
```bash
|
||
# 在项目中初始化配置文件
|
||
ccw config init
|
||
|
||
# 编辑配置
|
||
ccw config edit
|
||
```
|
||
|
||
### 设置 API Keys
|
||
|
||
**方式 1: 编辑配置文件**
|
||
|
||
```bash
|
||
# 编辑项目配置
|
||
code .cw/settings.json
|
||
|
||
# 编辑全局配置
|
||
code ~/.claude/settings.json
|
||
```
|
||
|
||
**方式 2: 使用命令**
|
||
|
||
```bash
|
||
# 设置 OpenAI API Key
|
||
ccw config set providers.openai.apiKey "sk-proj-..."
|
||
|
||
# 设置 Anthropic API Key
|
||
ccw config set providers.anthropic.apiKey "sk-ant-..."
|
||
|
||
# 设置默认工具
|
||
ccw config set cw.defaultTool "codex"
|
||
```
|
||
|
||
**方式 3: 环境变量**
|
||
|
||
```bash
|
||
# 设置环境变量（优先级最高）
|
||
export OPENAI_API_KEY="sk-proj-..."
|
||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||
export GEMINI_API_KEY="AIza..."
|
||
```
|
||
|
||
### 本地配置 (不提交)
|
||
|
||
```bash
|
||
# 创建本地配置（自动添加到 .gitignore）
|
||
cat > .cw/settings.local.json << 'EOF'
|
||
{
|
||
"providers": {
|
||
"openai": {
|
||
"apiKey": "sk-proj-..."
|
||
}
|
||
}
|
||
}
|
||
EOF
|
||
```
|
||
|
||
### 验证配置
|
||
|
||
```bash
|
||
# 验证 API Keys
|
||
ccw config verify
|
||
|
||
# 测试连接
|
||
ccw cli -p "Hello" --tool gemini --mode analysis
|
||
```
|
||
|
||
## 配置文件位置
|
||
|
||
| 配置文件 | 位置 | 用途 | Git |
|
||
| --- | --- | --- | --- |
|
||
| 项目配置 | `.cw/settings.json` | 项目共享配置 | 提交 |
|
||
| 本地配置 | `.cw/settings.local.json` | 个人开发配置 | **不提交** |
|
||
| 全局配置 | `~/.claude/settings.json` | 用户默认配置 | 不适用 |
|
||
| CLI 工具配置 | `~/.claude/cli-tools.json` | CLI 工具定义 | 不适用 |
|
||
| CLI 设置 | `.cw/cli-settings.json` | CLI 行为配置 | 提交 |
|
||
|
||
## 常见问题
|
||
|
||
### Q1: API Key 存储安全吗？
|
||
|
||
A: 建议使用 `settings.local.json` 存储敏感信息：
|
||
- `settings.local.json` 自动被 `.gitignore` 排除
|
||
- 永不提交到仓库
|
||
- 优先级最高，覆盖其他配置
|
||
|
||
### Q2: 如何切换不同环境？
|
||
|
||
A: 使用多配置文件：
|
||
|
||
```bash
|
||
# 开发环境
|
||
.cw/settings.dev.json
|
||
|
||
# 生产环境
|
||
.cw/settings.prod.json
|
||
|
||
# 切换环境
|
||
cp .cw/settings.dev.json .cw/settings.local.json
|
||
```
|
||
|
||
### Q3: LiteLLM 如何配置？
|
||
|
||
A: 配置 LiteLLM 端点：
|
||
|
||
```json
|
||
{
|
||
"providers": {
|
||
"litellm": {
|
||
"apiKey": "sk-...",
|
||
"baseURL": "https://your-litellm-proxy.com/v1"
|
||
}
|
||
},
|
||
"cw": {
|
||
"defaultTool": "litellm"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Q4: 配置不生效怎么办？
|
||
|
||
A: 检查优先级和语法：
|
||
|
||
```bash
|
||
# 验证配置语法
|
||
ccw config validate
|
||
|
||
# 查看有效配置
|
||
ccw config show
|
||
|
||
# 查看配置来源
|
||
ccw config --debug
|
||
```
|
||
|
||
## 相关功能
|
||
|
||
- [CLI 调用系统](./cli.md) — 使用 API Keys 执行命令
|
||
- [系统设置](./system-settings.md) — cli-tools.json 配置
|
||
- [Dashboard 面板](./dashboard.md) — 可视化配置管理
|
||
|
||
## 进阶阅读
|
||
|
||
- 配置加载: `ccw/src/config/settings-loader.ts`
|
||
- 配置验证: `ccw/src/config/settings-validator.ts`
|
||
- CLI 配置: `ccw/src/tools/claude-cli-tools.ts`
|
||
- Hooks 执行: `ccw/src/core/hooks/`
|