养龙虾指南：OpenClaw 中国用户完全手册

2026-03-20 · 阅读约 10 分钟

OpenClaw 社区里，大家把搭建和调优 Agent 的过程戏称为"养龙虾"（Claw = 龙虾钳）。养龙虾看似简单——装个框架、接个模型、定义几个工具就行了——但中国用户在实际操作中会遇到大量海外文档没有提到的坑：网络问题、模型兼容性、中文 Prompt 优化、依赖安装等。

这篇手册专门为中国开发者编写，覆盖从环境配置到生产部署的每一个关键环节。如果你是完全的新手，建议先阅读OpenClaw 新手入门教程了解基础概念。

一、国内网络环境配置

这是中国用户遇到的第一道坎。OpenClaw 的 pip 包本身不大，但它的依赖链很长，在国内直连 PyPI 经常超时。

1.1 使用国内镜像源安装

# 临时使用清华源
pip install openclaw -i https://pypi.tuna.tsinghua.edu.cn/simple

# 永久设置（推荐）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

1.2 Docker 部署方案

如果你的生产环境使用 Docker，推荐使用阿里云容器镜像服务加速：

# Dockerfile
FROM registry.cn-hangzhou.aliyuncs.com/python:3.11-slim
RUN pip install openclaw -i https://pypi.tuna.tsinghua.edu.cn/simple
COPY . /app
WORKDIR /app
CMD ["python", "main.py"]

1.3 离线安装

在完全隔离的内网环境中，你可以先在联网机器上下载所有依赖包，再拷贝到目标机器安装：

# 联网机器：下载所有依赖
pip download openclaw -d ./packages

# 离线机器：从本地目录安装
pip install openclaw --no-index --find-links=./packages

二、国内模型接入指南

OpenClaw 兼容 OpenAI API 协议，国内大多数模型供应商都提供了兼容接口。以下是主流供应商的配置方式：

2.1 DeepSeek

# openclaw.yml
model:
  provider: "openai-compatible"
  api_key: "sk-xxx"
  base_url: "https://api.deepseek.com/v1"
  model_name: "deepseek-chat"

2.2 阿里云百炼（通义千问）

model:
  provider: "openai-compatible"
  api_key: "sk-xxx"
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  model_name: "qwen3-coder-plus"

2.3 智谱 AI（GLM）

model:
  provider: "openai-compatible"
  api_key: "xxx.xxx"
  base_url: "https://open.bigmodel.cn/api/paas/v4"
  model_name: "glm-5"

不同模型在 tool calling 场景下的表现差异很大。我们的10 个模型实测对比数据显示，MiniMax-M2.5 在多步任务中完成率最高，而 DeepSeek-V3 在性价比方面最优。

三、中文 Prompt 优化技巧

大多数模型的 tool calling 能力是基于英文训练的，中文指令可能导致调用成功率下降。以下是经过实测验证的优化技巧：

3.1 工具描述使用中英双语

@tool(description="搜索网页内容 (Search web content and return top results)")
def web_search(query: str) -> str:
    ...

我们测试发现，中英双语描述比纯中文描述的工具调用准确率高 12%。模型在选择工具时，英文关键词能提供更精准的语义匹配。

3.2 System Prompt 中明确指定行为

system_prompt = """你是一个任务执行助手。
规则：
1. 需要信息时，必须先调用工具获取，不要猜测
2. 工具调用失败时，尝试替代方案，不要直接放弃
3. 多步任务必须逐步完成，不能跳步
4. 返回结果必须基于工具返回的真实数据"""

这四条规则对应了我们在Tool Calling 失败分析中发现的四个最常见问题。明确写入 system prompt 可以有效降低失败率。

3.3 参数命名保持英文

虽然工具描述可以用中文，但参数名称强烈建议使用英文。中文参数名在某些模型的 JSON 序列化中会出现编码问题：

# 不推荐
def search(搜索词: str) -> str:

# 推荐
def search(query: str) -> str:
    """Args: query: 搜索关键词"""

四、常见坑点与解决方案

坑点 1：SSL 证书验证失败

部分企业网络环境存在 SSL 中间人代理，导致 API 请求失败。临时解决：在配置中添加 verify_ssl: false。长期建议将代理证书加入系统信任链。

坑点 2：Token 计费差异

中文文本的 token 数量通常是英文的 1.5-2 倍。一个 500 字的中文 prompt 可能消耗 800-1000 个 token。在预算规划时要考虑这个因素。

坑点 3：时区与日期格式

工具返回的时间默认是 UTC 格式。如果你的 Agent 需要处理中国时间，记得在工具实现中做时区转换：

from datetime import datetime, timezone, timedelta

cst = timezone(timedelta(hours=8))
now = datetime.now(cst).strftime("%Y-%m-%d %H:%M")

坑点 4：并发请求限制

国内模型 API 通常有严格的 QPS 限制（每秒请求数）。DeepSeek 免费版限制 2 QPS，百炼限制 5 QPS。在多 Agent 并发场景下，务必添加请求队列和限流逻辑。

五、生产环境部署建议

从开发环境到生产环境，还需要关注以下几点：

  1. 日志记录 — 记录每次 tool calling 的输入输出，便于排查问题
  2. 监控告警 — 设置 tool calling 成功率监控，低于阈值时自动告警
  3. 模型降级 — 主模型不可用时自动切换到备用模型
  4. 成本控制 — 设置每日 token 消耗上限，防止异常消耗

如果你不想从零搭建这些基础设施，ClawTune 提供了开箱即用的智能路由、监控和自动降级功能，一行配置即可接入。

总结

养龙虾的过程充满挑战，但只要避开这些已知的坑，就能大大缩短从入门到生产的路径。本文覆盖的核心要点：国内镜像加速安装、主流模型接入配置、中文 Prompt 优化三板斧（双语描述、明确规则、英文参数名）、以及生产环境的四个必备能力。

更多关于 AI Agent 工具的对比分析，可以阅读我们的2026 年 AI Agent 工具对比。

一行配置，让你的龙虾更聪明

ClawTune 专为中国开发者优化，内置国内模型适配、中文 Prompt 增强、自动错误恢复。免费体验版每天 50 次调用。

立即开始 →