OpenClaw 完整配置详解

配置文件概览

本文档详细说明 OpenClaw 三个核心配置文件的所有配置项及其含义。

一、openclaw.json（全局主配置）

文件位置：~/.openclaw/openclaw.json

作用：OpenClaw 的全局主配置文件，存储全局设置、模型配置、认证信息、通道配置等核心参数。

1.1 meta - 元数据

"meta": {
  "lastTouchedVersion": "2026.3.11",
  "lastTouchedAt": "2026-03-13T23:35:19.040Z"
}

作用：记录配置文件的版本和时间戳，用于配置迁移和兼容性检查。

1.2 wizard - 向导记录

"wizard": {
  "lastRunAt": "2026-03-12T13:52:29.349Z",
  "lastRunVersion": "2026.3.11",
  "lastRunCommand": "onboard",
  "lastRunMode": "local"
}

作用：记录初始设置向导的执行历史，避免重复运行向导。

1.3 auth - 认证配置

"auth": {
  "profiles": {
    "kimi-coding:default": {
      "provider": "kimi-coding",
      "mode": "api_key"
    }
  }
}

作用：定义认证档案，引用 auth-profiles.json 中的详细认证信息。主配置只存档案名，不存实际密钥。

档案名称格式：提供商:别名，如 kimi-coding:default、openai:personal

1.4 models - 模型配置

"models": {
  "mode": "merge",
  "providers": {
    "kimi-coding": {
      "baseUrl": "https://api.kimi.com/coding/",
      "api": "anthropic-messages",
      "models": [...]
    }
  }
}

模型定义字段：

1.5 agents - 智能体配置

"agents": {
  "defaults": {
    "model": { "primary": "kimi-coding/k2p5" },
    "workspace": "D:\\Users\\...\\workspace"
  },
  "list": [{ "id": "main", "tools": { "profile": "full" } }]
}

1.6 tools - 工具配置

"tools": {
  "profile": "coding",
  "web": { "search": { "provider": "brave" } }
}

1.7 commands - 命令配置

1.8 session - 会话配置

1.9 hooks - 钩子配置

内置钩子：boot-md、bootstrap-extra-files、command-logger、session-memory

1.10 channels - 通讯通道

支持的通道：telegram、discord、slack、whatsapp、signal、line、irc、webchat

1.11 gateway - 网关配置

二、auth-profiles.json（认证档案）

文件位置：~/.openclaw/agents/main/agent/auth-profiles.json

作用：存储 API 认证密钥的独立文件，将敏感信息与主配置分离，提高安全性。

2.1 version - 版本号

配置文件格式版本，用于未来兼容性升级。

2.2 profiles - 认证档案

"profiles": {
  "kimi-coding:default": {
    "type": "api_key",
    "provider": "kimi-coding",
    "key": "sk-kimi-..."
  }
}

档案名称格式：提供商:别名

• • 例如：kimi-coding:default、kimi-coding:backup、openai:work

2.3 lastGood - 最后成功档案

记录每个提供商最后一次成功认证的档案，用于快速恢复。

2.4 usageStats - 使用统计

作用：追踪档案使用情况，帮助排查问题（如某个 Key 是否过期）。

三、models.json（Agent专属模型）

文件位置：~/.openclaw/agents/main/agent/models.json

作用：为特定 Agent 定义专属的模型配置，扩展或覆盖全局模型设置。

3.1 providers - 模型提供商

"providers": {
  "kimi-coding": {
    "baseUrl": "https://api.kimi.com/coding/",
    "api": "anthropic-messages",
    "headers": { "User-Agent": "claude-code/0.1.0" },
    "models": [...],
    "apiKey": "KIMI_API_KEY"
  }
}

3.2 models - 模型定义

四、三配置文件关系图

┌─────────────────────────────────────────────────────────┐
│                    openclaw.json                        │
│                   【全局主配置】                          │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐        ┌─────────────┐                │
│  │   auth      │        │   models    │                │
│  │  profiles   │        │  (全局部分)  │                │
│  │             │        │             │                │
│  │ 引用档案名    │        │  基础模型配置 │                │
│  │ (不含密钥)   │        │             │                │
│  └──────┬──────┘        └──────┬──────┘                │
│         │                      │                        │
│         ▼                      ▼                        │
│  ┌─────────────────┐  ┌──────────────────────────────┐  │
│  │ auth-profiles   │  │        models.json           │  │
│  │    .json        │  │      【Agent 专属】            │  │
│  │  【密钥存储】     │  │                              │  │
│  │                 │  │  扩展/覆盖全局模型配置           │  │
│  │  实际 API Key    │  │  专属提供商参数               │  │
│  │  多档案管理      │  │  定制化模型列表               │  │
│  │  使用统计       │  │                              │  │
│  └─────────────────┘  └──────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

五、配置加载流程

启动 Agent: main
    │
    ├─ 1. 加载 openclaw.json
    │   ├─ 读取全局配置
    │   ├─ 获取默认模型：kimi-coding/k2p5
    │   └─ 获取认证档案名：kimi-coding:default
    │
    ├─ 2. 加载 auth-profiles.json
    │   └─ 解析档案 "kimi-coding:default"
    │       └─ 获取实际 API Key
    │
    ├─ 3. 加载 models.json
    │   └─ 合并到全局模型配置
    │       ├─ 保留全局提供商
    │       ├─ 应用专属覆盖
    │       └─ 添加新提供商
    │
    └─ 4. 初始化完成
        ├─ 工作目录：D:\Users\...\workspace
        ├─ 使用模型：kimi-coding/k2p5
        ├─ API Key：从 auth-profiles 获取
        └─ 可用模型：全局 + 专属合并结果

六、最佳实践

6.1 安全建议

1. 1. 文件权限设置

   # Linux/macOS
   chmod 600 ~/.openclaw/agents/main/agent/auth-profiles.json
   
   # Windows: 右键 → 属性 → 安全 → 仅当前用户访问

2. 2. 敏感信息隔离
• • openclaw.json → 可版本控制（不含敏感信息）
• • auth-profiles.json → 加密备份或排除版本控制
• • models.json → 可版本控制
3. 3. 使用环境变量

   export KIMI_API_KEY="sk-xxx"
   export OPENAI_API_KEY="sk-yyy"

6.2 多环境配置

# 开发环境
export KIMI_API_KEY="sk-dev-xxx"

# 生产环境  
export KIMI_API_KEY="sk-prod-xxx"

6.3 迁移步骤

1. 1. 复制 openclaw.json 到新机器
2. 2. 在新机器重新生成 auth-profiles.json（安全考虑）
3. 3. 复制 models.json 保持 Agent 行为一致

七、配置文件总览