第8章配置文件：openclaw.json解剖

🎯 本章目标：学完这章，你能理解配置文件的层次结构，独立修改配置

⏱️ 预计时间：25分钟

📋 前置要求：已完成第3章（基础安装）

本章你将学会什么

配置文件的位置和编辑方式
配置分层：全局→Agent→Channel 的优先级（后写覆盖先写）
关键字段详解：gateway、agents、channels、tools
多环境配置（家用/公司/云主机）
修改后的验证方法

8.1 配置文件在哪里

8.1.1 配置文件路径

OpenClaw的配置文件位于：

macOS/Linux：

~/.openclaw/openclaw.json

Windows：

%APPDATA%\openclaw\openclaw.json

8.1.2 如何编辑

方式一：使用CLI命令（推荐）

# 读取整个配置的某个特定值（例如读取网关端口）
openclaw config get gateway.port

# 设置配置项
openclaw config set key value

# 示例：修改Gateway端口
openclaw config set gateway.port 18790

方式二：直接编辑文件

# 用你喜欢的编辑器打开
nano ~/.openclaw/openclaw.json

# 或
vim ~/.openclaw/openclaw.json

# 或VS Code
code ~/.openclaw/openclaw.json

⚠️ 注意：直接编辑文件前，建议先备份
Terminal window
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

操作提醒：手动改完配置后，记得执行一次 openclaw gateway restart，否则你看到的仍是旧配置效果。

8.2 配置分层：优先级规则

OpenClaw 的配置是分层的。你可以先记一句：越靠近“当前这次启动/命令”的设置，优先级越高。

默认值
    ↓
全局配置（~/.openclaw/openclaw.json）
    ↓
Workspace配置（workspace/.openclaw/config.json）
    ↓
环境变量
    ↓
命令行参数

越往下，优先级越高。

8.2.1 示例

假设全局配置设置了：

{
  "gateway": {
    "port": 18789
  }
}

但启动时指定了：

openclaw gateway start --port 18790

最终使用的端口是 18790（命令行参数优先级最高）。

8.3 关键字段详解

8.3.1 gateway：网关配置

{
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1",
    "cors": {
      "enabled": true,
      "origins": ["http://localhost:3000"]
    },
    "auth": {
      "type": "token",
      "secret": "your-secret-token"
    }
  }
}

字段说明：

字段	说明	默认值
port	Gateway监听端口	18789
host	绑定地址	127.0.0.1
cors.enabled	是否启用跨域	true
cors.origins	允许的跨域来源	[]
auth.type	认证类型	token
auth.secret	认证密钥	随机生成

修改示例：

# 修改端口
openclaw config set gateway.port 18790

# 允许外部访问（谨慎！）
openclaw config set gateway.host 0.0.0.0

8.3.2 models：模型配置

{
  "models": {
    "primary": {
      "provider": "kimi",
      "model": "kimi-k2.5",
      "apiKey": "sk-xxx",
      "temperature": 0.7,
      "maxTokens": 4000
    },
    "fallbacks": [
      {
        "provider": "minimax",
        "model": "MiniMax-M2.5",
        "apiKey": "xxx"
      }
    ]
  }
}

字段说明：

字段	说明	示例
provider	模型提供商	kimi/minimax/glm/openai
model	模型名称	kimi-k2.5
apiKey	API密钥	sk-xxx
temperature	创造性（0-2）	0.7
maxTokens	最大token数	4000

temperature说明：

0.0：最确定，适合代码、数学
0.7：平衡，适合一般对话
1.0+：更有创意，适合写作

8.3.3 agents：智能体配置

{
  "agents": {
    "list": [
      {
        "id": "main",
        "name": "Assistant",
        "tools": {
          "profile": "coding",
          "allow": ["group:fs", "group:web"],
          "deny": ["group:runtime"]
        }
      }
    ]
  }
}

字段说明：

字段	说明
name	Agent显示名称
tools.profile	工具预设（minimal/coding/messaging/full）
tools.allow	允许使用的工具（支持 `group:*`）
tools.deny	禁止使用的工具（优先级高于allow）

tools.profile选项：

profile	包含的工具	适用场景
minimal	仅 `session_status`	安全优先
coding	`group:fs`、`group:runtime`、`group:sessions`、`group:memory`、`image`	开发助手
messaging	`group:messaging` + 会话基础工具	聊天机器人
full	不限制（等同未设置）	仅限已做好权限隔离时使用

8.3.4 channels：渠道配置

{
  "channels": {
    "feishu": {
      "type": "feishu",
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "domain": "feishu.cn",
      "privateChat": "pairing",
      "groupChat": "enabled",
      "requireMention": true,
      "allowFrom": [],
      "groupAllowFrom": []
    }
  }
}

字段说明：

字段	说明	选项
type	渠道类型	feishu/telegram/…
privateChat	私聊策略	pairing/allowlist/all
groupChat	群聊开关	enabled/disabled
requireMention	是否需要@	true/false
allowFrom	私聊白名单	用户ID列表
groupAllowFrom	群聊白名单	群ID列表

8.4 多环境配置

8.4.1 场景：家用/公司/云主机

假设你有三个使用场景：

家用Mac：轻量使用，KIMI模型
公司电脑：团队协作，MiniMax模型
云主机：24小时运行，多模型备份

8.4.2 方案：使用Workspace配置

OpenClaw支持Workspace级别的配置，覆盖全局配置。

目录结构：

~/projects/
  ├── home/           # 家用项目
  │   └── .openclaw/
  │       └── config.json
  ├── company/        # 公司项目
  │   └── .openclaw/
  │       └── config.json
  └── server/         # 云主机项目
      └── .openclaw/
          └── config.json

家用配置示例（~/projects/home/.openclaw/config.json）：

{
  "models": {
    "primary": {
      "provider": "kimi",
      "model": "kimi-k2.5",
      "apiKey": "sk-home-xxx"
    }
  },
  "agents": {
    "default": {
      "tools": {
        "profile": "minimal"
      }
    }
  }
}

公司配置示例（~/projects/company/.openclaw/config.json）：

{
  "models": {
    "primary": {
      "provider": "minimax",
      "model": "MiniMax-M2.5",
      "apiKey": "sk-company-xxx"
    }
  },
  "channels": {
    "feishu": {
      "privateChat": "pairing",
      "groupChat": "enabled",
      "requireMention": true
    }
  }
}

使用方法：

# 在家用目录下使用家用配置
cd ~/projects/home
openclaw gateway start

# 在公司目录下使用公司配置
cd ~/projects/company
openclaw gateway start

8.5 修改后的验证

8.5.1 验证配置是否可加载

# 先做整体诊断（会检查关键配置）
openclaw doctor

# 再看网关状态
openclaw status

8.5.2 查看生效配置

# 检查配置（交互式控制面板）
openclaw configure

# 查看模型状态（含鉴权摘要）
openclaw models status

8.5.3 测试配置

# 测试模型连接
openclaw models status --probe

# 测试Channel连接
openclaw channels status --probe

8.5.4 回滚配置

如果配置出错，快速回滚：

# 从备份恢复
cp ~/.openclaw/openclaw.json.backup ~/.openclaw/openclaw.json

# 重启Gateway
openclaw gateway restart

本章小结

配置文件的核心要点：

知道在哪 —— ~/.openclaw/openclaw.json
理解分层 —— 全局→Workspace→环境变量→命令行
关键字段 —— gateway、models、agents、channels
多环境 —— 用Workspace配置隔离不同场景
改前备份 —— 养成备份的好习惯

下一步：第9章，学习安全与沙箱配置。

动手试试

找到你的配置文件，打开看看结构
用openclaw configure重新检查并保存当前主要配置
尝试修改一个配置项（如temperature）
运行openclaw doctor验证配置
备份你的配置文件

第8章 配置文件：openclaw.json解剖

本章你将学会什么

8.1 配置文件在哪里

8.1.1 配置文件路径

8.1.2 如何编辑

8.2 配置分层：优先级规则

8.2.1 示例

8.3 关键字段详解

8.3.1 gateway：网关配置

8.3.2 models：模型配置

8.3.3 agents：智能体配置

8.3.4 channels：渠道配置

8.4 多环境配置

8.4.1 场景：家用/公司/云主机

8.4.2 方案：使用Workspace配置

8.5 修改后的验证

8.5.1 验证配置是否可加载

8.5.2 查看生效配置

8.5.3 测试配置

8.5.4 回滚配置

本章小结

动手试试

第8章配置文件：openclaw.json解剖