1. 项目概述：一个基于OpenClaw的本地AI智能体开发与测试环境

如果你正在寻找一个能让你在本地快速启动、测试和定制AI智能体的项目，那么 openclaw-agent 是一个绝佳的起点。这个项目本质上是一个预配置好的开发沙箱，它通过 Docker 和 Docker Compose 将 OpenClaw 网关服务、Google Vertex AI 模型以及一个可定制的智能体工作空间打包在一起。你不需要从零开始配置复杂的网络、认证和模型接口，只需几条命令，就能在本地拥有一个功能完整的、可对话的AI智能体，并可以立即开始修改它的“人格”、技能和指令。

这个项目的核心价值在于“开箱即用”和“深度可定制”。它解决了AI智能体开发中常见的环境搭建繁琐、依赖复杂、测试流程不连贯的问题。无论你是想快速体验OpenClaw框架的能力，还是计划基于它开发一个具备特定领域知识的专属助手，这个项目都提供了清晰的路径。它特别适合对AI应用开发感兴趣的Python开发者、希望研究智能体行为的工程师，以及任何想拥有一个私有、可控、可编程对话AI的个人用户。

2. 核心架构与设计思路拆解

2.1 为什么选择“网关+SDK+工作空间”的架构？

openclaw-agent 项目采用了典型的客户端-服务器架构，但这种架构在AI智能体场景下被赋予了特定的含义。其设计思路可以拆解为三个核心层次：

  1. 网关层（服务端） ：由 docker-compose.yml 定义的 openclaw-gateway 容器构成。这是整个系统的“大脑”和“调度中心”。它负责管理AI模型（如Gemini）的连接、处理WebSocket和HTTP请求、加载并执行智能体的技能（Skills）、维护会话状态。将其封装在Docker容器中，确保了环境的一致性，避免了“在我机器上能跑”的经典问题。网关通过配置文件 config/openclaw.json 来定义行为，例如启用哪些API端点、默认使用哪个AI模型、允许加载哪些技能包。

  2. 客户端层（SDK与脚本） ：项目中的 src/openclaw_agent/client.py 和 scripts/run.py 扮演了客户端的角色。它们使用官方的 openclaw-sdk 与网关进行通信。这种分离带来了巨大的灵活性：网关可以独立部署和运行，而客户端可以用任何支持WebSocket的语言重写，或者集成到更大的应用系统中。 scripts/run.py 脚本则是一个“验收测试”客户端，它依次检查WebSocket连通性、HTTP健康状态，并发送一个真实的对话请求来验证整个链路是否正常工作。

  3. 工作空间层（数据与配置） ： workspace/ 目录是智能体的“记忆宫殿”和“人格设定集”。它包含了定义智能体行为的所有文本文件（SOUL.md, AGENTS.md等）。这个目录被以“卷（Volume）”的形式挂载到Docker容器中，这意味着你可以在宿主机上直接编辑这些Markdown文件，改动会实时（或在重启后）反映到智能体的行为中。这种设计将“代码逻辑”（网关）和“内容数据”（工作空间）清晰分离，使得调整智能体性格、指令或添加新技能变得像编辑文档一样简单。

这种分层架构的优势在于 解耦 和 可维护性 。你可以单独升级网关镜像、调整SDK调用方式，或者彻底重写工作空间内容，而其他部分无需改动。对于团队协作来说，工作空间文件可以纳入版本控制（注意排除敏感信息），方便追踪智能体“人格”的演变历史。

2.2 关键技术选型背后的考量

  • Poetry 管理 Python 依赖 ：项目使用 Poetry 而非传统的 requirements.txt 加 venv 。Poetry 能更好地处理依赖解析、版本锁定（ poetry.lock ）和虚拟环境管理。它确保了所有开发者、CI/CD环境使用的第三方库版本完全一致，避免了因依赖冲突导致的诡异问题。对于 openclaw-sdk 这类仍在快速迭代的库，锁定版本至关重要。
  • npm Scripts 作为统一入口 ：尽管核心是Python项目，却用 package.json 中的 npm scripts 来封装常用命令（ start , stop , test ）。这是一个非常实用的设计。它为用户（尤其是可能不熟悉Docker Compose命令的开发者）提供了简单、一致的接口。你不需要记住 docker compose up 和 docker compose down 的各种参数，只需要知道 npm run start 和 npm run stop 。这降低了使用门槛，也使得项目结构对前端或全栈开发者更友好。
  • Google Vertex AI 作为默认模型后端 ：选择 Gemini via Vertex 而非 OpenAI API 或其他本地模型，可能基于几点考虑：一是性能与成本的平衡，Gemini Flash模型响应快且成本相对较低；二是与企业Google Cloud生态的集成便利性；三是通过服务账号JSON文件进行认证，比管理API密钥更符合生产环境的安全实践。项目通过 config/google-credentials.json 和 GOOGLE_APPLICATION_CREDENTIALS 环境变量来管理认证，这是GCP服务的标准做法。
  • 环境变量与配置文件的分工 ：安全敏感信息（如网关令牌 OPENCLAW_GATEWAY_TOKEN 、服务账号JSON）通过 .env 文件或环境变量传递，并被 .gitignore 排除在版本库外。而非敏感的运行时配置（如端口、启用哪些功能）则放在 config/openclaw.json 中，可以纳入版本控制。这种区分是安全开发的基础实践。

3. 从零开始的详细实操指南

3.1 环境准备与依赖安装

在开始之前，请确保你的系统满足以下基础要求。我将以 macOS/Linux 系统为例，Windows 用户建议使用 WSL2 以获得最佳体验。

第一步：安装核心工具

  1. Docker 与 Docker Compose ：这是项目的基石。前往 Docker 官网下载并安装 Docker Desktop（它包含了 Docker Compose）。安装后，在终端运行 docker --version 和 docker compose version 确认安装成功。
  2. Node.js 与 npm ：仅用于运行封装好的脚本。从 Node.js 官网下载 LTS 版本安装即可。安装后运行 node --version 和 npm --version 检查。
  3. Python 3.11+ ：OpenClaw SDK 对 Python 版本有要求。使用 pyenv 或系统包管理器安装。运行 python3 --version 确认。
  4. Poetry ：推荐使用官方安装脚本： curl -sSL https://install.python-poetry.org | python3 - 。安装后，将 Poetry 添加到你的 PATH（安装脚本通常会提示），然后运行 poetry --version 。

第二步：获取项目代码 

git clone <repository-url> openclaw-agent
cd openclaw-agent

请将 <repository-url> 替换为实际的仓库地址。

第三步：配置 Google Cloud 凭证（关键且易错） 这是让智能体“能思考”的关键一步，也是最容易出错的地方。

  1. 创建服务账号 ：访问 Google Cloud Console，进入 IAM 与管理 -> 服务账号。创建一个新的服务账号（例如命名为 openclaw-agent ），并为其授予 Vertex AI User 角色。这个角色允许该账号调用 Vertex AI API。
  2. 生成密钥 ：在创建的服务账号详情页，选择“密钥”标签页，点击“添加密钥” -> “创建新密钥”，选择 JSON 格式。下载生成的 JSON 文件。
  3. 放置密钥 ：在项目根目录下，将下载的 JSON 文件重命名为 google-credentials.json ，并放入 config/ 目录中。 务必确认 config/.gitignore 文件已包含 google-credentials.json ，防止误提交。 
    # 假设下载的密钥文件在 Downloads 目录
cp ~/Downloads/your-project-xxxxxxx.json ./config/google-credentials.json

注意 ：很多初次使用 GCP 的用户会忽略为服务账号启用对应的 API。请确保在你的 GCP 项目中， Vertex AI API 是启用状态。可以在 Cloud Console 的“API 与服务” -> “库”中搜索并启用。

第四步：配置环境变量 复制环境变量模板文件，并设置你的网关访问令牌。

cp .env.example .env

编辑 .env 文件。默认的 OPENCLAW_GATEWAY_TOKEN=dev-token-local-only 对于本地开发是安全的，你可以保留。如果你需要更复杂的令牌，可以在此修改。 同样，确保 .env 在 .gitignore 列表中。

3.2 启动网关与运行测试

环境就绪后，启动和测试过程非常直观。

第一步：启动 OpenClaw 网关 在一个终端窗口（我们称之为终端 A）中，运行：

npm run start

你将看到 Docker 开始拉取镜像、创建容器，并最终输出网关的日志。当看到类似 “OpenClaw gateway started on http://0.0.0.0:18789” 的信息时，说明网关已成功启动并在 18789 端口监听。 让这个终端保持运行状态。

第二步：运行集成测试 打开另一个终端窗口（终端 B），在项目根目录下运行：

npm run test

这个脚本会依次执行以下操作：

  1. 检查 Poetry 依赖，如有必要则安装。
  2. 运行 scripts/run.py 。
  3. run.py 会首先尝试连接 ws://127.0.0.1:18789/gateway 的 WebSocket 端点，完成一个简单的握手挑战（challenge）。这是验证网关核心通信层是否正常。
  4. 接着，它会向 http://127.0.0.1:18789/healthz 发送 HTTP GET 请求，检查网关的 HTTP 服务健康状态。
  5. 最后，也是最关键的一步，它会通过 HTTP API ( POST /v1/responses ) 向智能体发送一个预设的提示词 “Say hello.” 。
  6. 智能体（配置了 workspace/skills/hello-world/ 技能）会处理这个请求，并应返回一个包含 “hello-world” 字样的回复。脚本会检查回复中是否包含该字符串。

如果一切顺利，你将在终端 B 看到如下输出，并返回退出码 0：

OpenClaw gateway checks:
  ✓ WebSocket: WebSocket connect.challenge received
  ✓ Health: HTTP /healthz -> 200
  ✓ Agent: Agent replied: '... hello-world ...'
Done.

这标志着从基础设施到AI模型，再到自定义技能的完整链路全部贯通。

第三步：停止网关 测试完成后，在运行网关的终端 A 中按下 Ctrl+C ，即可优雅停止容器。或者，在任何终端运行 npm run stop 来停止并移除容器。

3.3 深入探索：使用 Python SDK 与智能体交互

测试脚本只是验证了基础功能。要真正“使用”这个智能体，你需要了解如何通过 SDK 编程式地与它对话。

基本异步调用 项目提供的 run_agent_query 函数是对 SDK 的简单封装。你可以创建一个新的 Python 脚本（例如 chat.py ）进行尝试：

import asyncio
from openclaw_agent import run_agent_query

async def main():
    # 询问一个简单问题
    response = await run_agent_query("What is the capital of France?", agent_id="main")
    print(f"Agent replied: {response}")
    # 进行多轮对话（注意：默认配置下，每次execute是独立会话）
    follow_up = await run_agent_query("And what is its population?", agent_id="main")
    print(f"Follow-up: {follow_up}")

if __name__ == "__main__":
    asyncio.run(main())

运行前确保网关已启动 ( npm run start )。这个例子展示了最基本的问答。

直接使用 OpenClaw SDK 如果你想获得更细粒度的控制，可以直接使用官方 SDK。 client.py 中的函数也是基于此构建的：

import asyncio
from openclaw_sdk import OpenClawClient

async def main():
    # 连接到本地网关，使用默认令牌和URL
    async with OpenClawClient.connect(
        # 这些参数默认从环境变量读取，与项目配置一致
        # gateway_ws_url="ws://127.0.0.1:18789",
        # token="dev-token-local-only"
    ) as client:
        # 获取名为 “main” 的智能体实例
        agent = client.get_agent("main")
        
        # 执行一个查询
        result = await agent.execute("请用中文作一首关于秋天的五言绝句。")
        print(result.content)  # 打印智能体返回的文本内容
        
        # 查看原始响应对象（可能包含更多元数据）
        # print(result)

asyncio.run(main())

直接使用 SDK 的好处是你能接触到完整的响应对象，未来如果需要处理非文本内容、工具调用结果或会话ID，会更有灵活性。

4. 核心组件深度解析与定制

4.1 解剖智能体的“人格”：Workspace 文件详解

workspace/ 目录下的 Markdown 文件共同塑造了智能体的行为和认知。理解它们的作用是进行高级定制的关键。

文件 核心作用与编写要点 示例/技巧
SOUL.md 定义智能体的 核心人格、价值观和边界 。这是最高层次的指导，影响其所有输出。 在这里你可以设定：“你是一位乐于助人且严谨的软件工程师助手”、“你的回答应基于事实，对不确定的信息要明确说明”、“你拒绝回答涉及隐私或有害内容的问题”。这部分内容会在每次会话开始时被加载，奠定基调。
AGENTS.md 操作指令手册 。更具体地说明智能体应该如何思考、使用模型、处理记忆和工具。 可以包含：“当用户提供代码时，优先分析其逻辑和潜在bug”、“使用思维链（Chain-of-Thought）的方式分步骤回答复杂问题”、“将重要的用户偏好记录到每日记忆文件中”。
IDENTITY.md 智能体的 名称和角色 。一个简短的自我介绍。 “我是Claw，你的开源AI开发助手。” 这会在对话中偶尔被引用，让交互更有代入感。
USER.md 关于用户的描述 。告诉智能体它正在与谁对话，用户的背景和偏好。 “你正在与一位全栈开发者对话，他熟悉Python和JavaScript，正在构建一个AI应用。” 这能帮助智能体调整回答的技术深度和角度。
TOOLS.md 本地工具和约定的说明 。注意，这个文件本身不“启用”工具，而是告诉智能体有哪些工具可用及其用法。 可以描述：“项目使用 pytest 进行测试，测试文件位于 tests/ 目录”、“代码风格遵循 black 和 isort ”。当智能体需要建议测试或代码规范时，会参考这里。
memory/ 目录 可选的外部记忆 。可以按日期（ YYYY-MM-DD.md ）存储对话摘要或重要事实。 智能体可以被告知（在AGENTS.md中）去读取或写入这个目录的文件，从而实现跨会话的、简单的持久化记忆。例如，记录用户说过“我最喜欢的编辑器是VS Code”。

定制实操 ：想要一个“毒舌但专业的代码评审员”？在 SOUL.md 中加入幽默犀利的语言风格描述，在 AGENTS.md 中强调代码分析和批判性思维。完成后，需要 重启网关 ( npm run stop && npm run start ) 才能使新的“人格”生效，因为工作空间文件通常在网关启动时加载。

4.2 技能（Skills）系统：扩展智能体的能力

技能是OpenClaw中智能体可以执行的具体操作或调用外部服务的方式。项目通过 config/openclaw.json 的 skills 部分进行配置。

// config/openclaw.json 片段
"skills": {
  "allowBundled": ["gemini", "peekaboo", "sag", "agent-tools"],
  "entries": {
    "gemini": { "enabled": true },
    "peekaboo": { "enabled": true },
    "sag": { "enabled": false },
    "agent-tools": { "enabled": true }
  }
}
  • allowBundled ：这是一个 白名单 。网关镜像内预置（Bundled）了一些技能，但出于安全考虑，你需要在这里明确声明允许加载哪些。项目默认允许了四个。
  • entries ：对具体技能进行 精细控制 。你可以启用或禁用某个技能，也可以为其提供配置（如API密钥）。例如， sag 技能（可能关联 ElevenLabs 语音合成）默认是禁用的，因为需要额外的 ELEVENLABS_API_KEY 。

如何添加自定义技能？ 这是赋予智能体独特能力的关键。所有自定义技能都应放置在 workspace/skills/ 目录下。每个技能是一个独立的子目录，其中必须包含一个 skill.json 描述文件。

  1. 在 workspace/skills/ 下创建一个新目录，例如 my-calculator/ 。
  2. 在该目录内创建 skill.json ，定义技能的名称、描述、触发模式等。
  3. 根据技能类型，可能还需要编写对应的执行脚本（如Python文件）。
  4. 在 config/openclaw.json 的 skills.allowBundled 数组中添加你的技能名（例如 “my-calculator” ），并在 skills.entries 中配置 { “enabled”: true } 。
  5. 重启网关。现在，当用户的问题匹配该技能的描述时，智能体就有可能调用它。

workspace/skills/hello-world/ 就是一个最简单的示例技能，它让智能体在检测到问候语时回复特定内容。研究它的结构是学习创建自定义技能的最佳起点。

4.3 网关配置与网络调优

config/openclaw.json 是网关的“大脑配置”。除了技能，还有几个关键配置项值得关注：

  • gateway.http.endpoints.responses ：设置为 true 才启用 POST /v1/responses 这个HTTP API端点，我们的测试脚本和SDK默认调用都依赖它。
  • gateway.bind ：默认配置可能是 “lan” ，这通常意味着绑定到 0.0.0.0 ，允许同一局域网内的其他设备访问。如果仅在本地开发，可以改为 “127.0.0.1” 以增强安全性。
  • defaultModel ：定义了智能体默认使用的AI模型。本项目是 “google-vertex/gemini-2.0-flash” 。如果你想尝试其他模型（如 gemini-2.0-pro 或未来支持的模型），需要在此修改，并确保你的GCP项目和凭证有权限调用该模型。

关于网络连接的一个常见问题 ：Docker容器内的网关服务默认绑定到容器的 18789 端口，并通过 docker-compose.yml 的 ports: - “18789:18789” 映射到宿主机的同一端口。因此，从宿主机上的Python脚本连接 127.0.0.1:18789 是可行的。如果你需要从同一网络下的另一台机器访问，则需要确保宿主机的防火墙允许该端口，并使用宿主机的IP地址进行连接。

5. 开发、调试与问题排查实战

5.1 高效的开发工作流

  1. 修改工作空间/技能 ：直接编辑 workspace/ 下的 .md 文件或 skills/ 下的技能文件。对于技能文件的修改，OpenClaw网关可能支持热重载（需查看具体版本特性），但最稳妥的方式是修改后执行 npm run stop && npm run start 重启网关。
  2. 修改Python客户端代码 ：编辑 src/openclaw_agent/ 下的文件。由于是使用 poetry install 进行的可编辑安装（ pyproject.toml 中可能有 packages = [{include = “openclaw_agent”, from = “src”}] 的配置），修改会立即生效，无需重新安装包。
  3. 运行测试 ： npm run test 是主要的集成测试。对于更频繁的单元测试，你可以直接使用 pytest ： 
    poetry run pytest tests/ -v
  4. 查看网关日志 ：这是 最重要的调试手段 。在运行 npm run start 的终端中，所有网关日志（包括模型调用、技能执行、错误信息）都会实时输出。任何与智能体交互相关的问题，首先查看这里。

5.2 常见问题与解决方案速查表

以下是我在部署和测试过程中遇到的一些典型问题及其解决方法：

问题现象 可能原因 排查步骤与解决方案
npm run test 失败，提示 WebSocket 连接错误。 1. 网关未启动。
2. 端口被占用或映射错误。
3. 防火墙阻止。		 1. 运行 npm run start 并确认无报错。
2. 运行 docker ps 查看容器是否运行，并检查 18789 端口映射。
3. 尝试 curl http://127.0.0.1:18789/healthz ，应返回 OK 。
WebSocket 连接成功，但 HTTP /healthz 检查失败。 网关HTTP服务未正确启动或配置有误。 检查 config/openclaw.json 中 gateway.http 相关配置，特别是 endpoints.responses 是否启用。查看网关日志是否有HTTP服务启动错误。
Agent 检查失败，回复为空或不包含 “hello-world”。 1. Google 凭证无效或未找到。
2. Vertex AI API 未启用。
3. 工作空间或技能未正确挂载。
4. AI 模型调用失败。		 1. 最关键 ：确认 config/google-credentials.json 文件存在且内容正确。检查网关日志是否有 “No API key found for provider google-vertex” 或 GCP 认证错误。
2. 登录 GCP Console，确认 Vertex AI API 已启用。
3. 检查 docker-compose.yml 中 workspace 卷的挂载路径是否正确。进入容器检查： docker exec -it <container_name> ls /app/workspace/skills/ 。
4. 查看网关日志中模型调用的详细错误信息。可能是配额不足、区域设置不对或模型名称错误。
运行 npm run start 时，容器立即退出。 1. 入口脚本 scripts/entrypoint.sh 执行错误。
2. 关键环境变量缺失。
3. 端口冲突。		 1. 查看 Docker 日志： docker logs <container_name> （即使已退出，短命容器也有日志）。
2. 检查 docker-compose.yml 中的环境变量，特别是 OPENCLAW_GATEWAY_TOKEN 是否设置。
3. 运行 `netstat -tuln
修改 .env 文件后，网关似乎没有使用新值。 Docker Compose 缓存了环境变量。 停止服务后，使用 docker compose down （或 npm run stop ）清除容器，再 npm run start 重新创建。或者，在 docker-compose.yml 中使用 env_file 指令明确指定 .env 文件路径。
Python 导入 openclaw_agent 模块失败。 1. 未安装依赖。
2. 不在 Poetry 虚拟环境中。		 1. 运行 poetry install 确保安装所有依赖。
2. 使用 poetry run python your_script.py 运行脚本，或先执行 poetry shell 激活虚拟环境。

关于凭证问题的深度排查 ：如果遇到GCP认证问题，可以手动进入容器内部检查环境：

# 找到网关容器的名称或ID
docker ps
# 进入容器shell
docker exec -it openclaw-agent-openclaw-gateway-1 /bin/sh
# 检查凭证文件是否存在且路径正确
ls -la /app/config/
cat /app/config/google-credentials.json | head -5 # 查看前几行，确认格式
# 检查环境变量
echo $GOOGLE_APPLICATION_CREDENTIALS
# 尝试一个简单的gcloud认证测试（如果容器内有gcloud命令）
gcloud auth list

通常， “No API key found for provider google-vertex” 这个错误信息明确指向 auth-profiles.json 文件生成失败，而根本原因往往是 GOOGLE_APPLICATION_CREDENTIALS 指向的JSON文件无法读取或格式错误。

5.3 安全实践与生产部署考量

项目自带的 .gitignore 文件已经很好地排除了 config/google-credentials.json 和 .env 。但在团队协作中，仍需警惕：

  • 绝对不要 将包含真实密钥的配置文件提交到版本库。每次提交前，用 git status 仔细检查。
  • 考虑使用密钥管理服务 ：在本地开发中， .env 文件是方便的，但在生产环境或CI/CD流水线中，应使用更安全的方式，如 Docker Secrets、云厂商的密钥管理服务（如 GCP Secret Manager、AWS Secrets Manager）或 GitHub Actions Secrets，通过环境变量注入。
  • 审查 docker-compose.yml ：当前配置是为了本地开发便利。生产部署时，应考虑：
    • 使用特定的 Docker 镜像标签，而非 latest 。
    • 设置更严格的容器重启策略（如 restart: unless-stopped ）。
    • 考虑将 workspace 目录通过更持久的方式（如云存储卷）挂载，而非本地目录。
    • 配置日志驱动，将容器日志收集到集中式日志系统。

这个 openclaw-agent 项目提供了一个强大、灵活且高度可定制的本地AI智能体开发框架。它巧妙地将复杂的后端服务（OpenClaw网关、AI模型）封装在Docker中，同时通过清晰的文件结构和脚本，让开发者能够专注于智能体“人格”和“技能”的塑造——这才是创造有价值AI应用的核心。从环境搭建到问题排查，整个过程就像在组装一个精密的乐高模型，每一步都有迹可循。当你看到自己定制的智能体根据新的 SOUL.md 指令或自定义技能做出符合预期的回应时，那种成就感正是开源项目魅力的所在。

# AI智能体
Logo
码道开发者社区

码道开发者社区，聚焦华为云码道 CodeArts 代码智能体，沉淀 Agent、Skill、鸿蒙开发实战内容，供开发者查阅资料、交流技术、分享工程实践

更多推荐

Manim 数学动画完全指南：五分钟从零到成片

Manim 是用 Python 驱动的数学动画引擎，把抽象的公式与曲线转成逐帧可控的动态可视化。适合想制作 Python 数学可视化视频的编程新手、数学学生和科普创作者。## 数学为什么需要"动"起来你试过用一张静态图讲清导数的概念吗？切线、割线、极限位置都能画出来，但"割线逼近切线"发生的那一下，观众只能靠脑补。课本插图大多是"结论截图"：只留下最终状态，过程被压缩成一句"易见"。函

avatar 码道开发者社区
cover

Claude API + Python实战：结构化输出后，如何拦住“看起来正确”的JSON

avatar 码道开发者社区
cover

GitHub每日热评｜claude-plugins-community 源码静态分析：一个 Claude 插件社区仓库为什么不适合直接打架构分

avatar 码道开发者社区