第 4 章：认识配置文件 openclaw.json

适合人群：已经能用 OpenClaw 聊天，想进一步自定义的你 本章目标：学会找到、看懂和修改配置文件

4.1 openclaw.json 在哪里

OpenClaw 的所有设置都存放在一个叫 openclaw.json 的文件里。它不在程序目录中，而是在你的用户主目录下的一个隐藏文件夹里。

具体位置：

~/.openclaw/openclaw.json

等等，波浪号（~）是什么？ 在电脑术语里，~ 代表你的"用户主目录"。

macOS：/Users/你的用户名/

Windows：C:\Users\你的用户名\

Linux：/home/你的用户名/

如何打开这个文件？

方法一：命令行直接打开（最推荐）

openclaw config edit

这会直接用系统自带的文本编辑器打开配置文件。

方法二：终端里查看（便于复制）

openclaw config get

方法三：手动查找打开

如果找不到文件，可以用这个命令看看配置文件的路径：

openclaw config path

会输出类似 ~/.openclaw/openclaw.json 这样的完整路径。

然后用任意文本编辑器（记事本、VS Code、Sublime 等）打开它。

🔒 如果文件不存在？ 说明你没做过任何自定义配置。OpenClaw 使用的是默认设置，一切正常。你可以自己创建这个文件，或者运行 openclaw onboard 自动生成。

4.2 配置文件结构概览

openclaw.json 用的是 JSON5 格式——跟常见的 JSON 差不多，但更友好：

✅ 可以写注释（以 // 开头）
✅ 末尾可以多一个逗号
✅ 键名可以不用引号

一个典型的配置文件大概长这样：

{
  // === AI 模型配置 ===
  providers: {
    anthropic: {
      apiKey: "sk-ant-xxx",
    },
  },

  // === Agent（AI 助手）配置 ===
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
      },
    },
  },

  // === 网关配置 ===
  gateway: {
    port: 18789,
    host: "127.0.0.1",
  },

  // === 聊天通道配置 ===
  channels: {
    telegram: {
      enabled: false,
    },
    whatsapp: {
      enabled: false,
    },
  },
}

配置文件的五个核心模块

模块	作用	必填？
`providers`	配置 AI 模型提供商的 API Key	是
`agents`	配置 AI 助手的行为、模型、技能	可选
`gateway`	配置网关的端口、地址等	可选
`channels`	配置聊天通道（Telegram、微信等）	可选
`tools`	配置工具（搜索、浏览器等）	可选

4.3 配置 AI 模型提供商

OpenClaw 支持 35 种以上的 AI 模型提供商。下面演示怎么配置。

单模型配置（最简单）

如果你只用一种模型，只需要配置一个 API Key：

{
  providers: {
    anthropic: {
      apiKey: "sk-ant-你申请到的APIKey",
    },
  },
}

多模型配置（高级）

如果你想在不同场景用不同模型，可以配置多个提供商：

{
  providers: {
    anthropic: {
      apiKey: "sk-ant-xxx",
    },
    openai: {
      apiKey: "sk-proj-xxx",
    },
    deepseek: {
      apiKey: "sk-xxx",
    },
  },

  agents: {
    defaults: {
      model: {
        // 主要模型（最聪明、最贵的）
        primary: "anthropic/claude-sonnet-4-6",
        // 备用模型（如果主要模型忙或出错，自动切换）
        fallbacks: ["openai/gpt-5.4", "deepseek/deepseek-chat"],
      },
    },
  },
}

模型名称格式：

所有模型都用 提供商/模型名 的格式，例如：

提供商	模型引用名
Anthropic Claude	`anthropic/claude-sonnet-4-6`
OpenAI GPT	`openai/gpt-5.4`
DeepSeek	`deepseek/deepseek-chat`
Google Gemini	`google/gemini-2.5-flash`
Grok (xAI)	`xai/grok-3`

用命令行配置

如果你不习惯手写 JSON，也可以用命令来配置：

# 设置 Anthropic API Key
openclaw config set providers.anthropic.apiKey "sk-ant-xxx"

# 设置主要模型
openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4-6"

# 查看当前配置
openclaw config get agents.defaults.model

配置本地模型（不联网也能用）

如果你没有云厂商的 API Key，也可以连接本地运行的 AI 模型。这需要额外装一个叫 Ollama 的软件。

安装 Ollama：

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.ai/install.sh | sh

拉取一个模型（比如阿里的 Qwen2）：

ollama pull qwen2.5:7b

然后在 OpenClaw 配置中指向它：

{
  providers: {
    ollama: {
      baseUrl: "http://127.0.0.1:11434",
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama/qwen2.5:7b",
      },
    },
  },
}

这样你的 AI 助手就完全离线运行了，数据不出本地。

4.4 配置 Gateway 端口和绑定地址

Gateway 默认在 127.0.0.1:18789 监听，也就是只能本机访问。

修改端口

如果 18789 被其他程序占用了，可以换一个：

{
  gateway: {
    port: 20000,  // 换成你喜欢的端口
  },
}

允许局域网访问

如果你想让家里其他设备（比如手机、平板）也能访问：

{
  gateway: {
    port: 18789,
    host: "0.0.0.0",  // 监听所有网络接口
  },
}

⚠️ 安全提醒：设为 0.0.0.0 意味着局域网内所有人都能访问你的 AI 助手。建议只在家里内网开，并设置访问密码。

设置访问密码

{
  gateway: {
    auth: {
      password: "你的密码",
    },
  },
}

设了密码后，在浏览器访问 Dashboard 时会提示输入密码。

4.5 配置工具策略

OpenClaw 的强大之处在于 AI 能调用工具——搜网页、操作文件、运行代码等。

默认工具策略

默认情况下，AI 可以使用所有内置工具。你也可以按需开关：

{
  agents: {
    defaults: {
      // 只允许这些工具
      skills: ["web-search", "weather", "filesystem"],
    },
  },
}

如果你想完全禁用某个工具：

{
  tools: {
    exec: {
      enabled: false,  // 禁用终端执行工具
    },
  },
}

常用工具列表

工具名	用途	建议
`web-search`	网上搜索信息	✅ 推荐打开
`browser`	控制浏览器	谨慎打开
`exec`	执行电脑命令	⚠️ 只有信得过的场景才开
`filesystem`	读写文件	✅ 基本操作
`skills`	调用技能插件	✅ 核心能力

配置 Web 搜索工具

{
  tools: {
    "web-search": {
      provider: "brave",  // 可选：brave, google, perplexity, duckduckgo 等
      apiKey: "你的Brave搜索API Key",
    },
  },
}

4.6 修改后重启

配置文件改完后，需要重启 Gateway 才能生效。

重启命令

openclaw gateway restart

检查是否生效

openclaw gateway status

确认显示"Running"就对了。

热重载（无需重启）

OpenClaw 的一个贴心设计是：它会自动监听配置文件的变化，很多改动无需重启就会生效。

但有些配置改动（如端口、模型提供商）还是需要手动重启的。如果不确定，直接重启最保险：

openclaw gateway restart

配置验证

修改配置后，如果 Gateway 启动失败，运行：

openclaw doctor

它会告诉你配置哪里有问题。也可以自动修复：

openclaw doctor --fix

为什么重启后 Gateway 不启动？ 最常见的原因是 JSON 格式错误 —— 比如漏了逗号、多写了花括号。另外 OpenClaw 对配置的检查非常严格，不认识或格式不对的字段会导致拒绝启动。 openclaw doctor --fix 通常能解决大部分问题。

本章小结

✅ 配置文件位于 ~/.openclaw/openclaw.json
✅ 用 openclaw config edit 可直接编辑
✅ 支持 35+ 种 AI 模型，用 提供商/模型名 格式配置
✅ 可以改端口、设密码、自定义工具策略
✅ 修改后 openclaw gateway restart 生效
✅ 用 openclaw doctor --fix 自动修复配置问题

现在你已经学会配置 OpenClaw 了！从下一章开始，我们会进入进阶篇，学习如何连接聊天通道（Telegram、微信等）、配置多 Agent、以及打造自己的自动化工作流。

← 第 3 章 · 第一次聊天第 5 章 · Agent 工作区 →

系统教程，帮你把工具用好，再回到任务中。浏览任务方案 →