第4讲：配置文件详解，掌控OpenClaw的核心参数

github star gitee star atomgit star PyPI Downloads AI 编程 AI 交流群

大家好，我是正在实战各种AI项目的程序员晚枫。

今天我们来深入OpenClaw的配置系统。配置文件是OpenClaw的灵魂，掌握它你就能完全掌控Gateway的行为。

配置文件位置

主配置文件位于：

1
~/.openclaw/openclaw.json

使用以下命令查看当前配置：

1
openclaw config show

编辑配置：

1
2
3
4
5
# 用默认编辑器打开
openclaw config edit

# 或手动编辑
nano ~/.openclaw/openclaw.json

配置文件结构概览

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "gateway": {          // Gateway核心配置
    "port": 18789,
    "host": "127.0.0.1",
    "auth": {...}
  },
  "providers": {        // AI模型提供商
    "anthropic": {...},
    "openai": {...}
  },
  "channels": {         // 消息通道
    "telegram": {...},
    "whatsapp": {...}
  },
  "tools": {            // 工具配置
    "exec": {...},
    "browser": {...}
  },
  "sessions": {         // 会话管理
    "maxHistory": 100,
    "ttl": 3600
  },
  "logging": {          // 日志配置
    "level": "info",
    "file": true
  }
}

核心配置项详解

1. Gateway配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "gateway": {
    "port": 18789,              // 服务端口
    "host": "127.0.0.1",        // 绑定地址
    "publicUrl": null,          // 公网访问地址（可选）
    
    "auth": {
      "type": "token",          // 认证方式
      "token": "your-secret-token"  // 访问令牌
    },
    
    "cors": {
      "enabled": true,          // 是否允许跨域
      "origins": ["*"]          // 允许的域名
    }
  }
}

安全建议：生产环境务必设置强token，并限制origins。

2. 模型提供商配置

Anthropic (Claude)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "providers": {
    "anthropic": {
      "enabled": true,
      "apiKey": "sk-ant-api03-xxxxx",
      "defaultModel": "claude-3-opus-20240229",
      "models": {
        "claude-3-opus": {
          "id": "claude-3-opus-20240229",
          "maxTokens": 4096,
          "contextWindow": 200000
        },
        "claude-3-sonnet": {
          "id": "claude-3-sonnet-20240229",
          "maxTokens": 4096,
          "contextWindow": 200000
        }
      }
    }
  }
}

OpenAI (GPT)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "providers": {
    "openai": {
      "enabled": true,
      "apiKey": "sk-xxxxx",
      "baseUrl": "https://api.openai.com/v1",
      "defaultModel": "gpt-4",
      "models": {
        "gpt-4": {"id": "gpt-4", "maxTokens": 8192},
        "gpt-3.5-turbo": {"id": "gpt-3.5-turbo", "maxTokens": 4096}
      }
    }
  }
}

国内模型示例（Moonshot）

1
2
3
4
5
6
7
8
9
10
{
  "providers": {
    "moonshot": {
      "enabled": true,
      "apiKey": "your-moonshot-key",
      "baseUrl": "https://api.moonshot.cn/v1",
      "defaultModel": "moonshot-v1-8k"
    }
  }
}

3. 通道安全配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "xxxxxx:yyyyyy",
      "allowFrom": [],           // 白名单用户ID
      "groups": {
        "requireMention": true,  // 群组中需要@才响应
        "allowedGroups": []      // 允许的群组ID
      }
    },
    
    "whatsapp": {
      "enabled": true,
      "sessionName": "default",
      "allowFrom": ["+86138xxxxxxxx"],  // 只允许特定手机号
      "pairingCode": null
    }
  }
}

4. 工具权限配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "tools": {
    "exec": {
      "enabled": true,
      "sandbox": true,           // 沙盒模式
      "allowedCommands": ["ls", "cat", "grep", "curl"],
      "blockedCommands": ["rm", "dd", "mkfs"],
      "workingDirectory": "~/.openclaw/sandbox"
    },
    
    "browser": {
      "enabled": true,
      "headless": true,          // 无头模式
      "timeout": 30000,          // 超时时间(ms)
      "allowedDomains": ["*"],   // 允许访问的域名
      "blockedDomains": []
    },
    
    "read": {
      "enabled": true,
      "allowedPaths": ["~/projects", "~/documents"],
      "blockedPaths": ["~/.ssh", "~/.aws"]
    },
    
    "write": {
      "enabled": false,          // 默认禁用写入
      "allowedPaths": ["~/projects/temp"],
      "requireApproval": true    // 需要人工确认
    }
  }
}

5. 会话与记忆配置

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "sessions": {
    "maxHistory": 100,           // 最大历史消息数
    "ttl": 86400,               // 会话过期时间(秒)
    "pruneInterval": 3600,      // 清理间隔
    
    "memory": {
      "enabled": true,
      "storage": "file",        // file/redis
      "path": "~/.openclaw/state/memory"
    }
  }
}

常用配置模板

模板1：本地开发环境

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "gateway": {
    "port": 18789,
    "auth": {"type": "none"}
  },
  "providers": {
    "anthropic": {
      "enabled": true,
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  },
  "tools": {
    "exec": {"enabled": true, "sandbox": false},
    "write": {"enabled": true}
  }
}

模板2：生产服务器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "gateway": {
    "port": 18789,
    "host": "0.0.0.0",
    "auth": {
      "type": "token",
      "token": "${GATEWAY_TOKEN}"
    }
  },
  "providers": {
    "anthropic": {"enabled": true, "apiKey": "${ANTHROPIC_KEY}"},
    "openai": {"enabled": true, "apiKey": "${OPENAI_KEY}"}
  },
  "tools": {
    "exec": {
      "enabled": true,
      "sandbox": true,
      "allowedCommands": ["ls", "cat", "ps"]
    },
    "write": {"enabled": false}
  }
}

模板3：多模型负载均衡

1
2
3
4
5
6
7
{
  "routing": {
    "strategy": "failover",     // failover/round-robin/random
    "providers": ["anthropic", "openai", "moonshot"],
    "fallback": "openai"
  }
}

配置热重载

修改配置后，无需重启Gateway：

1
2
3
4
5
# 发送重载信号
openclaw gateway reload

# 或发送SIGHUP
kill -HUP $(pgrep -f openclaw-gateway)

部分配置（如port、host）仍需重启生效。

环境变量注入

敏感信息建议使用环境变量：

1
2
3
4
# .bashrc 或 .zshrc
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export OPENAI_API_KEY="sk-xxxxx"
export GATEWAY_TOKEN="my-secret-token"

配置文件中引用：

1
2
3
4
5
6
7
{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  }
}

下节预告

下一讲我们将学习模型提供商配置，详细讲解如何接入Claude、GPT、Gemini以及国产大模型。

👉 继续阅读：第5讲-模型提供商配置与多模型接入

💬 加入学习交流群

配置问题？加群讨论：

👉 点击加入交流群

推荐：AI Python编程实战营

🎁 限时福利：送《利用Python进行数据分析》实体书

👉 点击了解详情

—## 📚 完整学习路线这是OpenClaw入门课程的第X讲。查看完整课程大纲：👉 **OpenClaw入门课程大纲**课程包含30讲，从安装部署到实战项目，带你全面掌握OpenClaw。

课程导航

上一篇： 第3讲-Control UI详解

下一篇： 第5讲-模型提供商配置与多模型接入

PS：配置文件是OpenClaw的命脉，建议备份好你的openclaw.json。

进群

嗨，扫码 进群

微信

扫一扫，分享到微信

微信分享二维码
本站总访问量次

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置：

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true

编程博主，全网粉丝30w+，开源项目：python-office，我的微信：python-office