Skip to content

docker-compose

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docker-compose

README.md

Docker Compose Runbook

This runbook is for the current working setup in this repository:

  • AuthSec SSO in front of OpenClaw
  • OpenClaw gateway running in Docker
  • browser access through the proxy at http://localhost:8080
  • optional Discord plugin
  • Windows local-machine access through a paired OpenClaw node

It is written for Windows + PowerShell because that is the environment this repo is currently using.

Architecture

The local stack is:

  • proxy: AuthSec login, session handling, user identity injection, OpenClaw HTTP and WebSocket proxying
  • openclaw: OpenClaw gateway in Docker
  • run-openclaw-node.ps1: helper to connect your Windows machine as a node

The gateway is exposed only on loopback for node pairing:

  • proxy UI: http://localhost:8080
  • gateway loopback: ws://127.0.0.1:18789

Prerequisites

  • Docker Desktop
  • PowerShell
  • Node.js + npm
  • An AuthSec application and working AuthSec credentials
  • At least one LLM provider key for OpenClaw

Optional:

  • Discord bot token
  • Brave Search API key if you want the search tool instead of just browser automation

1. Configure .env

Open deploy/docker-compose/.env and set the values for your environment.

Minimum fields to review:

OPENCLAW_GATEWAY_TOKEN=<random-token>
PROXY_PUBLIC_BASE_URL=http://localhost:8080
SESSION_HMAC_SECRET=<random-secret>
SESSION_SECURE_COOKIE=false

AUTHSEC_MODE=authsec
AUTHSEC_ISSUER_URL=https://oauth.prod.authsec.ai
AUTHSEC_CLIENT_ID=<your-authsec-client-id>
AUTHSEC_CLIENT_SECRET=<your-authsec-client-secret>
AUTHSEC_ADMIN_EMAIL=<your-email>

AUTHSEC_JWT_SECRET=<native-authsec-secret>
AUTHSEC_BASE_URL=https://prod.api.authsec.ai
AUTHSEC_LOGIN_URL=https://oauth.prod.authsec.ai/oauth2/auth

OPENAI_API_KEY=<optional>
ANTHROPIC_API_KEY=<optional>
OPENCLAW_MODEL=openai/gpt-4o

Notes:

  • PROXY_PUBLIC_BASE_URL should stay http://localhost:8080 for the local flow.
  • SESSION_SECURE_COOKIE=false is correct for local HTTP.
  • Keep real secrets out of Git.

2. Configure OpenClaw

The active OpenClaw config is deploy/docker-compose/openclaw-config/openclaw.json.

Important current behavior:

  • gateway auth mode is token
  • local Control UI is allowed on http://localhost
  • device auth is relaxed for localhost development
  • tools.exec defaults to the Windows node named RitamKrKundu

If you want Discord enabled, set the bot token in channels.discord.token.

If you want a different default node name for local exec, update:

"tools": {
  "exec": {
    "host": "node",
    "node": "RitamKrKundu"
  }
}

3. Start the Stack

From deploy/docker-compose:

docker compose up -d --build

If you only need to refresh the two main services later:

docker compose up -d --build --force-recreate openclaw proxy

Check logs:

docker compose logs -f openclaw proxy

4. Log In Through AuthSec

Open:

http://localhost:8080

Then:

  1. Sign in with AuthSec.
  2. Wait for the OpenClaw Control UI to load.
  3. Ask who am I?

Expected result:

  • OpenClaw should answer with your authenticated email and user ID.

That identity comes from the proxy writing user context into the shared workspace before the request reaches OpenClaw.

5. Pair the Windows Node

The Docker gateway can proxy chat by itself, but it cannot launch Windows apps like Notepad, Teams, or Explorer directly. For that, your Windows machine must be connected as an OpenClaw node.

Install the OpenClaw CLI once:

npm install -g openclaw@latest

From the repo root, start the node host:

powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode run

If this is the first time, it may print pairing required.

6. Approve the Pairing Request

If pairing is required, use another terminal and approve it from the gateway container.

List pending requests:

docker exec openclaw-gateway sh -lc "node /app/openclaw.mjs devices list --json"

Approve the request:

docker exec openclaw-gateway sh -lc "node /app/openclaw.mjs devices approve <request-id> --json"

Then rerun:

powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode run

Keep that terminal open. The node must stay running to keep Windows local-machine access available.

Check node status:

openclaw.cmd nodes status

Expected result:

  • Known: 1
  • Paired: 1
  • Connected: 1

7. Unlock Windows Exec Approvals

Even after the node connects, OpenClaw may still deny Windows commands until the node-side exec approvals are opened up for this single-user setup.

From the repo root:

powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode unlock
powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode status

The helper:

  • writes a permissive local ~/.openclaw/exec-approvals.json
  • pushes the same policy live to the connected node
  • sets security=full
  • sets ask=off
  • sets askFallback=full

If you still see SYSTEM_RUN_DENIED: approval required, run -Mode unlock again while the node is connected.

8. Try Real Commands

Once AuthSec login, node connection, and unlock are all done, these are good tests:

Identity:

  • who am I?

Windows apps:

  • Open Notepad on node RitamKrKundu
  • Open my Downloads folder on node RitamKrKundu
  • Open the file C:\Users\<you>\Downloads\test.txt on node RitamKrKundu

Browser:

  • Use the browser on node RitamKrKundu and open https://authsec.ai

Discord:

  • Read the last 5 messages from #general
  • Send a message to channel:123456789012345678

9. How Discord Works Here

The Discord plugin can be enabled in deploy/docker-compose/openclaw-config/openclaw.json.

Important:

  • a connected Discord bot is not enough by itself
  • OpenClaw needs a real target for reads and sends
  • a server or guild name alone is not a valid read target

Use:

  • #channel-name
  • channel:<channel-id>
  • user:<user-id>

Do not expect:

  • only the guild name, for example Ritam Server

10. How Browser and Search Differ

Browser automation:

  • can work through the OpenClaw browser tool or the connected node/browser capability
  • does not require a search API key

Search tool:

  • is different from browser automation
  • needs a configured provider such as Brave Search

If you want Brave Search too, configure the appropriate key in OpenClaw's web tool settings.

11. Common Problems

who am I? does not show the logged-in user

Check:

  • AuthSec login completed successfully
  • proxy logs show user context written
  • the proxy was rebuilt after the identity changes

Useful command:

docker compose logs -f proxy

node required

Your Windows node is not connected right now.

Run:

powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode run
openclaw.cmd nodes status

SYSTEM_RUN_DENIED: approval required

The node is connected, but its exec approvals are still restrictive.

Run:

powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode unlock

gateway timeout after 30000ms

This usually means one of these:

  • the node process is not currently running
  • the node was connected but got stuck
  • the command tried to launch through the wrong host before defaults refreshed

Try:

openclaw.cmd nodes status
powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode run
powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode unlock

Discord says target is unknown

Use a channel or user target:

  • #general
  • channel:<id>
  • user:<id>

Teams, Explorer, Notepad, or Edge do not open

Remember:

  • Docker cannot launch Windows GUI apps by itself
  • /host-home is only a mounted folder
  • real GUI app launch must go through the connected Windows node

12. Rebuild and Restart Commands

From deploy/docker-compose:

docker compose up -d --build --force-recreate openclaw proxy
docker compose logs -f openclaw proxy
docker compose down

From the repo root:

go test ./internal/proxy ./internal/auth

13. Security Warning

The current local setup is intentionally relaxed so http://localhost:8080 works during development:

  • insecure localhost Control UI auth is enabled
  • device auth is disabled for localhost
  • node exec is opened up for a single trusted operator

That is fine for local testing on your own machine.

Before exposing this publicly over HTTPS, you should:

  • re-enable normal device auth
  • remove insecure localhost-only shortcuts
  • review token and provider-key handling
  • rethink whether unrestricted node exec belongs on the same gateway

中文版本

Docker Compose 操作手册

本操作手册适用于本仓库当前正常运行的配置：

  • AuthSec SSO 位于 OpenClaw 前面
  • OpenClaw 网关在 Docker 中运行
  • 通过代理在 http://localhost:8080 进行浏览器访问
  • 可选的 Discord 插件
  • 通过已配对的 OpenClaw 节点进行 Windows 本机访问

本文档为 Windows + PowerShell 环境编写，因为这是本仓库当前使用的环境。

架构

本地栈包含：

  • proxy：AuthSec 登录、会话处理、用户身份注入、OpenClaw HTTP 和 WebSocket 代理
  • openclaw：Docker 中的 OpenClaw 网关
  • run-openclaw-node.ps1：将你的 Windows 机器作为节点连接的辅助脚本

网关仅在回环地址上暴露，用于节点配对：

  • 代理 UI：http://localhost:8080
  • 网关回环：ws://127.0.0.1:18789

前置条件

  • Docker Desktop
  • PowerShell
  • Node.js + npm
  • 一个 AuthSec 应用程序和有效的 AuthSec 凭据
  • 至少一个用于 OpenClaw 的 LLM 提供商密钥

可选：

  • Discord 机器人令牌
  • 如果你想使用搜索工具而非仅浏览器自动化，需要 Brave Search API 密钥

1. 配置 .env

打开 deploy/docker-compose/.env 并为你的环境设置相应的值。

至少需要检查以下字段：

OPENCLAW_GATEWAY_TOKEN=<random-token>
PROXY_PUBLIC_BASE_URL=http://localhost:8080
SESSION_HMAC_SECRET=<random-secret>
SESSION_SECURE_COOKIE=false

AUTHSEC_MODE=authsec
AUTHSEC_ISSUER_URL=https://oauth.prod.authsec.ai
AUTHSEC_CLIENT_ID=<your-authsec-client-id>
AUTHSEC_CLIENT_SECRET=<your-authsec-client-secret>
AUTHSEC_ADMIN_EMAIL=<your-email>

AUTHSEC_JWT_SECRET=<native-authsec-secret>
AUTHSEC_BASE_URL=https://prod.api.authsec.ai
AUTHSEC_LOGIN_URL=https://oauth.prod.authsec.ai/oauth2/auth

OPENAI_API_KEY=<optional>
ANTHROPIC_API_KEY=<optional>
OPENCLAW_MODEL=openai/gpt-4o

说明：

  • 本地流程中 PROXY_PUBLIC_BASE_URL 应保持为 http://localhost:8080。
  • SESSION_SECURE_COOKIE=false 对于本地 HTTP 是正确的。
  • 不要将真实密钥提交到 Git。

2. 配置 OpenClaw

当前生效的 OpenClaw 配置位于 deploy/docker-compose/openclaw-config/openclaw.json。

当前重要行为：

  • 网关认证模式为 token
  • 本地 Control UI 允许在 http://localhost 上访问
  • 设备认证对 localhost 开发已放宽
  • tools.exec 默认使用名为 RitamKrKundu 的 Windows 节点

如需启用 Discord，在 channels.discord.token 中设置机器人令牌。

如需更改本地执行的默认节点名称，请更新：

"tools": {
  "exec": {
    "host": "node",
    "node": "RitamKrKundu"
  }
}

3. 启动栈

在 deploy/docker-compose 目录下：

docker compose up -d --build

如果之后只需刷新两个主要服务：

docker compose up -d --build --force-recreate openclaw proxy

查看日志：

docker compose logs -f openclaw proxy

4. 通过 AuthSec 登录

打开：

http://localhost:8080

然后：

  1. 使用 AuthSec 登录。
  2. 等待 OpenClaw Control UI 加载完成。
  3. 询问 who am I?

预期结果：

  • OpenClaw 应回答你已认证的邮箱和用户 ID。

该身份来自代理在请求到达 OpenClaw 之前将用户上下文写入共享工作区。

5. 配对 Windows 节点

Docker 网关本身可以代理聊天，但无法直接启动 Notepad、Teams 或 Explorer 等 Windows 应用。为此，你的 Windows 机器必须作为 OpenClaw 节点连接。

安装一次 OpenClaw CLI：

npm install -g openclaw@latest

在仓库根目录启动节点主机：

powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode run

如果是第一次运行，可能会打印 pairing required。

6. 批准配对请求

如果需要配对，使用另一个终端从网关容器中批准。

列出待处理的请求：

docker exec openclaw-gateway sh -lc "node /app/openclaw.mjs devices list --json"

批准请求：

docker exec openclaw-gateway sh -lc "node /app/openclaw.mjs devices approve <request-id> --json"

然后重新运行：

powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode run

保持该终端处于打开状态。节点必须持续运行才能保持 Windows 本机访问可用。

检查节点状态：

openclaw.cmd nodes status

预期结果：

  • Known: 1
  • Paired: 1
  • Connected: 1

7. 解锁 Windows 执行审批

即使节点连接成功，OpenClaw 仍可能拒绝 Windows 命令，直到为这个单用户设置打开节点端的执行审批。

在仓库根目录执行：

powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode unlock
powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode status

该辅助脚本会：

  • 写入一个宽松的本地 ~/.openclaw/exec-approvals.json
  • 将相同策略实时推送到已连接的节点
  • 设置 security=full
  • 设置 ask=off
  • 设置 askFallback=full

如果仍然看到 SYSTEM_RUN_DENIED: approval required，请在节点已连接时再次运行 -Mode unlock。

8. 测试真实命令

完成 AuthSec 登录、节点连接和解锁后，以下是一些好的测试：

身份验证：

  • who am I?

Windows 应用：

  • Open Notepad on node RitamKrKundu
  • Open my Downloads folder on node RitamKrKundu
  • Open the file C:\Users\<you>\Downloads\test.txt on node RitamKrKundu

浏览器：

  • Use the browser on node RitamKrKundu and open https://authsec.ai

Discord：

  • Read the last 5 messages from #general
  • Send a message to channel:123456789012345678

9. Discord 的工作方式

Discord 插件可以在 deploy/docker-compose/openclaw-config/openclaw.json 中启用。

重要说明：

  • 仅仅连接 Discord 机器人本身是不够的
  • OpenClaw 需要一个真实的读取和发送目标
  • 单独的服务器或公会名称不是有效的读取目标

使用：

  • #channel-name
  • channel:<channel-id>
  • user:<user-id>

不要期望：

  • 仅使用公会名称，例如 Ritam Server

10. 浏览器与搜索的区别

浏览器自动化：

  • 可以通过 OpenClaw 浏览器工具或已连接的节点/浏览器能力实现
  • 不需要搜索 API 密钥

搜索工具：

  • 与浏览器自动化不同
  • 需要配置 Brave Search 等提供商

如果还需要 Brave Search，请在 OpenClaw 的网络工具设置中配置相应的密钥。

11. 常见问题

who am I? 未显示已登录用户

检查：

  • AuthSec 登录是否成功完成
  • 代理日志中是否显示 user context written
  • 身份更改后代理是否已重新构建

有用的命令：

docker compose logs -f proxy

node required

你的 Windows 节点当前未连接。

运行：

powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode run
openclaw.cmd nodes status

SYSTEM_RUN_DENIED: approval required

节点已连接，但其执行审批仍然受限。

运行：

powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode unlock

gateway timeout after 30000ms

这通常意味着以下情况之一：

  • 节点进程当前未在运行
  • 节点已连接但卡住了
  • 命令在默认值刷新前尝试通过错误的主机启动

尝试：

openclaw.cmd nodes status
powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode run
powershell -ExecutionPolicy Bypass -File deploy/docker-compose/run-openclaw-node.ps1 -Mode unlock

Discord 提示目标未知

使用频道或用户目标：

  • #general
  • channel:<id>
  • user:<id>

Teams、Explorer、Notepad 或 Edge 无法打开

请记住：

  • Docker 本身无法启动 Windows GUI 应用
  • /host-home 只是一个挂载的文件夹
  • 真正的 GUI 应用启动必须通过已连接的 Windows 节点进行

12. 重新构建和重启命令

在 deploy/docker-compose 目录下：

docker compose up -d --build --force-recreate openclaw proxy
docker compose logs -f openclaw proxy
docker compose down

在仓库根目录下：

go test ./internal/proxy ./internal/auth

13. 安全警告

当前本地设置有意放宽，以便在开发期间 http://localhost:8080 能够正常工作：

  • 已启用不安全的 localhost Control UI 认证
  • localhost 的设备认证已禁用
  • 为单个受信任的操作员开放了节点执行权限

这对于在你自己机器上进行本地测试来说是可以的。

在通过 HTTPS 公开暴露之前，你应该：

  • 重新启用正常的设备认证
  • 删除不安全的仅 localhost 快捷方式
  • 检查令牌和提供商密钥的处理方式
  • 重新考虑是否应在同一网关上保留不受限制的节点执行权限