thClaws Docker 部署指南:一个容器跑起 AI Agent 服务
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 界面即部署成功 ✅。启动后的服务监听输出如下:
浏览器中的 Chat 界面与桌面 GUI 完全一致,左侧是会话、知识与 MCP 服务器列表,右侧直接与 AI Agent 对话:
配置 API Key:3 种方式让 AI Agent 动起来
容器里没有操作系统级密钥链(keychain),thClaws 会从环境变量中自动读取密钥,按推荐程度排序:
.env文件注入(推荐):在项目目录放一个.env,写入ANTHROPIC_API_KEY=…、OPENAI_API_KEY=…、GEMINI_API_KEY=…等,启动时加--env-file .env(compose 中为env_file);- 宿主机环境变量:如果你在 shell 里已
export过密钥,Docker 会自动透传; - Web 界面直接填写:打开界面右上角设置里的 Providers 面板,填入密钥并点 Save,thClaws 会写入挂载目录下的
.thclaws/settings.json,容器重启后依然保留:
⚠️ 两个常见坑:
- 如果指定了
.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",让写入的文件归属你的宿主机用户。
相关文档与源码
- 官方 Docker 手册:thclaws-technical-manual/docker.md
- Serve 模式与信任模型:thclaws-technical-manual/serve-mode.md
- 用户手册安装章节(含完整 docker run 配方):user-manual/ch02-installation.md
- 构建入口:Dockerfile、编排文件:docker-compose.yml
- Web 服务实现:crates/core/src/server.rs
至此,你的 thClaws Docker 部署就完成了:一条 docker run 拉起容器、一个 .env 注入密钥、浏览器打开 8443 端口,AI Agent 服务即可开始工作。


