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

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

## 核心文件结构

当前真正最重要的是：

```text
/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`，大致结构：

```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**，用命令改：

```bash
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`：

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

```ini
HINDSIGHT_API_TOKEN=你的token
```

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

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

不是普通 restart。

## 二、LLM 后续怎么改

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

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

它配置两部分：

**`.env` 保存：**

```ini
OPENCLAW_CUSTOM_LLM_API_KEY=sk-xxxx
```

**`openclaw.json` 保存：**

```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 地址

不用重跑配置器：

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

docker compose restart openclaw-gateway
```

## 四、换 API Key

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

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

传递链路：

```text
.env → Docker Environment → SecretRef → OpenClaw
```

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

## 五、切换默认模型

```bash
# 查看
./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` 格式，例如：

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

## 六、建议配置两个 LLM Provider

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

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

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

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

**插件启停**在 `openclaw.json`：

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

```bash
# 查看
./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 不要手工编辑**。登录用：

```bash
./wechat-login.sh
```

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

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

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

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

## 八、Browser 配置

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

```bash
./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`，如：

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

只有 npm 镜像挂了才改。

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

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

```bash
openclaw config get
openclaw config set
openclaw config validate
```

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

日常固定习惯：

```bash
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
```

## 十二、记忆规则

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

再往外：

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

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

## 十三、最常用的 10 条命令

```bash
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，都不会越来越乱。

## 参考

- [OpenClaw 常见问题](https://docs.openclaw.ai/zh-CN/help/faq)
- [Hindsight 集成文档](https://github.com/vectorize-io/hindsight/blob/main/hindsight-docs/docs-integrations/codex.md)
- [OpenClaw 配置工具与自定义提供商](https://docs.openclaw.ai/zh-CN/gateway/config-tools)
- [OpenClaw 模型与身份验证 FAQ](https://docs.openclaw.ai/zh-CN/help/faq-models)
- [OpenClaw 微信频道](https://docs.openclaw.ai/zh-CN/channels/wechat)