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 元信息

字段	说明
lastTouchedVersion	最后修改时的 OpenClaw 版本
lastTouchedAt	最后修改时间

models 模型配置

字段	说明
mode	模型合并模式，通常为 "merge"
providers	AI 模型提供商配置

Provider 配置项：

字段	说明
baseUrl	API 基础 URL
apiKey	API 密钥（支持环境变量引用）
api	API 类型（anthropic/openai-completions）
models	可用模型列表

agents Agent 配置

字段	说明
defaults.model.primary	默认使用的模型
defaults.workspace	工作目录路径
defaults.maxConcurrent	最大并发数
list	Agent 列表

gateway Gateway 配置

字段	说明
port	Gateway 端口（固定 18789）
mode	运行模式（local）
bind	绑定地址（loopback）
http.endpoints	启用的 HTTP 端点

环境变量引用

安全的密钥管理

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

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

安全性保证：

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

支持的环境变量

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

变量名	说明
ANTHROPIC_AUTH_TOKEN	Anthropic API 密钥（Knodo 和 Anthropic Provider）
ANTHROPIC_BASE_URL	api key的base url

修改配置

通过文件编辑器

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

配置生效

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

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

自定义 Agent

创建自定义 Agent

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

# my-agent.md

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

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

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

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

Agent 配置项

字段	说明
name	Agent 名称
description	Agent 描述
model	使用的模型

自定义工具

创建自定义工具

在 .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"标签页：

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

高级配置

修改默认模型

编辑 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：配置修改后不生效？

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

Q：API Key 配置错误？

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

Q：自定义 Agent 不工作？

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

OpenClaw 配置指南

OpenClaw 配置指南

配置目录结构

主配置文件

openclaw.json 结构

配置说明

meta 元信息

models 模型配置

agents Agent 配置

gateway Gateway 配置

环境变量引用

安全的密钥管理

支持的环境变量

修改配置

通过文件编辑器

配置生效

自定义 Agent

创建自定义 Agent

Agent 配置项

自定义工具

创建自定义工具

知识库集成

添加知识文件

知识库使用

Gateway 管理

自动启动

健康检查

自动重启

手动重启

高级配置

修改默认模型

添加自定义 Provider

调整并发限制

常见问题

Q：配置修改后不生效？

Q：API Key 配置错误？

Q：自定义 Agent 不工作？

相关文档