1. 从 OpenClaw 到 Clawith：企业级 AI Agent 的工程化起点
如果你最近在折腾 AI Agent，大概率听过 OpenClaw 这个名字。它把"本地运行、真正执行任务"这件事做成了开源爆款，个人开发者用得很爽。但一旦要把这套能力搬进团队协作场景，问题就来了：单用户架构、没有多租户隔离、缺少审批和审计，几个人同时用就开始互相踩脚。Clawith 就是冲着这个缺口来的，定位是"OpenClaw for Teams"，把个人 Agent 升维成组织级平台。
这篇文章不聊概念，直接拆工程落地。我会带你走一遍 Clawith 在 AI Agent 场景下的 FastAPI 服务层设计，以及 Docker 容器化部署的关键路径。读完你能拿到一套可复制的 Dockerfile、docker-compose 配置和 FastAPI 路由示例，本地跑起来一个能连通、能调用的 Agent 服务骨架。
适合谁看：想快速复现一套 Agent 后端骨架的后端工程师、正在评估企业级 Agent 平台的技术负责人、以及被 Docker 编排和 FastAPI 异步坑过的同学。前置要求不高，Python 3.12+、Node.js 20+、2 核 4G 的机器就够起步。
先说清楚 Clawith 的架构定位，避免后面配置时概念混淆。它是标准的前后端分离 Web 应用，前端 React 19 + Vite，后端 FastAPI + SQLAlchemy 异步，基础设施层用 PostgreSQL/SQLite + Redis + Docker Compose。关键一点：Clawith 本地不跑任何 AI 模型，所有 LLM 推理由外部 API 提供商处理。这意味着你的部署压力主要在服务编排和数据持久化，而不是 GPU。
Agent 的工作空间文件——soul.md、memory.md、技能文件、工作区文件——都存在宿主机./backend/agent_data/<agent-uuid>/目录下，通过挂载注入容器。这个设计很实用，数据直接可访问、可备份，不用进容器里捞文件。理解这一点，后面配 volume 的时候你就知道该挂哪里。
2. TaoToken 前置：给 Agent 服务接上稳定的模型调用层
Clawith 本身不产模型能力，它靠外部 API 提供商驱动 Agent 的推理。你在.env里配的 LLM API Key，决定了 Agent 能不能真正"思考"和"执行"。这一步如果配得随意，后面调试接口连通性时会很痛苦——报错信息往往指向业务代码，实际根因却在模型调用层。
我建议在正式接入前，先把模型调用层单独验证通。TaoToken 提供统一的 API 入口，兼容主流模型协议，适合作为 Clawith 的 LLM 后端。它的 API 地址是https://taotoken.net/api，你可以在控制台创建 Key，然后在模型对话页面先做一次最小验证，确认 Key 有效、模型可调，再写进 Clawith 的.env。
具体操作路径：先到 API Keys 管理页 生成一个 Key，注意保存时只显示一次。然后打开模型对话页面，选一个模型发一条测试消息，确认返回正常。这一步别跳过，很多"Agent 不响应"的问题，根源就是 Key 没生效或模型 ID 写错。
如果你打算长期跑编码类 Agent 或做多 Agent 协作，可以了解下 Coding Plan，它在调用配额和稳定性上更适合持续任务。接入文档在这里，里面有各语言的调用示例，FastAPI 里用 httpx 异步调用可以直接参考。
把模型层验证通之后，再回到 Clawith 的配置。.env里通常需要填OPENAI_API_KEY、OPENAI_BASE_URL、LLM_MODEL这类字段。Base URL 指向https://taotoken.net/api，Key 填你刚生成的，Model ID 填你在模型对话里验证过的那个。三件套对齐，Agent 才有推理能力。
这里有个容易忽略的点：Clawith 支持 LLM 模型池配置，可以配 OpenAI、Anthropic、DeepSeek、Azure 多家并做智能路由。如果你只用一个提供商，配一组就行；如果要做路由，确保每个提供商的 Base URL 和 Key 都独立验证过，别混用。
3. 可复制配置：Dockerfile、docker-compose 与 FastAPI 路由
这一节是全文的核心，直接给可复制的配置片段。先说 Docker 部署的整体结构，再拆 FastAPI 服务层的关键路由。
Clawith 官方提供两种部署方式：脚本安装和 Docker 部署。脚本方式适合快速体验，Docker 方式适合工程化落地。我们聚焦 Docker，因为你要的是可复现、可迁移的服务骨架。
先看.env的关键配置。复制.env.example后，重点改这几项：
# .env 关键配置 OPENAI_API_KEY=sk-你的TaoToken密钥 OPENAI_BASE_URL=https://taotoken.net/api LLM_MODEL=gpt-4o-mini DATABASE_URL=postgresql+asyncpg://clawith:clawith@db:5432/clawith REDIS_URL=redis://redis:6379/0 AGENT_DATA_DIR=./backend/agent_data注意DATABASE_URL用的是asyncpg驱动，因为 Clawith 后端是 SQLAlchemy 异步模式。如果你用 SQLite 做个人试用，改成sqlite+aiosqlite:///./clawith.db即可。
接下来是docker-compose.yml的核心结构。Clawith 的编排包含后端、前端、数据库、Redis 四个主要服务：
# docker-compose.yml services: backend: build: context: ./backend dockerfile: Dockerfile ports: - "8008:8008" env_file: - .env volumes: - ./backend/agent_data:/app/agent_data depends_on: - db - redis restart: unless-stopped frontend: build: context: ./frontend dockerfile: Dockerfile ports: - "3008:3008" depends_on: - backend restart: unless-stopped db: image: postgres:16-alpine environment: POSTGRES_USER: clawith POSTGRES_PASSWORD: clawith POSTGRES_DB: clawith volumes: - pgdata:/var/lib/postgresql/data restart: unless-stopped redis: image: redis:7-alpine restart: unless-stopped volumes: pgdata:这里的关键是backend服务的 volume 挂载：./backend/agent_data:/app/agent_data。这对应前面说的 Agent 工作空间文件存储路径，挂载后宿主机可直接访问，备份和迁移都方便。
后端 Dockerfile 的写法要注意 Python 依赖和异步驱动的安装：
# backend/Dockerfile FROM python:3.12-slim WORKDIR /app RUN apt-get update && apt-get install -y --no-install-recommends \ gcc libpq-dev && rm -rf /var/lib/apt/lists/* COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8008 CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8008"]libpq-dev是 PostgreSQL 异步驱动编译需要的，别省。uvicorn启动时用0.0.0.0而不是127.0.0.1，否则容器外访问不到。
现在看 FastAPI 服务层。Clawith 后端有 18 个 API 模块，我们抽一个 Agent 调用的核心路由来演示。假设你要加一个自定义的 Agent 执行端点：
# backend/app/api/agent_route.py from fastapi import APIRouter, Depends, HTTPException from pydantic import BaseModel from sqlalchemy.ext.asyncio import AsyncSession from app.core.database import get_db from app.services.agent_service import AgentService router = APIRouter(prefix="/api/agent", tags=["agent"]) class AgentRunRequest(BaseModel): agent_id: str task: str skill: str | None = None class AgentRunResponse(BaseModel): run_id: str status: str output: str | None = None @router.post("/run", response_model=AgentRunResponse) async def run_agent( req: AgentRunRequest, db: AsyncSession = Depends(get_db), ): service = AgentService(db) try: result = await service.execute( agent_id=req.agent_id, task=req.task, skill=req.skill, ) return AgentRunResponse(**result) except ValueError as e: raise HTTPException(status_code=400, detail=str(e)) except Exception as e: raise HTTPException(status_code=500, detail=f"agent run failed: {e}")这个路由展示了三个工程要点：用 Pydantic 做请求/响应模型校验、用Depends(get_db)注入异步数据库会话、把业务逻辑收进AgentService而不是堆在路由里。Clawith 的 RBAC 和审计日志通常通过依赖注入的中间件或装饰器实现，你可以在Depends链里加权限校验。
如果你要接 MCP 工具，Clawith 内置了 MCP Client。配置方式是在 Agent 的技能配置里挂载 MCP Server 地址，运行时通过 MCP Registry 动态加载。这部分在.env里可能需要配SMITHERY_API_KEY或MODELSCOPE_API_KEY，取决于你用哪个注册表。
4. 验证请求：本地启动与接口连通性检查
配置写完，下一步是验证。别急着开前端点按钮，先用命令行把后端接口打通，这样出问题定位快。
启动所有服务：
docker compose up -d docker compose psps应该看到四个服务都是running或healthy。如果backend反复重启，先看日志：
docker compose logs -f backend常见的是数据库连接失败或依赖没装全。确认db服务先起来，backend的depends_on才会生效。
服务起来后，先测健康检查端点：
curl -s http://localhost:8008/health正常返回类似{"status":"ok"}。如果连不上，检查端口映射和防火墙。
接着测 Agent 执行接口。先注册一个用户拿到 JWT，第一个注册用户自动成为管理员：
curl -X POST http://localhost:8008/api/auth/register \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"yourpassword","email":"admin@example.com"}'拿到 token 后，调用 Agent 执行端点：
curl -X POST http://localhost:8008/api/agent/run \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <你的token>" \ -d '{"agent_id":"test-agent","task":"用一句话介绍 FastAPI","skill":"content_writing"}'预期返回一个run_id和status。如果status是completed且output有内容，说明模型调用层通了。如果返回 500 且日志里出现模型相关报错，回到第 2 节检查 Base URL、Key、Model ID 三件套。
前端验证：浏览器打开http://localhost:3008，用刚注册的账号登录，进 Agent 管理页创建一个 Agent。五步向导里，Persona & Soul 那步会生成soul.md，技能配置那步选内置技能，权限级别建议先选 L1 自动，渠道绑定可以先跳过。创建完成后，在任务看板里发一条任务，看 Agent 是否响应。
实测下来，最容易卡住的是模型调用超时。如果你的网络环境访问外部 API 不稳定，可以在.env里调大超时参数，或者用 TaoToken 的模型对话页面先确认服务端可达。另外，Agent 首次执行会初始化工作空间文件，./backend/agent_data/<agent-uuid>/目录下应该出现soul.md和memory.md，这是判断 Agent 是否真正创建成功的标志。
5. 本篇常见错排查：401、local proxy failed 与 reading choices
这一节对照真实报错，给你排查路径。这些坑我在部署时基本都踩过一遍。
401 Unauthorized。两种可能：一是 JWT 过期或没带，检查请求头Authorization: Bearer <token>格式对不对；二是模型 API Key 无效，日志里会显示上游返回 401。区分方法：看报错发生在你的路由层还是模型调用层。如果是模型层，回到.env确认OPENAI_API_KEY和OPENAI_BASE_URL是否匹配。Key 和 Base URL 必须来自同一个提供商，混用会直接 401。
local proxy failed。这个报错通常出现在容器内访问外部 API 时。容器默认走宿主机的网络配置，如果宿主机有代理设置而容器没继承，就会失败。排查步骤：进容器测连通性：
docker compose exec backend curl -s -o /dev/null -w "%{http_code}" https://taotoken.net/api如果返回非 200，说明容器网络层有问题。检查docker-compose.yml里有没有配network_mode或extra_hosts。另外确认.env里的 Base URL 没有写成localhost——容器里的localhost指向容器自己，不是宿主机。
reading choices 报错。这个通常出现在模型返回格式不符合预期时。Clawith 的 Agent 服务在解析 LLM 响应时，如果返回体里没有choices字段，就会抛这个错。原因可能是：Model ID 写错导致返回了错误页、Base URL 指向了非兼容端点、或者请求体格式不对。排查方法：用 curl 直接调模型端点，看原始返回：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer <你的key>" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'如果这个返回正常有choices，问题就在 Clawith 的请求构造层；如果这个也报错，问题在 Key 或 Model ID。
OAuth 相关报错。Clawith 支持飞书/Slack 的 SSO 登录，如果你配了渠道绑定但 OAuth 回调失败，检查回调地址是否和平台配置一致。本地开发时，回调地址通常是http://localhost:3008/api/auth/callback/<provider>，平台侧要填同样的地址。端口不一致是最常见的低级错误。
Agent 不响应但接口返回 200。这种情况通常是 Agent 的权限级别设成了 L3 审批，任务进了审批队列但没人批。去审批工作流页面看一下有没有待审批项。或者 Agent 的 TTL 到期了，检查使用配额配置。
数据库迁移失败。Clawith 用 SQLAlchemy 异步，首次启动会自动建表。如果db服务没就绪，backend启动时会报连接错误。解决办法是给backend加健康检查依赖，或者手动先起db再起backend：
docker compose up -d db redis sleep 5 docker compose up -d backend frontend排查的核心思路是分层定位：先确认容器状态，再确认网络连通，再确认模型调用，最后确认业务逻辑。每一层都有对应的验证命令，别跳层猜。
6. 把 Agent 服务骨架跑起来之后
到这里，你应该有一套能跑通的 Clawith Agent 服务骨架了。后端 FastAPI 在 8008，前端在 3008，Agent 工作空间文件落在宿主机可访问的目录，模型调用走 TaoToken 的统一入口。这套骨架的价值在于可复现——换台机器，改.env里的 Key 和数据库地址，docker compose up -d就能重建。
后续要扩展的话，几个方向值得试。一是接 MCP 工具，Clawith 内置 MCP Client，你可以在技能配置里挂载外部 MCP Server，让 Agent 能调数据库、查 API、操作文件。二是配多 Agent 协作，用监督任务机制让一个 Agent 跟进另一个 Agent 的待办，这在项目管理场景里很实用。三是把审计日志接出来，Clawith 每个 Agent 操作都有完整追踪，导出到你的日志系统做合规分析。
如果你在配模型层时想要更细的调用控制，可以看下 Coding Plan 的配额策略；接入细节在文档里，FastAPI 异步调用的示例可以直接抄。Key 管理在控制台，建议给不同环境建不同的 Key，方便排查和轮换。
最后留一个实用技巧：Agent 的soul.md和memory.md是持久身份的核心，前者定义角色和行为边界，后者积累交互记忆。调试阶段可以手动编辑这两个文件，观察 Agent 行为变化，比反复改代码快得多。工作空间目录挂载在宿主机，直接改文件、重启 Agent 就生效。
