# travel-claw

**Repository Path**: cuixc2018/travel-claw

## Basic Information

- **Project Name**: travel-claw
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Travel Claw - OpenClaw Python SDK & API Server

完整的 OpenClaw Python SDK 和 HTTP/WebSocket API 服务器。

## 功能

1. **Python SDK** - 完整的 Python 客户端库
   - 技能列表管理
   - Agent 对话（同步/流式）
   - 会话管理

2. **HTTP REST API** - 标准 REST 接口
   - 技能列表和详情
   - 对话接口
   - 流式对话 (SSE)

3. **WebSocket API** - 实时双向通信
   - 低延迟对话
   - 实时事件流
   - 自动上下文保持

## 文档

- **[README.md](README.md)** - 本文档（快速开始）
- **[API.md](API.md)** - Python SDK 完整文档
- **[API_DOCS.md](API_DOCS.md)** - HTTP/WebSocket API 完整文档
- **[CONFIG.md](CONFIG.md)** - 配置说明
- **[QUICKSTART.md](QUICKSTART.md)** - 快速入门指南
- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - 故障排除

## 快速开始

### 1. 配置环境

```bash
cd /Users/cuixiucheng/workspace/travel_claw

# 复制配置模板
cp .env.example .env

# 编辑 .env 文件，根据你的环境修改配置
# 本地开发：OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789
# 服务器：OPENCLAW_GATEWAY_URL=http://127.0.0.1:10183
```

详细配置说明请查看 **[CONFIG.md](CONFIG.md)**

### 2. 安装依赖

```bash
# SDK 依赖
pip install -r requirements.txt

# API 服务器依赖
pip install -r requirements-api.txt
```

### 3. 启动 API 服务器

```bash
python3 server.py
```

服务器将在配置的端口启动（默认 `http://localhost:8000`）。

访问：
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

启动时会显示当前配置：
```
📡 Gateway URL: http://127.0.0.1:18789
🔌 Gateway WS URL: ws://127.0.0.1:18789
🔑 Token: 已配置
🚀 Server Port: 8000
```

### 4. 使用 Python SDK

```python
from travel_claw import OpenClawClient

client = OpenClawClient()

# 列出技能
skills = client.list_skills()
print(f"找到 {len(skills)} 个技能")

# 对话
response = client.chat(
    message="北京明天天气怎么样？",
    agent_id="default",
    verbose=True
)

print(response['content'])
```

## API 端点

### HTTP REST API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/` | GET | API 信息 |
| `/api/skills` | GET | 技能列表 |
| `/api/skills/{name}` | GET | 技能详情 |
| `/api/chat` | POST | 对话 |
| `/api/chat/stream` | POST | 流式对话 (SSE) |
| `/health` | GET | 健康检查 |
| `/ready` | GET | 就绪检查 |

### WebSocket API

| 端点 | 说明 |
|------|------|
| `/ws/chat` | WebSocket 对话 |

完整 API 文档请查看 **[API_DOCS.md](API_DOCS.md)**

## 使用示例

### HTTP 对话

```bash
# 简单对话
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "北京明天天气怎么样？",
    "agent_id": "default"
  }'

# 多轮对话（保持上下文）
SESSION_ID="abc123"
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"你还记得我叫什么吗？\",
    \"session_id\": \"$SESSION_ID\"
  }"
```

### WebSocket 对话

```javascript
// JavaScript 客户端
const ws = new WebSocket('ws://localhost:8000/ws/chat');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'message',
    content: '你好'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};
```

## 项目结构

```
travel_claw/
├── travel_claw/           # Python SDK
│   ├── client.py          # 主客户端
│   ├── skills.py          # 技能管理
│   └── chat.py            # 对话功能
├── server.py              # API 服务器
├── ws_server.py           # WebSocket 服务器
├── openclaw_tracer.py     # 执行追踪器
├── travel_claw_cli.py     # 命令行工具
├── .env.example           # 配置模板
├── CONFIG.md              # 配置说明
└── README.md              # 本文档
```

## 配置

所有配置通过 `.env` 文件管理，详见 **[CONFIG.md](CONFIG.md)**

主要配置项：
- `OPENCLAW_GATEWAY_URL`: Gateway HTTP 地址
- `OPENCLAW_GATEWAY_WS_URL`: Gateway WebSocket 地址
- `OPENCLAW_GATEWAY_TOKEN`: Gateway token（可选，留空自动读取）
- `OPENCLAW_WORKSPACE`: 工作空间路径
- `SERVER_PORT`: API 服务器监听端口

## 生产部署

### Docker

```bash
docker build -t travel-claw-api .
docker run -p 8000:8000 travel-claw-api
```

### Systemd

```bash
sudo cp travel-claw-api.service /etc/systemd/system/
sudo systemctl start travel-claw-api
```

## 监控

```bash
# 健康检查
curl http://localhost:8000/health

# 就绪检查
curl http://localhost:8000/ready
```

## License

MIT