mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-01 15:03:57 +08:00

Files

catlog22 c3ddf7e322 docs: add VitePress documentation site

- 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

2026-02-28 16:14:09 +08:00

9.4 KiB

Raw Blame History

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 结构

{
  "$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

{
  "providers": {
    "openai": {
      "apiKey": "sk-proj-...",
      "baseURL": "https://api.openai.com/v1",
      "organization": "org-...",
      "timeout": 60000,
      "maxRetries": 3
    }
  }
}

Anthropic (Claude)

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-...",
      "baseURL": "https://api.anthropic.com/v1",
      "version": "2023-06-01",
      "timeout": 60000,
      "maxRetries": 3
    }
  }
}

Gemini (Google)

{
  "providers": {
    "gemini": {
      "apiKey": "AIza...",
      "baseURL": "https://generativelanguage.googleapis.com/v1beta",
      "timeout": 60000
    }
  }
}

LiteLLM (统一代理)

{
  "providers": {
    "litellm": {
      "apiKey": "sk-...",
      "baseURL": "https://litellm.example.com/v1",
      "dropParams": ["max_tokens"],
      "timeout": 120000
    }
  }
}

CCW 配置详解

{
  "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 配置

{
  "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"]
      }
    ]
  }
}

操作步骤

初始化配置

# 在项目中初始化配置文件
ccw config init

# 编辑配置
ccw config edit

设置 API Keys

方式 1: 编辑配置文件

# 编辑项目配置
code .cw/settings.json

# 编辑全局配置
code ~/.claude/settings.json

方式 2: 使用命令

# 设置 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: 环境变量

# 设置环境变量（优先级最高）
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="AIza..."

本地配置 (不提交)

# 创建本地配置（自动添加到 .gitignore）
cat > .cw/settings.local.json << 'EOF'
{
  "providers": {
    "openai": {
      "apiKey": "sk-proj-..."
    }
  }
}
EOF

验证配置

# 验证 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: 使用多配置文件：

# 开发环境
.cw/settings.dev.json

# 生产环境
.cw/settings.prod.json

# 切换环境
cp .cw/settings.dev.json .cw/settings.local.json

Q3: LiteLLM 如何配置？

A: 配置 LiteLLM 端点：

{
  "providers": {
    "litellm": {
      "apiKey": "sk-...",
      "baseURL": "https://your-litellm-proxy.com/v1"
    }
  },
  "cw": {
    "defaultTool": "litellm"
  }
}

Q4: 配置不生效怎么办？

A: 检查优先级和语法：

# 验证配置语法
ccw config validate

# 查看有效配置
ccw config show

# 查看配置来源
ccw config --debug

进阶阅读

配置加载: 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/

9.4 KiB Raw Blame History Unescape Escape