docs: fix architecture descriptions and add missing commands

- CLAUDE.md: Clarify 7897/15721 are proxy configs, not services
- USER_ONBOARDING.md: Fix port table, remove misleading proxy services
- REFERENCE.md: Add 30+ missing commands, organize by category
- REFERENCE_en.md: Sync with Chinese version, add all missing commands

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: hotplex-ai

CLAUDE.md

@@ -77,8 +77,10 @@ make clean-volumes    # 清理所有数据卷 (危险!)
 | Service          | Port  | Description                     |
 | ---------------- | ----- | ------------------------------- |
 | openclaw-gateway | 18789 | 主网关服务 (Web UI + WebSocket) |
-| HTTP Proxy       | 7897  | 代理服务 (访问外网)             |
-| Claude API Proxy | 15721 | Claude API 代理                 |
+|                  | 18790 | Bridge WebSocket 桥接           |
+|                  | 18791 | Browser 浏览器调试端口          |
+
+> **代理配置**: 通过 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量配置外部代理，用于访问 Google 和 Claude API
 
 ## Docker Image Variants
 
@@ -133,8 +135,46 @@ GITHUB_TOKEN=xxx
 - Gateway 日志位于容器内 `/tmp/openclaw-gateway.log`
 - 进入容器后可直接运行 `openclaw` 命令
 
+### CI 调试命令
+
+```bash
+# 查看最近的 CI 运行
+gh run list --repo hrygo/openclaw-devkit --limit 5
+
+# 查看特定运行的详细信息
+gh run view <run-id> --repo hrygo/openclaw-devkit
+
+# 获取完整 CI 日志
+gh run view <run-id> --repo hrygo/openclaw-devkit --log
+
+# 搜索日志中的错误
+gh run view <run-id> --repo hrygo/openclaw-devkit --log 2>&1 | grep -E "(ERROR|failed|process \")"
+```
+
 ## Gotchas
 
+### Shell 条件执行陷阱 (Dockerfile)
+
+**问题**: 在 Dockerfile RUN 命令中使用 `&&` 链时，条件测试 `[ condition ] && cmd` 如果返回 false 会中断整个链条。
+
+**错误示例**:
+```dockerfile
+RUN ARCH=$(dpkg --print-architecture) && \
+    JUST_ARCH="${ARCH}" && \
+    [ "$ARCH" = "amd64" ] && JUST_ARCH="x86_64" && \  # 如果 ARCH=arm64，这里不会执行
+    [ "$ARCH" = "arm64" ] && JUST_ARCH="aarch64" && \  # 如果 ARCH=amd64，这里断链!
+    curl ... # 不会执行
+```
+
+**正确做法**: 使用 `if-then-elif-else-fi` 语法：
+```dockerfile
+RUN ARCH=$(dpkg --print-architecture) && \
+    if [ "$ARCH" = "amd64" ]; then JUST_ARCH="x86_64"; \
+    elif [ "$ARCH" = "arm64" ]; then JUST_ARCH="aarch64"; \
+    else JUST_ARCH="${ARCH}"; fi && \
+    curl ...
+```
+
 ### Shell 脚本换行符问题
 
 **症状**: 执行 `make up` 时报错 `env: 'bash\r': No such file or directory`
@@ -173,6 +213,20 @@ git diff --check
 
 ## Dockerfile Development
 
+### 工具架构映射表
+
+不同工具使用不同的架构命名约定，需要正确映射：
+
+| 工具 | amd64 命名 | arm64 命名 | 示例 URL |
+|------|-----------|-----------|----------|
+| yq | `amd64` | `arm64` | `yq_linux_amd64` |
+| just | `x86_64` | `aarch64` | `just-1.47.0-x86_64-unknown-linux-musl.tar.gz` |
+| lazygit | `x86_64` | `arm64` | `lazygit_0.49.0_Linux_x86_64.tar.gz` |
+| gh CLI | `amd64` | `arm64` | `gh_2.67.0_linux_amd64.deb` |
+| Go | `amd64` | `arm64` | `go1.26.1.linux-arm64.tar.gz` |
+
+**推荐**: 在 RUN 命令中使用 `if-then-else-fi` 处理架构差异。
+
 ### Version Verification
 Before using specific versions in Dockerfile, verify download URLs exist:
 ```bash
@@ -191,6 +245,21 @@ docker build --check -f Dockerfile .  # Validate without full build
 - golangci-lint: 1.64.x
 - Java: 21 LTS (via Eclipse Temurin)
 
+### 版本锁定原则
+
+**必须锁定版本**: 所有工具版本必须锁定，避免因上游更新导致构建失败。
+
+```bash
+# ❌ 错误: 动态查询最新版本 (消耗 GitHub API 配额，易触发 rate limit)
+LATEST=$(curl -s https://api.github.com/repos/foo/bar/releases/latest | jq -r '.tag_name')
+
+# ✅ 正确: 锁定具体版本
+ARG TOOL_VERSION=1.2.3
+curl -fsSL "https://github.com/foo/bar/releases/download/v${TOOL_VERSION}/..."
+```
+
+**好处**: 可重复构建 + 避免 API rate limit + 便于追踪回滚
+
 ### Installation Methods
 - **Node.js**: Use NodeSource APT repository (not direct nodejs.org download)
   - More reliable for multi-architecture builds (amd64 + arm64)

docs/REFERENCE.md

@@ -64,24 +64,65 @@ make onboard
 
 ## 3. 常用运维指令
 
+### 快速开始
+
+| 指令 | 说明 |
+| :--- | :--- |
+| `make help` | 显示所有可用命令 |
+| `make install` | 首次安装/初始化环境 |
+| `make onboard` | 交互式配置 (LLM/API) |
+
+### 生命周期管理
+
+| 指令 | 说明 |
+| :--- | :--- |
+| `make up` / `make start` | 启动 openclaw-gateway 服务 |
+| `make down` / `make stop` | 移除容器，保留 Data Volumes |
+| `make restart` | 执行 down + up，刷新配置 |
+| `make status` | 显示容器健康状态、运行时间、端口占用 |
+
+### 构建与更新
+
+| 指令 | 说明 |
+| :--- | :--- |
+| `make build` | 构建标准版镜像 |
+| `make build-go` | 构建 Go 版镜像 |
+| `make build-java` | 构建 Java 版镜像 |
+| `make build-office` | 构建 Office 版镜像 |
+| `make rebuild` | 重建镜像并重启服务 |
+| `make update` | 从 GitHub 同步最新代码 |
+
+### 调试诊断
+
 | 指令 | 说明 |
 | :--- | :--- |
-| `make start` / `make up` | 启动 openclaw-gateway 服务 |
-| `make stop` / `make down` | 移除容器，保留 Data Volumes |
 | `make logs` | 追踪任务分发、WebSocket 状态、错误堆栈 |
 | `make logs-all` | 查看所有容器日志 |
-| `make status` | 显示容器健康状态、运行时间、端口占用 |
-| `make restart` | 执行 down + up，刷新配置 |
 | `make shell` | 进入 Gateway 容器 |
 | `make run` | 交互式进入容器 |
 | `make exec CMD="..."` | 在容器中执行命令 |
 | `make cli CMD="..."` | 执行 OpenClaw CLI 命令 |
+| `make verify` | 验证镜像工具版本 |
+| `make test-proxy` | 测试代理连接 |
+
+### 设备管理
+
+| 指令 | 说明 |
+| :--- | :--- |
+| `make devices` | 列举配对设备 |
+| `make approve` | 批准配对请求 |
+| `make pairing` / `make pair` | 频道配对 |
 | `make dashboard` | 一键直达仪表盘 |
 | `make health` | 检查健康状态 |
+
+### 备份恢复
+
+| 指令 | 说明 |
+| :--- | :--- |
 | `make backup` | 备份配置文件 |
 | `make restore FILE=...` | 恢复配置文件 |
 | `make clean` | 清理容器和悬空镜像 |
-| `make clean-volumes` | 清理所有数据卷 |
+| `make clean-volumes` | 清理所有数据卷 (危险!) |
 
 ---
 

docs/REFERENCE_en.md

@@ -64,13 +64,65 @@ make onboard
 
 ## 3. Common Commands
 
+### Quick Start
+
 | Command | Description |
 | :--- | :--- |
-| `make up` | Start openclaw-gateway service |
-| `make down` | Remove containers, preserve Data Volumes |
-| `make logs` | Trace task distribution, WebSocket states, error stacks |
-| `make status` | Display container health, uptime, port occupancy |
+| `make help` | Show all available commands |
+| `make install` | First-time installation/setup |
+| `make onboard` | Interactive configuration (LLM/API) |
+
+### Lifecycle Management
+
+| Command | Description |
+| :--- | :--- |
+| `make up` / `make start` | Start openclaw-gateway service |
+| `make down` / `make stop` | Remove containers, preserve Data Volumes |
 | `make restart` | Execute down + up, refresh configuration |
+| `make status` | Display container health, uptime, port occupancy |
+
+### Build & Update
+
+| Command | Description |
+| :--- | :--- |
+| `make build` | Build standard image |
+| `make build-go` | Build Go variant image |
+| `make build-java` | Build Java variant image |
+| `make build-office` | Build Office variant image |
+| `make rebuild` | Rebuild image and restart service |
+| `make update` | Sync latest code from GitHub |
+
+### Debugging
+
+| Command | Description |
+| :--- | :--- |
+| `make logs` | Trace task distribution, WebSocket states, error stacks |
+| `make logs-all` | View all container logs |
+| `make shell` | Enter Gateway container |
+| `make run` | Interactive container access |
+| `make exec CMD="..."` | Execute command in container |
+| `make cli CMD="..."` | Execute OpenClaw CLI command |
+| `make verify` | Verify image tool versions |
+| `make test-proxy` | Test proxy connection |
+
+### Device Management
+
+| Command | Description |
+| :--- | :--- |
+| `make devices` | List paired devices |
+| `make approve` | Approve pairing request |
+| `make pairing` / `make pair` | Channel pairing |
+| `make dashboard` | Quick access to dashboard |
+| `make health` | Check health status |
+
+### Backup & Restore
+
+| Command | Description |
+| :--- | :--- |
+| `make backup` | Backup configuration files |
+| `make restore FILE=...` | Restore configuration |
+| `make clean` | Clean containers and dangling images |
+| `make clean-volumes` | Clean all data volumes (dangerous!) |
 
 ---
 

docs/USER_ONBOARDING.md

@@ -112,8 +112,9 @@ make install / make up
 | :---- | :--------------- | :--------------- |
 | 18789 | Gateway Web UI   | HTTP 访问        |
 | 18790 | Bridge           | WebSocket 桥接   |
-| 7897  | HTTP Proxy       | 代理服务（可选） |
-| 15721 | Claude API Proxy | API 代理（可选） |
+| 18791 | Browser          | 浏览器调试端口   |
+
+> **代理配置**: 通过环境变量 `HTTP_PROXY`/`HTTPS_PROXY` 配置外部代理访问
 
 ### 5.3 数据持久化