2026-09-01 10:20 +0800·文章

OpenClaw Docker 部署维护指南：记住「2 个主配置 + 3 个辅助文件」

Docker 部署 OpenClaw 后，日常维护只需抓住核心文件结构。本文把功能配置、密钥配置、常见修改场景和常用命令一次讲清。

核心文件结构

当前真正最重要的是：

/root/local-app/openclaw-walter/
│
├── .env                           ← 密钥、环境变量
├── docker-compose.yml             ← Docker部署层，平时基本不改
│
├── data/openclaw/
│   └── openclaw.json              ← ★ OpenClaw 最核心配置文件
│
├── config/
│   └── .npmrc                     ← npm国内源
│
└── INSTALL_INFO.txt               ← 安装信息/端口/Token

OpenClaw 官方从 ~/.openclaw/openclaw.json 读取主配置；在 Docker 映射里，对应宿主机就是 /root/local-app/openclaw-walter/data/openclaw/openclaw.json。

主要管这两个

1. openclaw.json —— 功能配置

负责：LLM、Hindsight、Browser、微信插件启停、Agent、模型选择、Skill、工具权限、Gateway、MCP，即绝大多数功能配置。

2. .env —— 密钥配置

负责：Gateway Token、LLM API Key、Hindsight Token、npm Registry、Docker 环境变量。

原则：

功能参数进 openclaw.json，密码 / API Key 尽量进 .env。

这样备份、迁移、安全性都会清晰很多。

一、Hindsight 后续怎么改

Hindsight 的主要配置会进入 data/openclaw/openclaw.json，大致结构：

{
  "plugins": {
    "entries": {
      "hindsight-openclaw": {
        "enabled": true,
        "config": {
          "hindsightApiUrl": "http://t.stoneji.cc:18888",
          "dynamicBankId": false,
          "bankId": "walter",
          "autoRecall": true,
          "autoRetain": true,
          "recallBudget": "mid",
          "recallMaxTokens": 1024,
          "enableKnowledgeTools": true
        }
      }
    }
  }
}

推荐修改方式

不要直接 vim JSON，用命令改：

cd /root/local-app/openclaw-walter

# 查看
./openclaw.sh config get plugins.entries.hindsight-openclaw

# 改 Hindsight 地址
./openclaw.sh config set \
  plugins.entries.hindsight-openclaw.config.hindsightApiUrl \
  "http://新的地址:18888"

# 改 Bank
./openclaw.sh config set \
  plugins.entries.hindsight-openclaw.config.bankId \
  "walter"

# 开启 Recall
./openclaw.sh config set \
  plugins.entries.hindsight-openclaw.config.autoRecall \
  true --strict-json

# 开启 Retain
./openclaw.sh config set \
  plugins.entries.hindsight-openclaw.config.autoRetain \
  true --strict-json

# Recall 深度
./openclaw.sh config set \
  plugins.entries.hindsight-openclaw.config.recallBudget \
  "mid"

Recall 深度可选：low（快、省）、mid（均衡，推荐）、high（更深入、更慢）。

Hindsight Token 怎么改

敏感信息放 .env：

nano /root/local-app/openclaw-walter/.env

HINDSIGHT_API_TOKEN=你的token

.env 是 Docker 启动时注入的，改完后必须用 --force-recreate：

docker compose up -d --force-recreate openclaw-gateway

不是普通 restart。

二、LLM 后续怎么改

已专门生成了配置脚本 /root/local-app/openclaw-walter/configure-responses-llm.sh，第一次配置直接跑：

cd /root/local-app/openclaw-walter
./configure-responses-llm.sh

它配置两部分：

.env 保存：

OPENCLAW_CUSTOM_LLM_API_KEY=sk-xxxx

openclaw.json 保存：

{
  "models": {
    "mode": "merge",
    "providers": {
      "custom": {
        "baseUrl": "https://api.xxx.com/v1",
        "api": "openai-responses",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "OPENCLAW_CUSTOM_LLM_API_KEY"
        },
        "timeoutSeconds": 300,
        "models": [
          {
            "id": "gpt-xxx",
            "name": "gpt-xxx",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 32768
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "custom/gpt-xxx"
      }
    }
  }
}

通过 models.providers 配置自定义 Base URL，用 api: openai-responses 指定 Responses API（前提是上游真的支持 /v1/responses）。

三、只改 LLM 地址

不用重跑配置器：

./openclaw.sh config set \
  models.providers.custom.baseUrl \
  "https://api.b.com/v1"

docker compose restart openclaw-gateway

四、换 API Key

nano .env
# OPENCLAW_CUSTOM_LLM_API_KEY=sk-old → sk-new

docker compose up -d --force-recreate openclaw-gateway

传递链路：

.env → Docker Environment → SecretRef → OpenClaw

不要把 API Key 明文写进 openclaw.json。

五、切换默认模型

# 查看
./openclaw.sh models list

# 切换
./openclaw.sh models set custom/gpt-5.6-sol

# 或直接改配置
./openclaw.sh config set \
  agents.defaults.model.primary \
  "custom/gpt-5.6-sol"

模型引用统一使用 provider/model 格式，例如：

custom/gpt-5.6-sol
deepseek/deepseek-v3
dashscope/qwen3-max

六、建议配置两个 LLM Provider

{
  "models": {
    "providers": {
      "main": {
        "baseUrl": "https://api.xxx.com/v1",
        "api": "openai-responses"
      },
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "api": "openai-completions"
      }
    }
  }
}

main/gpt-5.6-sol
deepseek/deepseek-chat

主模型：./openclaw.sh models set main/gpt-5.6-sol

七、微信：插件启停与账号

插件启停在 openclaw.json：

{
  "plugins": {
    "entries": {
      "openclaw-weixin": {
        "enabled": true
      }
    }
  }
}

# 查看
./openclaw.sh config get plugins.entries.openclaw-weixin

# 启用 / 禁用
./openclaw.sh config set plugins.entries.openclaw-weixin.enabled true --strict-json
./openclaw.sh config set plugins.entries.openclaw-weixin.enabled false --strict-json

微信账号 Token 不要手工编辑。登录用：

./wechat-login.sh

本质执行 openclaw channels login --channel openclaw-weixin。扫码成功后，插件自动把账号凭据写入 ~/.openclaw（即宿主机 /root/local-app/openclaw-walter/data/openclaw/）。重新登录直接再跑脚本即可。

多账号：再运行一次 ./wechat-login.sh 添加第二账号，并建议：

./openclaw.sh config set session.dmScope per-account-channel-peer

这样微信账号 A/B 的用户会话不会混。

八、Browser 配置

{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "headless": true
  }
}

./openclaw.sh config get browser
./browser-test.sh

九、docker-compose.yml 什么时候才需要改

只管「基础设施」：端口、Volume、网络。端口实际来自 .env 的 OPENCLAW_HOST_PORT=18789，大部分情况只改 .env 即可，无需动 compose。

十、.npmrc 基本不用碰

位置 /root/local-app/openclaw-walter/config/.npmrc，如：

registry=https://registry.npmmirror.com/

只有 npm 镜像挂了才改。

十一、建议不要直接编辑 openclaw.json

虽然可以 nano data/openclaw/openclaw.json，但官方更推荐：

openclaw config get
openclaw config set
openclaw config validate

自定义 Provider 增量更新用 config set ... --merge，减少误覆盖风险。

日常固定习惯：

cd /root/local-app/openclaw-walter

# 查看
./openclaw.sh config get xxx

# 修改
./openclaw.sh config set xxx value

# 验证
./openclaw.sh config validate

# 重启
docker compose restart openclaw-gateway

十二、记忆规则

                    OpenClaw 配置
                         │
             ┌───────────┴───────────┐
             │                       │
          非敏感配置                密钥
             │                       │
             ▼                       ▼
      openclaw.json                 .env
             │                       │
      Hindsight参数             LLM API KEY
      LLM Provider              Hindsight Token
      默认模型                  Gateway Token
      Browser
      Plugin开关
      Agent
      MCP

再往外：

docker-compose.yml
        ↓
只负责 Docker / 端口 / Volume / 网络

.npmrc
        ↓
只负责 npm / pnpm 下载源

十三、最常用的 10 条命令

cd /root/local-app/openclaw-walter

# 整体状态
./status.sh

# OpenClaw 日志
./logs.sh

# 检查配置
./openclaw.sh config validate

# 看 Hindsight
./openclaw.sh config get plugins.entries.hindsight-openclaw

# 看 LLM
./openclaw.sh config get models

# 看默认模型
./openclaw.sh config get agents.defaults.model

# 模型列表
./openclaw.sh models list

# 微信状态
./openclaw.sh channels status --probe

# 微信重新登录
./wechat-login.sh

# Browser
./browser-test.sh

总结：长期维护的核心文件就是 data/openclaw/openclaw.json，日常通过 ./openclaw.sh config set 修改；.env 只在改 API Key、Token 这些秘密时动。这样后续增加 Hindsight、微信、WPS MCP、Radicale/ntfy MCP、多个 LLM Provider，都不会越来越乱。

参考