企业官网建设流程全解析

1. Linux 下 Docker 部署 OpenClaw 到底解决什么问题

OpenClaw 是一个把 ClaudeCode 这类编码 Agent 包装成常驻服务的开源项目，社区里习惯叫它“龙虾”。它本身不产出模型能力，而是负责会话管理、工具调用、渠道接入（飞书、Web 仪表盘等），再把请求转发给底层的 Agent 运行时。ClaudeCode 是 Anthropic 官方的命令行编码工具，能力很强，但默认是“一次性交互”的形态，你关掉终端它就停了。把两者接起来，就能得到一个随时在线、能记住上下文、还能从聊天窗口直接派活的编码助手。

apcx 是 ACP（Agent Client Protocol）协议的客户端工具，OpenClaw 通过它来拉起并驱动 ClaudeCode。整条链路是：你在飞书或仪表盘发指令 → OpenClaw Gateway 接收 → 通过 acpx 调用 claude-agent-acp → 后者驱动本机已登录的 ClaudeCode 执行任务 → 结果回传。所以这套方案适合三类人：想让 ClaudeCode 7×24 待命的后端/运维同学、想把编码 Agent 接进团队 IM 的协作场景、以及想在自己 Linux 服务器上搭一套私有 Agent 网关的折腾党。

我实测下来，最容易卡住的不是 OpenClaw 本身，而是容器里没有 ClaudeCode 的登录态、acpx 找不到 claude-agent-acp 的可执行路径、以及权限模式没放开导致写入被拦。这篇就按“宿主机准备 → 容器构建 → 配置初始化 → 验证调用 → 排错”的顺序，把每一步的可复制命令都给你，跟着敲基本能一次跑通。

需要说明的是，ClaudeCode 的模型调用需要一个稳定的 API 入口。如果你本机已经登录了官方账号，可以直接复用；如果想让 OpenClaw 走统一的网关来管理密钥和额度，可以在配置阶段把 Base URL 指向 TaoToken 的 API 地址，后面第 3 节会给到具体写法。

2. 部署前的宿主机准备与 acpx 安装

这一节的目标是让宿主机具备两样东西：一个已经登录可用的 ClaudeCode，以及全局可执行的 acpx 和 claude-agent-acp。容器会通过 volume 把宿主机的配置目录挂进去，所以宿主机这步不能省。

先确认 Node 环境。acpx 和 claude-agent-acp 都是 npm 包，建议 Node 18 以上：

node -v npm -v

如果版本太低，用 nvm 装一个 LTS 版本即可。接着安装 ClaudeCode 本体并完成登录：

npm install -g @anthropic-ai/claude-code claude

第一次运行claude会引导你完成认证，登录成功后会在~/.claude下生成配置和凭据文件。这个目录后面要挂进容器，所以务必确认它存在：

ls -la ~/.claude

然后安装 ACP 相关的两个核心工具。国内网络直接拉 npm 官方源容易超时，用 npmmirror 镜像会快很多：

npm install -g @zed-industries/claude-agent-acp --registry=https://registry.npmmirror.com npm install -g acpx@latest

装完后验证一下可执行文件的位置，这个路径后面写进 acpx 配置要用：

which claude-agent-acp which acpx

正常会输出类似/usr/local/bin/claude-agent-acp。如果你的输出是/usr/bin/...或 nvm 路径，记下来，配置里要改成实际路径，否则容器内会报 command not found。

初始化 acpx 配置，它会生成默认的 config.json：

acpx config init

默认配置在~/.acpx/config.json。我们要覆盖它，把 claude 这个 agent 的命令指向刚才确认的路径，并把权限模式设为自动批准，否则 OpenClaw 派发的写入类操作会被逐个拦截：

cat > ~/.acpx/config.json << 'EOF' { "agents": { "claude": { "command": "/usr/local/bin/claude-agent-acp" } }, "config": { "permissionMode": "approve-all" } } EOF

注意：approve-all意味着 ACP 请求不再逐条询问。这套配置适合本地或内网可信环境，公网暴露的机器请谨慎，最好配合访问白名单。

到这里宿主机侧就绪。你可以先用acpx单独跑一次，确认它能拉起 claude-agent-acp，避免问题被带进容器里排查。

3. 可复制的 Docker 配置与 OpenClaw 初始化

这一节是全文的核心，包含 Dockerfile.custom、docker-compose.yml 的改动、.env 环境变量，以及 OpenClaw 的 onboard 初始化。所有片段都可以直接复制。

先准备 OpenClaw 的源码目录。假设你放在/home/hyn/clawLatest/openclaw，进入该目录后创建.env：

cat > .env << 'EOF' OPENCLAW_CONFIG_DIR=/home/hyn/clawLatest/openclaw/.openclaw OPENCLAW_WORKSPACE_DIR=/home/hyn/clawLatest/openclaw/.openclaw/workspace OPENCLAW_GATEWAY_TOKEN=你的随机token OPENCLAW_GATEWAY_PORT=18789 OPENCLAW_BRIDGE_PORT=18790 OPENCLAW_GATEWAY_BIND=lan OPENCLAW_TZ=Asia/Shanghai CLAUDE_AI_SESSION_KEY= CLAUDE_WEB_SESSION_KEY= CLAUDE_WEB_COOKIE= OPENCLAW_ALLOW_INSECURE_PRIVATE_WS= EOF

生成一个 32 字节的随机 Token 并替换进去，别用弱口令：

export RANDOM_TOKEN=$(openssl rand -hex 32) echo "你的安全 Token：$RANDOM_TOKEN" sed -i "s/OPENCLAW_GATEWAY_TOKEN=你的随机token/OPENCLAW_GATEWAY_TOKEN=$RANDOM_TOKEN/" .env cat .env

接着创建自定义 Dockerfile，基于官方镜像补装 acpx 和 claude-agent-acp：

FROM ghcr.io/openclaw/openclaw:latest USER root RUN npm install -g @zed-industries/claude-agent-acp --registry=https://registry.npmmirror.com RUN npm install -g acpx USER node CMD ["/docker-entrypoint.sh"]

然后改docker-compose.yml，指定用自定义 Dockerfile，并把宿主机的 Claude 和 acpx 配置挂进容器。两个数据卷都要加：

services: openclaw-gateway: build: context: . dockerfile: Dockerfile.custom volumes: - /home/hyn/.claude:/home/node/.claude - /home/hyn/.acpx:/home/node/.acpx

注意：宿主机必须先完成 ClaudeCode 登录，否则容器内/home/node/.claude是空的，ClaudeCode 无法认证。

配置就绪后跑一次初始化向导。用--rm --no-deps起一个临时容器，手动模式、不装守护进程：

docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js onboard --mode local --no-install-daemon

向导里几个关键选择：安全提示选 Yes；安装模式选 Manual；工作区目录回车用默认；模型提供商这里我选的是本地 Ollama，你按实际填 Base URL 和模型名；Gateway 端口 18789、绑定 LAN、认证方式 Token，Token 填.env里生成的那个；Tailscale 暴露选 Off；聊天渠道可以选飞书，也可以先跳过；搜索提供商选 DuckDuckGo；技能依赖先 Skip；各类 API Key 都选 No；Hooks 勾选 boot-md、bootstrap-extra-files、command-logger、session-memory 这四个核心项；zsh 补全按你的 shell 选。

初始化完成后启动：

docker compose up -d --build

首次构建会拉镜像装依赖，慢一点正常。起来后用docker compose ps确认容器状态是 Up。

4. 验证请求：从仪表盘到 ClaudeCode 联动

容器跑起来不代表链路通了，这一节用几条命令把 OpenClaw 到 ClaudeCode 的调用验证一遍。

先进容器：

docker exec -it <容器名称> bash

生成仪表盘链接（不自动打开浏览器）：

openclaw dashboard --no-open

它会输出一个带 Token 的 URL，复制到浏览器打开。首次访问会提示设备未批准，回到容器里查看并批准：

openclaw devices list openclaw devices approve ${DEVICE_ID}

批准后刷新页面就能进仪表盘。接下来是关键的 ACP 配置。编辑~/.openclaw/openclaw.json，加上 acp 段：

{ "acp": { "enabled": true, "backend": "acpx", "defaultAgent": "claude", "allowedAgents": ["claude"] } }

同时在.claude/settings.json里放开权限，否则 OpenClaw 通过 acpx 写入时会被拦：

{ "permissions": { "defaultMode": "bypassPermissions" } }

改完重启容器让配置生效：

docker compose restart

然后在仪表盘的对话窗口里发一条测试指令，比如“列出当前工作区目录下的文件”。如果配置正确，你会看到 OpenClaw 把请求转给 acpx，acpx 拉起 claude-agent-acp，ClaudeCode 执行后把结果回传。整个过程在~/.openclaw/logs/audit/commands.log里有审计记录，出问题时先看这个日志。

如果你希望 OpenClaw 走统一的 API 网关来管理模型调用，可以在模型提供商配置里把 Base URL 指向https://taotoken.net/api，Key 用你在控制台生成的密钥，模型 ID 按需选择。这样密钥集中管理，换模型也不用改容器。

5. 常见报错排查：401、local proxy failed 与路径问题

这一节把几个高频报错和对应处理列出来，都是我在实际部署里踩过的。

401 Unauthorized：多半是 Gateway Token 不匹配。检查.env里的OPENCLAW_GATEWAY_TOKEN和仪表盘 URL 里带的 Token 是否一致，以及 onboard 时填的是不是同一个。改完.env要docker compose up -d重建，光 restart 不会重读环境变量。

local proxy failed / connection refused：通常是 acpx 在容器内找不到 claude-agent-acp。进容器执行which claude-agent-acp，如果为空，说明 Dockerfile 里那步 npm 安装没成功，或者~/.acpx/config.json里的 command 路径写错了。容器内路径是/usr/local/bin/claude-agent-acp，宿主机路径可能不同，配置要以容器内为准。

reading choices 相关报错：一般是 ClaudeCode 没有登录态。确认宿主机~/.claude里有凭据文件，且 volume 映射路径是/home/node/.claude。容器内用户是 node，权限不对也会读不到，必要时chown -R 1000:1000 ~/.claude。

OAuth / 认证失败：如果 ClaudeCode 用的是 OAuth 登录，容器内可能因为缺少浏览器回调而失败。这种情况建议在宿主机完成登录后再挂载，或者改用 API Key 方式认证。

权限被拒 / 写入失败：检查.claude/settings.json的defaultMode是否为bypassPermissions，以及 acpx 配置里的permissionMode是否为approve-all。两处都要放开。

排查顺序建议：先看docker compose logs -f的容器日志，再看~/.openclaw/logs/audit/commands.log的审计日志，最后进容器手动跑acpx确认底层工具本身可用。这样能快速定位是 OpenClaw 层、acpx 层还是 ClaudeCode 层的问题。

6. 把链路用起来：密钥管理与长期运行建议

链路跑通之后，有几件事值得提前做好，能省掉后面很多麻烦。

密钥管理上，Gateway Token 用openssl rand -hex 32生成，别图省事用简单字符串。如果你把 OpenClaw 暴露在内网多台机器访问，建议在反向代理层再加一层认证。模型调用的 Key 如果分散在多个容器里，后期轮换会很痛苦，统一走一个 API 网关（比如把 Base URL 指向https://taotoken.net/api）会清爽很多，密钥在控制台一处管理，容器里只留引用。

长期运行方面，docker compose up -d之后容器默认会随 Docker 重启，但建议加restart: unless-stopped策略，避免宿主机重启后服务没起来。日志会持续增长，command-logger写的审计日志和 session-memory 的会话 JSON 都要定期清理或轮转，否则磁盘会被慢慢吃满。

如果你打算把 OpenClaw 接进飞书做团队协作，群聊策略建议用 Allowlist 白名单模式，只响应指定群，避免机器人被拉进无关群后乱回。DM 策略用 Pairing 配对模式，安全性更好。

最后，ClaudeCode 的版本更新比较频繁，acpx 和 claude-agent-acp 也建议定期升级。升级后记得重新验证一次链路，因为协议细节偶尔会有变动。把这套配置固化成脚本或 compose 文件提交到自己的仓库，下次换机器部署就是几分钟的事。