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

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

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

🚀 开篇：配置文件是什么？

打个比方：

想象OpenClaw是一辆汽车，配置文件就是汽车的操控面板。

  • Gateway配置 → 引擎和传动系统
  • 通道配置 → 车门和窗户
  • 工具配置 → 各种功能按钮
  • 会话配置 → 行车电脑

学会调配置，就等于学会了调车。

配置文件位置

主配置文件位置：

1
~/.openclaw/openclaw.json

常用操作命令：

命令作用
openclaw config show查看当前配置
openclaw config edit编辑配置（用默认编辑器）
cat ~/.openclaw/openclaw.json直接查看配置文件
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
  }
}

各模块说明：

模块作用修改频率
gateway服务端口、安全设置低
providersAI模型API配置中
channels聊天平台连接配置中
tools工具权限和参数高
sessions会话行为配置低
logging日志级别和输出低

核心配置项详解

1. Gateway配置 ⭐

Gateway是OpenClaw的核心服务，这部分配置决定服务如何运行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "gateway": {
    "port": 18789,              // 服务端口（默认18789，不要改）
    "host": "127.0.0.1",        // 绑定地址
    "publicUrl": null,          // 公网访问地址（可选）

    "auth": {
      "type": "token",          // 认证方式
      "token": "your-secret-token"  // 访问令牌
    },

    "cors": {
      "enabled": true,          // 是否允许跨域
      "origins": ["*"]          // 允许的域名
    }
  }
}

配置说明：

参数说明建议
port服务端口默认18789，不要随便改
host监听地址开发用127.0.0.1，生产用0.0.0.0
publicUrl公网地址有域名或公网IP时填写
token访问令牌生产环境务必设置强密码

⚠️ 安全建议：

生产环境务必设置强token，不要用默认或简单密码。
建议使用至少32位的随机字符串。

2. 模型提供商配置 ⭐⭐

这部分决定AI的"大脑"是什么。

Anthropic (Claude)

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
  "providers": {
    "anthropic": {
      "enabled": true,
      "apiKey": "sk-ant-api03-xxxxx",
      "baseUrl": "https://api.anthropic.com",

      "defaultModel": "claude-3-opus",
      "defaultParams": {
        "max_tokens": 4096,
        "temperature": 0.7
      },

      "models": {
        "claude-3-opus": {
          "id": "claude-3-opus-20240229",
          "name": "Claude 3 Opus",
          "description": "最强推理能力，适合复杂任务",
          "maxTokens": 4096,
          "contextWindow": 200000,
          "inputPrice": 0.015,
          "outputPrice": 0.075
        },
        "claude-3-sonnet": {
          "id": "claude-3-sonnet-20240229",
          "name": "Claude 3 Sonnet",
          "description": "平衡性能与成本，日常使用推荐",
          "maxTokens": 4096,
          "contextWindow": 200000,
          "inputPrice": 0.003,
          "outputPrice": 0.015
        },
        "claude-3-haiku": {
          "id": "claude-3-haiku-20240307",
          "name": "Claude 3 Haiku",
          "description": "快速响应，成本最低，适合简单任务",
          "maxTokens": 4096,
          "contextWindow": 200000,
          "inputPrice": 0.00025,
          "outputPrice": 0.00125
        }
      }
    }
  }
}

价格参考（每1000 tokens，注意是美元）：

  • Opus：输入$0.015，输出$0.075 → 贵但最强
  • Sonnet：输入$0.003，输出$0.015 → 性价比最高 ✅
  • Haiku：输入$0.00025，输出$0.00125 → 便宜快

OpenAI (GPT)

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
{
  "providers": {
    "openai": {
      "enabled": true,
      "apiKey": "sk-xxxxx",
      "baseUrl": "https://api.openai.com/v1",

      "defaultModel": "gpt-4",

      "models": {
        "gpt-4": {
          "id": "gpt-4",
          "maxTokens": 8192,
          "contextWindow": 8192
        },
        "gpt-4-turbo": {
          "id": "gpt-4-turbo-preview",
          "maxTokens": 4096,
          "contextWindow": 128000
        },
        "gpt-3.5-turbo": {
          "id": "gpt-3.5-turbo",
          "maxTokens": 4096,
          "contextWindow": 16385
        }
      }
    }
  }
}

国内模型示例（Moonshot/Kimi）

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
{
  "providers": {
    "moonshot": {
      "enabled": true,
      "apiKey": "your-moonshot-key",
      "baseUrl": "https://api.moonshot.cn/v1",
      "defaultModel": "moonshot-v1-8k",

      "models": {
        "moonshot-v1-8k": {
          "id": "moonshot-v1-8k",
          "maxTokens": 8192,
          "contextWindow": 8192,
          "description": "日常对话推荐，便宜"
        },
        "moonshot-v1-32k": {
          "id": "moonshot-v1-32k",
          "maxTokens": 32768,
          "contextWindow": 32768,
          "description": "长文本分析"
        },
        "moonshot-v1-128k": {
          "id": "moonshot-v1-128k",
          "maxTokens": 131072,
          "contextWindow": 131072,
          "description": "超长上下文，适合文档分析"
        }
      }
    }
  }
}

💡 我的推荐：国内用户直接用Moonshot，有免费额度，速度快，不需要魔法。

其他国内模型配置

智谱GLM：

1
2
3
4
5
6
7
8
9
10
{
  "providers": {
    "glm": {
      "enabled": true,
      "apiKey": "xxxxx.xxxxx",
      "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
      "defaultModel": "glm-4"
    }
  }
}

阿里千问：

1
2
3
4
5
6
7
8
9
10
{
  "providers": {
    "qwen": {
      "enabled": true,
      "apiKey": "your-api-key",
      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "defaultModel": "qwen-plus"
    }
  }
}

3. 通道安全配置 ⭐⭐

通道配置决定AI能从哪些平台接收消息。

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
32
{
  "tools": {
    "exec": {
      "enabled": true,
      "sandbox": true,           // 沙盒模式
      "allowedCommands": ["ls", "cat", "grep", "curl", "python3"],
      "blockedCommands": ["rm", "dd", "mkfs", "sudo", "chmod"],
      "workingDirectory": "~/.openclaw/sandbox",
      "requireApproval": false
    },

    "browser": {
      "enabled": true,
      "headless": true,          // 无头模式
      "timeout": 30000,          // 超时时间(ms)
      "allowedDomains": ["*"],   // 允许访问的域名
      "blockedDomains": []
    },

    "read": {
      "enabled": true,
      "allowedPaths": ["~/projects", "~/documents"],
      "blockedPaths": ["~/.ssh", "~/.aws", "~/.env"]
    },

    "write": {
      "enabled": false,          // 默认禁用写入
      "allowedPaths": ["~/projects/temp"],
      "requireApproval": true    // 需要人工确认
    }
  }
}

⚠️ 生产环境安全建议：

  • exec：启用沙盒，只允许必要命令
  • write：生产环境禁用，或开启审批
  • read：设置允许和禁止路径

5. 会话与记忆配置

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "sessions": {
    "maxHistory": 100,           // 最大历史消息数
    "ttl": 86400,               // 会话过期时间(秒)，默认24小时
    "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
23
{
  "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}"},
    "moonshot": {"enabled": true, "apiKey": "${MOONSHOT_KEY}"}
  },
  "tools": {
    "exec": {
      "enabled": true,
      "sandbox": true,
      "allowedCommands": ["ls", "cat", "ps", "grep", "curl"]
    },
    "write": {"enabled": false}
  }
}

模板3：多模型负载均衡

同时配置多个模型，自动故障切换：

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

策略说明：

策略说明适用场景
failover主模型失败时切换到备用追求稳定性 ✅
round-robin轮询使用各模型追求均衡
random随机选择测试环境

配置热重载 ⚡

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

1
2
3
4
5
# 方法1：使用命令重载
openclaw gateway reload

# 方法2：发送信号
kill -HUP $(pgrep -f openclaw-gateway)

⚠️ 注意：

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

环境变量注入 🔐

敏感信息（API密钥、密码等）不要直接写在配置文件中，使用环境变量：

在Shell中设置环境变量

1
2
3
4
5
6
7
# macOS/Linux - 添加到 ~/.bashrc 或 ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
echo 'export OPENAI_API_KEY="sk-xxxxx"' >> ~/.zshrc
echo 'export GATEWAY_TOKEN="my-secret-token-min-32-chars"' >> ~/.zshrc

# 生效
source ~/.bashrc  # 或 source ~/.zshrc

在配置文件中引用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    }
  },
  "gateway": {
    "auth": {
      "token": "${GATEWAY_TOKEN}"
    }
  }
}

配置文件不再包含明文密钥，更安全。

配置验证与备份

验证配置是否正确

1
2
3
4
5
openclaw config validate
# 如果输出 OK，说明配置格式正确

# 或直接查看配置
openclaw config show

备份配置

1
2
3
4
5
6
# 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 恢复配置
cp ~/.openclaw/openclaw.json.backup ~/.openclaw/openclaw.json
openclaw gateway restart

💡 建议：每次大改动前都备份配置，这样改坏了可以一键还原。

下节预告

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

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

💬 加入学习交流群

配置问题？加群讨论：

👉 点击加入交流群

推荐：AI Python编程实战营

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

👉 点击了解详情

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

课程导航

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

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

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

💬 联系我

平台账号/链接
微信扫码加好友
微博@程序员晚枫
知乎@程序员晚枫
抖音@程序员晚枫
小红书@程序员晚枫
B 站Python 自动化办公社区

主营业务：AI 编程培训、企业内训、技术咨询

🎓 AI 编程实战课程

想系统学习 AI 编程？程序员晚枫的 AI 编程实战课 帮你从零上手！