OpenClaw 配置指南

了解 OpenClaw 配置文件结构和自定义选项

OpenClaw 配置指南

本文档介绍 OpenClaw 的配置文件结构和自定义选项，帮助您根据需求调整 AI 助手的行为。

配置目录结构

创建 OpenClaw 工作空间后，系统会自动生成 .openclaw/ 配置目录：

.openclaw/
├── openclaw.json      # 主配置文件
├── agents/            # 自定义 Agent 目录
├── tools/             # 自定义工具目录
├── knowledge/         # 知识库文件目录
├── workspace/         # 工作目录
└── memory/            # 记忆存储目录

主配置文件

openclaw.json 结构

系统会根据您选择的模型和组织配置自动生成 openclaw.json 文件。以下是一个典型的配置示例：

{
  "meta": {
    "lastTouchedVersion": "2026.2.13",
    "lastTouchedAt": "2026-02-28T05:53:33.912Z"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "anthropic": {
        "baseUrl": "${ANTHROPIC_BASE_URL}",
        "apiKey": "${ANTHROPIC_AUTH_TOKEN}",
        "api": "anthropic",
        "models": [
          { "id": "claude-sonnet-4-5", "name": "Claude Sonnet 4.5" },
          { "id": "claude-opus-4-6", "name": "Claude Opus 4.6" }
        ]
      },
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "${OPENAI_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "gpt-4", "name": "GPT-4" },
          { "id": "gpt-3.5-turbo", "name": "GPT-3.5 Turbo" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-5"
      },
      "workspace": "/workspace",
      "maxConcurrent": 4
    },
    "list": [
      { "id": "main" }
    ]
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": true }
      }
    }
  }
}

注意：配置文件由系统自动生成，会根据组织的 Channel 配置自动包含可用的 Provider 和模型。

配置说明

meta 元信息

models 模型配置

Provider 配置项：

agents Agent 配置

gateway Gateway 配置

环境变量引用

安全的密钥管理

配置文件中的 API Key 使用环境变量引用格式：

{
  "baseUrl": "${ANTHROPIC_BASE_URL}",
  "apiKey": "${ANTHROPIC_AUTH_TOKEN}"
}

安全性保证：

1. API Key 和 baseUrl都不会明文存储在配置文件中
2. 环境变量仅在 Sandbox 容器内注入
3. 不会暴露给前端或日志

支持的环境变量

系统会根据组织配置自动注入以下环境变量：

修改配置

通过文件编辑器

1. 进入工作空间的知识库
2. 导航到 .openclaw/openclaw.json
3. 使用内置编辑器修改配置
4. 保存后配置自动生效

配置生效

修改配置后，Gateway 会在下次启动时加载新配置。如需立即生效：

1. 进入工作空间设置
2. 切换到"AgentOS"标签页
3. 点击"重启 Gateway"

自定义 Agent

创建自定义 Agent

在 .openclaw/agents/ 目录下创建 Agent 配置文件：

# my-agent.md

---
name: 我的自定义 Agent
description: 专注于特定任务的 Agent
model: anthropic/claude-sonnet-4-5
---

你是一个专业的 [领域] 助手，专注于 [任务]。

## 能力
- 能力 1
- 能力 2

## 限制
- 限制 1
- 限制 2

Agent 配置项

自定义工具

创建自定义工具

在 .openclaw/tools/ 目录下创建工具文件：

// my-tool.ts

export const myTool = {
  name: 'my_tool',
  description: '工具描述',
  parameters: {
    type: 'object',
    properties: {
      input: { type: 'string', description: '输入参数' }
    },
    required: ['input']
  },
  execute: async (params: { input: string }) => {
    // 工具实现
    return { result: `处理结果: ${params.input}` };
  }
};

知识库集成

添加知识文件

将知识文件放入 .openclaw/knowledge/ 目录：

.openclaw/knowledge/
├── company-info.md      # 公司信息
├── product-docs/        # 产品文档目录
│   ├── feature-a.md
│   └── feature-b.md
└── faq.md               # 常见问题

知识库使用

OpenClaw 会自动索引 knowledge 目录中的文件，在对话中提供相关信息。

Gateway 管理

自动启动

Gateway 在以下情况自动启动：

• 首次向 OpenClaw 助手发送消息
• Sandbox 容器启动时检测到 .openclaw/ 目录

健康检查

系统定期检查 Gateway 健康状态：

• 检查间隔：30 秒
• 健康检查端点：http://localhost:18789/health

自动重启

Gateway 异常退出时会自动重启：

• 最大重试次数：3 次
• 重试间隔：1s, 2s, 4s（指数退避）

手动重启

在工作空间设置的"AgentOS"标签页：

1. 找到"Gateway 管理"部分
2. 点击"重启 Gateway"按钮
3. 等待重启完成

高级配置

修改默认模型

编辑 openclaw.json 中的 agents.defaults.model.primary：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-4"
      }
    }
  }
}

添加自定义 Provider

在 models.providers 中添加新的 Provider：

{
  "models": {
    "providers": {
      "custom-provider": {
        "baseUrl": "https://your-api.com/v1",
        "apiKey": "${CUSTOM_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "model-1", "name": "Model 1" }
        ]
      }
    }
  }
}

调整并发限制

修改 agents.defaults.maxConcurrent：

{
  "agents": {
    "defaults": {
      "maxConcurrent": 8
    }
  }
}

常见问题

Q：配置修改后不生效？

1. 确保配置文件语法正确（JSON 格式）
2. 重启 Gateway 使配置生效
3. 检查错误日志

Q：API Key 配置错误？

1. 确保使用正确的环境变量名
2. 检查组织是否已配置对应的 Channel
3. 联系管理员确认 API Key 有效性

Q：自定义 Agent 不工作？

1. 确保文件放在正确的目录
2. 检查 Agent 配置语法
3. 重启 Gateway 后重试

相关文档

• OpenClaw 概述 - 了解 OpenClaw 集成架构
• 创建 OpenClaw 助手 - 快速入门指南
• 模型配置 - 组织级模型配置