OpenClaw + OpenCode + 微信插件 Docker 部署完整教程

## 环境概述

- **系统**: macOS (Apple Silicon)
- **架构**: 三容器模式
- `openclaw-gateway`: OpenClaw 官方镜像 (最新版)
- `opencode`: 本地 AI 服务
- `opencode-bridge`: OpenAI 兼容 API 桥接

## 一、安装 Docker Desktop

### 1.1 下载 Docker Desktop

```bash
# Apple Silicon Mac
curl -L -o /tmp/docker.dmg https://desktop.docker.com/mac/main/arm64/Docker.dmg

# Intel Mac
# curl -L -o /tmp/docker.dmg https://desktop.docker.com/mac/main/amd64/Docker.dmg
```

### 1.2 安装 Docker

```bash
# 挂载镜像
hdiutil attach /tmp/docker.dmg -nobrowse

# 复制到 Applications (使用 ditto 避免损坏警告)
ditto /Volumes/Docker/Docker.app /Applications/Docker.app

# 弹出镜像
hdiutil detach /Volumes/Docker
```

### 1.3 启动 Docker Desktop

```bash
open -a Docker
# 或
open "/Applications/Docker.app/Contents/MacOS/Docker Desktop.app"
```

### 1.4 验证 Docker

```bash
# 等待几秒后检查
docker info
```

---

## 二、克隆项目并安装

### 2.1 克隆仓库

```bash
cd ~
git clone https://github.com/Alphabaijinde/openclaw-opencode-bridge.git
```

### 2.2 安装 openclaw 主仓库

```bash
cd ~/openclaw-opencode-bridge/deploy/openclaw-addon
./scripts/install-openclaw-addon.sh ~/openclaw
```

---

## 三、构建 opencode Docker 镜像

### 3.1 构建镜像

```bash
cd ~/openclaw
docker build -t openclaw-opencode-local:latest -f docker/opencode-prebuilt/Dockerfile docker/opencode-prebuilt/
```

---

## 四、启动容器

### 4.1 创建 Docker 网络

```bash
docker network create openclaw_default
```

### 4.2 启动 opencode

```bash
docker run -d \
--name opencode \
--network openclaw_default \
-p 4096:4096 \
openclaw-opencode-local:latest
```

### 4.3 启动 opencode-bridge

```bash
docker run -d \
--name opencode-bridge \
--network openclaw_default \
-p 8787:8787 \
-e HOST=0.0.0.0 \
-e PORT=8787 \
-e BRIDGE_API_KEY=<your-api-key> \
-e OPENCODE_BASE_URL=http://opencode:4096 \
-e OPENCODE_AUTH_MODE=basic \
-e OPENCODE_AUTH_USERNAME=opencode \
-e OPENCODE_AUTH_PASSWORD= \
-e OPENCODE_PROVIDER_ID=opencode \
-e OPENCODE_MODEL_ID=minimax-m2.5-free \
-e OPENAI_MODEL_ID=opencode-local \
-e OPENAI_TIMEOUT_MS=180000 \
ghcr.io/alphabaijinde/openclaw-opencode-bridge:bridge-only
```

**说明**: `OPENAI_TIMEOUT_MS=180000` 设置 180 秒超时（可调整为更大值），避免模型响应慢时超时。

### 4.4 启动 openclaw-gateway

```bash
cd ~/openclaw
docker compose up -d openclaw-gateway
```

### 4.5 将容器加入网络

```bash
docker network connect openclaw_default opencode
docker network connect openclaw_default opencode-bridge
```

---

## 五、配置 OpenClaw 模型

### 5.1 获取宿主机用户名

```bash
echo $HOME
```

### 5.2 修改配置文件

```bash
# 备份配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# 使用 Node.js 修改配置（将 YOUR_USERNAME 替换为你的用户名）
node -e '
const fs = require("fs");
const config = JSON.parse(fs.readFileSync(process.env.HOME + "/.openclaw/openclaw.json", "utf8"));
config.models = {
mode: "merge",
providers: {}
};
config.models.providers["opencode-bridge"] = {
baseUrl: "http://host.docker.internal:8787/v1",
apiKey: "c05da3ac40c3fecab1f16ba0ada668a233f6eb6fca0504c3",
api: "openai-completions",
models: [{ id: "opencode-local", name: "Opencode Local" }]
};
config.agents = {
defaults: {
model: { primary: "opencode-bridge/opencode-local" },
compaction: { mode: "safeguard" }
}
};
fs.writeFileSync(process.env.HOME + "/.openclaw/openclaw.json", JSON.stringify(config, null, 2));
console.log("Config updated");
'
```

**关键点**:
- `host.docker.internal` 是 Docker 容器访问宿主机的特殊域名
- 模型配置中 `name` 字段必须存在

---

## 六、安装微信插件

### 6.1 在 Gateway 容器内安装 openclaw CLI

```bash
docker exec openclaw-openclaw-gateway-1 npm install -g openclaw@latest --prefix /home/node/.npm-global
```

### 6.2 安装微信插件

```bash
docker exec openclaw-openclaw-gateway-1 bash -c 'export PATH=/home/node/.npm-global/bin:$PATH && openclaw plugins install @tencent-weixin/openclaw-weixin'
```

### 6.3 启用插件

```bash
docker exec openclaw-openclaw-gateway-1 bash -c 'export PATH=/home/node/.npm-global/bin:$PATH && openclaw plugins enable openclaw-weixin'
```

---

## 七、微信扫码登录

### 7.1 执行登录命令

```bash
docker exec -it openclaw-openclaw-gateway-1 bash -c 'export PATH=/home/node/.npm-global/bin:$PATH && openclaw channels login --channel openclaw-weixin'
```

**注意**: 必须使用 `-it` 参数才能显示二维码。

### 7.2 扫码授权

终端会显示二维码，用微信扫描并在手机上确认授权。

### 7.3 验证登录

```bash
docker exec openclaw-openclaw-gateway-1 bash -c 'export PATH=/home/node/.npm-global/bin:$PATH && openclaw channels list'
```

应该显示:
```
Chat channels:
- openclaw-weixin xxx-im-bot: configured, enabled
```

---

## 八、重启 Gateway

**重要**: 微信登录后必须重启 Gateway 才能启动消息监控。

```bash
docker restart openclaw-openclaw-gateway-1
```

### 8.1 验证监控启动

```bash
docker logs openclaw-openclaw-gateway-1 --tail 30 | grep -i "weixin\|monitor"
```

应该看到:
```
[xxx-im-bot] starting weixin provider
weixin monitor started
```

---

## 九、验证完整功能

### 9.1 检查所有容器状态

```bash
docker ps
```

### 9.2 测试 Bridge API

```bash
curl -s -H "Authorization: Bearer <your-api-key>" \
-X POST http://127.0.0.1:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"opencode-local","messages":[{"role":"user","content":"hello"}],"max_tokens":30}'
```

### 9.3 访问 Dashboard

```
http://127.0.0.1:18789
```

---

## 十、常见问题

### Q1: "应用已损坏" 错误

**原因**: macOS Gatekeeper 阻止了非 App Store 应用。

**解决**:
```bash
xattr -cr /Applications/Docker.app
```

### Q2: npm 安装权限错误

**原因**: 容器内 `/usr/local/lib/node_modules` 无写权限。

**解决**: 使用 `--prefix` 安装到用户目录:
```bash
npm install -g openclaw --prefix /home/node/.npm-global
```

### Q3: 微信登录后不响应消息

**原因**: Gateway 未重启，消息监控未启动。

**解决**:
```bash
docker restart openclaw-openclaw-gateway-1
```

### Q4: 模型配置验证失败

**原因**: 缺少 `name` 字段或配置格式错误。

**解决**: 确保配置中包含:
```json
"models": [{ "id": "opencode-local", "name": "Opencode Local" }]
```

### Q5: LLM 请求超时

**原因**: opencode 模型响应慢，默认超时 60 秒不够。

**症状**: 日志显示 `error=LLM request timed out`

**解决**: 重启 bridge 并设置更长超时:
```bash
docker stop opencode-bridge
docker rm opencode-bridge
docker run -d \
--name opencode-bridge \
--network openclaw_default \
-p 8787:8787 \
-e HOST=0.0.0.0 \
-e PORT=8787 \
-e BRIDGE_API_KEY=<your-api-key> \
-e OPENCODE_BASE_URL=http://opencode:4096 \
-e OPENCODE_AUTH_MODE=basic \
-e OPENCODE_AUTH_USERNAME=opencode \
-e OPENCODE_AUTH_PASSWORD= \
-e OPENCODE_PROVIDER_ID=opencode \
-e OPENCODE_MODEL_ID=minimax-m2.5-free \
-e OPENAI_MODEL_ID=opencode-local \
-e OPENAI_TIMEOUT_MS=180000 \
ghcr.io/alphabaijinde/openclaw-opencode-bridge:bridge-only
```

**注意**: 如果仍超时，可继续增加超时值（如 300000）。

### Q6: 容器间网络不通

**症状**: bridge 无法连接 opencode。

**解决**: 确保所有容器在同一个网络:
```bash
docker network create openclaw_default
docker network connect openclaw_default opencode
docker network connect openclaw_default opencode-bridge
```

### Q7: 配置文件中 baseUrl 无法通过 CLI 设置

**原因**: CLI 配置需要完整对象结构。

**解决**: 直接编辑 JSON 配置文件:
```bash
# 备份
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# 使用 Node.js 或手动编辑
node -e '...'
```

---

## 十一、容器管理命令

```bash
# 查看所有容器
docker ps -a

# 查看运行中的容器
docker ps

# 查看容器日志
docker logs openclaw-openclaw-gateway-1 --tail 50

# 实时查看日志
docker logs -f openclaw-openclaw-gateway-1

# 重启容器
docker restart openclaw-openclaw-gateway-1

# 进入容器
docker exec -it openclaw-openclaw-gateway-1 bash

# 停止并删除容器
docker stop openclaw-openclaw-gateway-1
docker rm openclaw-openclaw-gateway-1

# 重建所有容器
cd ~/openclaw && docker compose down && docker compose up -d

# 查看网络
docker network ls
docker network inspect openclaw_default
```

### 查看详细日志

```bash
# Gateway 详细日志
docker exec openclaw-openclaw-gateway-1 cat /tmp/openclaw/openclaw-*.log

# 过滤关键信息
docker exec openclaw-openclaw-gateway-1 cat /tmp/openclaw/openclaw-*.log | grep -i "weixin\|inbound\|outbound\|sent OK\|error"
```

---

## 十二、关键路径和端口

| 组件 | 容器名 | 端口 | 说明 |
|------|--------|------|------|
| OpenClaw Gateway | openclaw-openclaw-gateway-1 | 18789 | Web UI |
| opencode | opencode | 4096 | 本地 AI |
| opencode-bridge | opencode-bridge | 8787 | API 桥接 |

### 配置目录
| 路径 | 说明 |
|------|------|
| `~/.openclaw/` | OpenClaw 配置 |
| `~/.opencode/` | opencode 配置 |
| `~/openclaw/` | openclaw 仓库 |

---

## 十三、日志分析

### 正常日志

```
# 微信监控启动
[xxx-im-bot] starting weixin provider
weixin monitor started

# 收到消息
inbound: from=xxx@im.wechat bodyLen=5 hasMedia=false

# 发送成功
outbound: text sent OK to=xxx@im.wechat
```

### 问题日志

```bash
# LLM 超时
error=LLM request timed out
rawErrorPreview=504 opencode timeout after 60000ms

# 插件未加载
plugins.allow is empty; discovered non-bundled plugins may auto-load

# 容器重启
signal SIGTERM received
```

---

## 十四、版本信息

- OpenClaw: 2026.3.13
- opencode: 1.1.51
- 微信插件: @tencent-weixin/openclaw-weixin 1.0.2

---

## 总结

本教程采用**三容器模式**部署:

1. **openclaw-gateway**: 使用官方最新镜像，确保插件兼容性
2. **opencode**: 本地 AI 服务，提供免费模型
3. **opencode-bridge**: OpenAI 兼容 API 桥接，连接 OpenClaw 和 opencode

**关键点**:
- 使用 `ditto` 安装 Docker.app 避免损坏警告
- npm 全局安装使用 `--prefix` 避免权限问题
- 微信登录后必须重启 Gateway
- bridge 设置 `OPENAI_TIMEOUT_MS=120000` 避免超时
- 配置文件在宿主机 `$HOME/.openclaw/`