thClaws Docker 部署指南:一个容器跑起 AI Agent 服务

原创2026-10-13 22:33:082,230 阅读

thClaws Docker 部署指南:一个容器跑起 AI Agent 服务

thClaws 是一款用 Rust 编写的开源 AI Agent 工具,一个二进制文件即可提供 GUI、CLI、headless 和 Web 服务四种形态。本文带你用 Docker 部署 thClaws:只需一个容器,就能把完整的 AI Agent 服务跑起来,并通过浏览器使用它的 Web 界面。整个过程不需要在服务器上安装 Rust 工具链、Node 或 GTK 等依赖,适合新手快速完成 thClaws 容器化部署。

为什么 Docker 是部署 thClaws 的简单方式 🐳

thClaws 官方镜像 thclaws/thclaws 已经把所有麻烦的依赖打包好了,你在服务器上只需要装一个 Docker:

  • 免装依赖:镜像内已编译好完整的 thClaws 二进制,宿主机的 Rust、Node、GTK/WebKit2GTK 依赖链全部不需要;
  • 工具开箱即用:镜像内置 ripgrep、git、ffmpeg、python3、node 以及 Playwright + Chromium(用于浏览器自动化),Agent 的常见任务不会因为 command not found 而失败;
  • 多架构支持:同时提供 linux/amd64 和 linux/arm64,docker pull 会自动匹配你主机的架构;
  • 默认就是 Web 服务模式:容器默认执行 thclaws --serve,监听 8443 端口,打开浏览器即可使用,与桌面 GUI 用的是同一套前端。

镜像采用三阶段构建(frontend 构建 → Rust 编译 → 精简运行环境),构建细节可参考 Dockerfile 与 thclaws-technical-manual/docker.md。

快速开始:3 步完成 Docker 部署

第一步:拉取官方镜像

docker pull thclaws/thclaws:latest

标签说明::latest 是最新发布的版本,:edge 对应主干最新代码,生产环境建议固定使用具体版本标签(如 :0.9.9)以保证可复现。

第二步:挂载项目目录并启动容器

部署单元是"一个项目对应一个容器":把你的项目目录挂载到容器内的 /workspace 即可。

cd /path/to/your-project

docker run --rm -d \
  --name thclaws \
  -v "$(pwd)":/workspace \
  -p 127.0.0.1:8443:8443 \
  thclaws/thclaws:latest

第三步:浏览器访问

打开 http://localhost:8443,看到 thClaws 界面即部署成功 ✅。启动后的服务监听输出如下:

thClaws Docker 部署后 serve 服务启动监听 8443 端口的终端输出

浏览器中的 Chat 界面与桌面 GUI 完全一致,左侧是会话、知识与 MCP 服务器列表,右侧直接与 AI Agent 对话:

thClaws AI Agent 服务部署成功后浏览器中的聊天界面

配置 API Key:3 种方式让 AI Agent 动起来

容器里没有操作系统级密钥链(keychain),thClaws 会从环境变量中自动读取密钥,按推荐程度排序:

  1. .env 文件注入(推荐):在项目目录放一个 .env,写入 ANTHROPIC_API_KEY=…、OPENAI_API_KEY=…、GEMINI_API_KEY=… 等,启动时加 --env-file .env(compose 中为 env_file);
  2. 宿主机环境变量:如果你在 shell 里已 export 过密钥,Docker 会自动透传;
  3. Web 界面直接填写:打开界面右上角设置里的 Providers 面板,填入密钥并点 Save,thClaws 会写入挂载目录下的 .thclaws/settings.json,容器重启后依然保留:

thClaws Docker 容器内通过 Web 界面配置各模型 Provider API Key 的设置面板

⚠️ 两个常见坑:

  • 如果指定了 .env 但文件不存在,Docker 会直接报错 open .env: no such file or directory——先执行 touch .env 再启动,或者去掉 --env-file 参数;
  • 不要把 API Key 打进镜像里,.env* 已被排除在构建上下文之外,密钥只应通过环境变量或挂载文件注入。

用 docker compose 做长期运行部署 💡

仓库自带了一份 docker-compose.yml,适合"跑起来就不管它"的长期服务场景:项目目录挂载为 /workspace,用户级配置存入命名卷 thclaws-config,并设置了自动重启策略。

services:
  thclaws:
    image: thclaws/thclaws:latest
    ports:
      - "127.0.0.1:8443:8443"
    volumes:
      - ./:/workspace
      - thclaws-config:/root/.config/thclaws
    env_file:
      - path: .env
        required: false
    restart: unless-stopped
volumes:
  thclaws-config:

常用命令:

docker compose up -d          # 后台启动
docker compose logs -f thclaws # 查看实时日志

数据去哪了?thClaws 把会话、计划、团队、知识库等状态全部写在挂载目录的 ./.thclaws/ 下(宿主机的项目文件夹里),因此容器删了重建,数据都不会丢。

安全注意事项:端口绑定与远程访问

--serve 模式目前没有应用层鉴权,能连上端口就等于拥有完整的 Agent 权限(执行命令、读写文件)。默认配置已经把宿主端口绑定在 127.0.0.1:8443,只有本机可以访问,这正是官方推荐的姿态:

  • 远程访问:使用 SSH 隧道,最省事也最安全:
ssh -L 8443:localhost:8443 user@your-server
  • 局域网暴露:把 compose 里的 127.0.0.1:8443:8443 改成 8443:8443 后,服务将对局域网可见——只有在你前面有带鉴权的反向代理、SSH 隧道或 VPN 时才能这样做;
  • 容器内监听 0.0.0.0 是必须的(否则宿主机端口转发进不来),真正的访问边界由宿主机的端口绑定来控制。

常见问题 FAQ

Q1:启动时报 open .env: no such file or directory? 指定了 .env 但文件不存在。执行 touch .env 创建空文件,或移除 --env-file 参数即可。

Q2:8443 端口被占用怎么办? 修改映射的宿主端口即可,例如 -p 127.0.0.1:9000:8443,然后访问 http://localhost:9000。

Q3:想从源码自己构建镜像?

git clone https://gitcode.com/gh_mirrors/th/thClaws
cd thClaws
docker build -t thclaws/thclaws:local .

首次全量构建约需 25 分钟(主要是 Rust 依赖编译),之后增量编译只需几分钟。

Q4:容器里写出的文件权限不对? 构建镜像时传入 --build-arg USER_UID=$(id -u) --build-arg USER_GID=$(id -g),或在 compose 中覆盖 user: "1000:1000",让写入的文件归属你的宿主机用户。

相关文档与源码

至此,你的 thClaws Docker 部署就完成了:一条 docker run 拉起容器、一个 .env 注入密钥、浏览器打开 8443 端口,AI Agent 服务即可开始工作。

登录后查看全文
thClaws