Kode-cli/docs/develop-zh/configuration.md

配置系统

概述

Kode 使用复杂的多级配置系统，允许在全局、项目和运行时级别进行自定义。配置从全局默认值通过项目特定设置级联到运行时覆盖。

配置层次结构

环境变量（最高优先级）
           ↓
    运行时标志 (CLI)
           ↓
  项目配置 (./.claude/config.json)
           ↓
   全局配置 (~/.claude/config.json)
           ↓
      默认值（最低优先级）

配置文件

全局配置

位置：~/.claude/config.json

{
  "theme": "dark",
  "hasCompletedOnboarding": true,
  "modelProfiles": {
    "default": {
      "type": "anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "maxTokens": 8192
    }
  },
  "modelPointers": {
    "main": "default",
    "task": "fast",
    "reasoning": "smart",
    "quick": "quick"
  },
  "mcpServers": {},
  "customApiKey": null,
  "autoUpdaterStatus": "enabled",
  "numStartups": 42
}

项目配置

位置：./.claude/config.json

{
  "enableArchitectTool": false,
  "allowedCommands": [
    "git *",
    "npm *",
    "bun *"
  ],
  "approvedTools": [
    "file_read",
    "file_edit",
    "bash"
  ],
  "context": {
    "projectName": "my-project",
    "description": "项目描述"
  },
  "mcpServers": {},
  "lastCost": 0.0234,
  "lastDuration": 45000
}

配置模式

模型配置

模型配置文件

定义可重用的 AI 模型配置：

interface ModelProfile {
  id: string
  name: string
  provider: 'anthropic' | 'openai' | 'custom'
  config: {
    model: string
    baseURL?: string
    apiKey?: string
    maxTokens?: number
    temperature?: number
    headers?: Record<string, string>
  }
}

模型指针

将角色映射到模型配置文件：

interface ModelPointers {
  main: string      // 主要对话模型
  task: string      // 任务执行模型
  reasoning: string // 复杂推理模型
  quick: string     // 快速响应模型
}

MCP 服务器配置

interface MCPServerConfig {
  type: 'stdio' | 'sse'
  // 对于 stdio 服务器
  command?: string
  args?: string[]
  env?: Record<string, string>
  // 对于 SSE 服务器
  url?: string
}

interface MCPServers {
  [serverName: string]: MCPServerConfig
}

权限配置

interface PermissionConfig {
  // 批准的 shell 命令模式
  allowedCommands: string[]
  
  // 批准的工具名称
  approvedTools: string[]
  
  // 文件/目录访问模式
  allowedPaths: string[]
  
  // 拒绝的 MCP 服务器
  rejectedMcprcServers: string[]
  
  // 批准的 MCP 服务器
  approvedMcprcServers: string[]
}

UI 配置

interface UIConfig {
  theme: 'dark' | 'light'
  compactMode: boolean
  showCosts: boolean
  syntaxHighlighting: boolean
  vimKeybindings: boolean
  shiftEnterKeyBindingInstalled: boolean
}

配置管理 API

读取配置

import { getGlobalConfig, getCurrentProjectConfig } from './utils/config'

// 获取全局配置
const globalConfig = getGlobalConfig()

// 获取项目配置
const projectConfig = getCurrentProjectConfig()

// 获取合并配置（项目覆盖全局）
const config = {
  ...globalConfig,
  ...projectConfig
}

写入配置

import { saveGlobalConfig, saveCurrentProjectConfig } from './utils/config'

// 更新全局配置
saveGlobalConfig({
  ...getGlobalConfig(),
  theme: 'light'
})

// 更新项目配置
saveCurrentProjectConfig({
  ...getCurrentProjectConfig(),
  enableArchitectTool: true
})

CLI 配置命令

# 获取配置值
kode config get theme
kode config get -g modelProfiles.default.model

# 设置配置值
kode config set theme dark
kode config set -g autoUpdaterStatus enabled

# 删除配置值
kode config remove customApiKey
kode config remove -g mcpServers.myserver

# 列出所有配置
kode config list
kode config list -g

环境变量

核心变量

# API 密钥
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# 模型选择
CLAUDE_MODEL=claude-3-5-sonnet-20241022
DEFAULT_MODEL_PROFILE=fast

# 功能标志
ENABLE_ARCHITECT_TOOL=true
DEBUG_MODE=true
VERBOSE=true

# MCP 配置
MCP_SERVER_URL=http://localhost:3000
MCP_TIMEOUT=30000

# 开发
NODE_ENV=development
LOG_LEVEL=debug

优先级规则

环境变量覆盖配置文件：

1. 检查环境变量
2. 检查项目配置
3. 检查全局配置
4. 使用默认值

配置迁移

版本迁移

系统自动迁移旧配置格式：

function migrateConfig(config: any): Config {
  // v1 到 v2：重命名字段
  if (config.iterm2KeyBindingInstalled) {
    config.shiftEnterKeyBindingInstalled = config.iterm2KeyBindingInstalled
    delete config.iterm2KeyBindingInstalled
  }
  
  // v2 到 v3：更新模型格式
  if (typeof config.model === 'string') {
    config.modelProfiles = {
      default: {
        type: 'anthropic',
        model: config.model
      }
    }
    delete config.model
  }
  
  return config
}

备份和恢复

配置文件在更改前备份：

function saveConfigWithBackup(config: Config) {
  // 创建备份
  const backupPath = `${configPath}.backup`
  fs.copyFileSync(configPath, backupPath)
  
  try {
    // 保存新配置
    fs.writeFileSync(configPath, JSON.stringify(config, null, 2))
  } catch (error) {
    // 错误时从备份恢复
    fs.copyFileSync(backupPath, configPath)
    throw error
  }
}

配置验证

模式验证

使用 Zod 进行运行时验证：

const ConfigSchema = z.object({
  theme: z.enum(['dark', 'light']).optional(),
  modelProfiles: z.record(ModelProfileSchema).optional(),
  modelPointers: ModelPointersSchema.optional(),
  mcpServers: z.record(MCPServerConfigSchema).optional(),
  // ... 其他字段
})

function loadConfig(path: string): Config {
  const raw = JSON.parse(fs.readFileSync(path, 'utf-8'))
  return ConfigSchema.parse(raw)
}

验证规则

1. API 密钥：必须匹配预期格式
2. 模型名称：必须是有效的模型标识符
3. URL：必须是端点的有效 URL
4. 路径：必须是有效的文件系统路径
5. 命令：不得包含危险模式

配置范围

全局范围

影响所有项目：

• 用户偏好（主题、键绑定）
• 模型配置文件和 API 密钥
• 全局 MCP 服务器
• 自动更新程序设置

项目范围

特定于当前项目：

• 工具权限
• 允许的命令
• 项目上下文
• 本地 MCP 服务器
• 成本跟踪

会话范围

当前会话的临时：

• 运行时标志
• 临时权限
• 活动 MCP 连接
• 当前模型选择

高级配置

自定义模型提供商

{
  "modelProfiles": {
    "custom-llm": {
      "type": "custom",
      "name": "我的自定义 LLM",
      "config": {
        "baseURL": "https://my-llm-api.com",
        "apiKey": "custom-key",
        "model": "my-model-v1",
        "headers": {
          "X-Custom-Header": "value"
        }
      }
    }
  }
}

MCP 服务器示例

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_DIRECTORIES": "/home/user/projects"
      }
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "web-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp"
    }
  }
}

上下文配置

{
  "context": {
    "projectType": "typescript",
    "framework": "react",
    "testingFramework": "jest",
    "buildTool": "webpack",
    "customContext": "该项目使用自定义状态管理解决方案..."
  }
}

配置最佳实践

1. 安全性

• 永远不要将 API 密钥提交到版本控制
• 使用环境变量存储机密
• 验证所有配置输入
• 适当限制命令权限

2. 组织

• 为用户偏好保留全局配置
• 为项目特定设置使用项目配置
• 在 README 中记录自定义配置
• 版本控制项目配置

3. 性能

• 在内存中缓存配置
• 仅在文件更改时重新加载
• 使用高效的 JSON 解析
• 最小化配置文件大小

4. 调试

• 为配置问题使用详细模式
• 使用 config list 检查配置
• 加载时验证配置
• 清楚地记录配置错误

故障排除

常见问题

1. 配置未加载

   • 检查文件权限
   • 验证 JSON 语法
   • 确保正确的文件路径

2. 设置未应用

   • 检查配置层次结构
   • 验证环境变量
   • 清除配置缓存

3. 迁移失败

   • 从备份恢复
   • 手动更新格式
   • 检查迁移日志

调试命令

# 显示有效配置
kode config list --effective

# 验证配置
kode config validate

# 重置为默认值
kode config reset

# 显示配置路径
kode config paths

配置系统提供灵活、安全和强大的所有 Kode 设置管理，同时保持向后兼容性和用户友好的默认值。