# 🚀 Trae CN + OpenClaw 集成快速配置指南

## 第一步：获取火山方舟 API Key

1. 访问 [火山方舟 Coding Plan 活动页面](https://www.volcengine.com/activity/codingplan)
2. 按需订阅套餐（免费试用或付费）
3. 获取 API Key：https://console.volcengine.com/ark/region:ark+cn-beijing/apikey

## 第二步：配置 API Key

### 方式 A：环境变量（推荐用于测试）

```bash
export ANTHROPIC_AUTH_TOKEN=你的API Key
export ANTHROPIC_BASE_URL=https://ark.cn-beijing.volces.com/api/coding
export ANTHROPIC_MODEL=doubao-seed-2.0-code
```

### 方式 B：配置文件（推荐用于生产）

```bash
# 复制配置模板
cp ~/.qclaw/workspace/trae-cn-mcp/config/api-key.env.example ~/.qclaw/workspace/trae-cn-mcp/config/api-key.env

# 编辑配置文件，填入你的 API Key
nano ~/.qclaw/workspace/trae-cn-mcp/config/api-key.env
```

配置文件内容：
```env
ANTHROPIC_AUTH_TOKEN=你的API Key
ANTHROPIC_BASE_URL=https://ark.cn-beijing.volces.com/api/coding
ANTHROPIC_MODEL=doubao-seed-2.0-code
```

## 第三步：启动 MCP Server

```bash
# 方式 1：使用启动脚本
cd ~/.qclaw/workspace/trae-cn-mcp
./scripts/start.sh

# 方式 2：直接运行
NODE_PATH="$HOME/.nvm/versions/node/v22.22.1/bin/node"
$NODE_PATH ~/.qclaw/workspace/trae-cn-mcp/src/server.js --project ~/编程/invest-diary
```

## 第四步：测试 MCP Server

> ⚠️ **注意：** 这是一个 **stdio 协议** 的 MCP Server，通过标准输入输出通信，**不监听任何端口**。
> 不要使用 `nc localhost 8788` 等 TCP 连接方式测试，那会失败。

正确的测试方式是通过管道直接向进程发送 JSON：

```bash
NODE="$HOME/.nvm/versions/node/v22.22.1/bin/node"
SERVER="$HOME/.qclaw/workspace/trae-cn-mcp/src/server.js"

# 测试 1：initialize（验证服务器能正常启动并响应）
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  | ANTHROPIC_AUTH_TOKEN=你的API Key $NODE $SERVER

# 测试 2：tools/list（验证工具列表）
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | ANTHROPIC_AUTH_TOKEN=你的API Key $NODE $SERVER
```

**预期输出：**
```json
{"id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{},"resources":{}},"serverInfo":{"name":"trae-cn-mcp","version":"1.0.0"}}}
```

如果看到上面的 JSON 响应，说明 MCP Server 工作正常。

## 第五步：集成到 OpenClaw

在 OpenClaw 配置文件中添加 MCP Server：

```json
{
  "mcpServers": {
    "trae-cn": {
      "command": "node",
      "args": ["/Users/bill/.qclaw/workspace/trae-cn-mcp/src/server.js"],
      "env": {
        "ANTHROPIC_AUTH_TOKEN": "你的API Key",
        "ANTHROPIC_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding",
        "ANTHROPIC_MODEL": "doubao-seed-2.0-code"
      }
    }
  }
}
```

> ⚠️ **安全警告：不要将真实 API Key 直接写入此配置文件！**
> - 推荐做法：先 `export ANTHROPIC_AUTH_TOKEN=你的Key`，然后配置中引用环境变量
> - 确认此配置文件已加入 `.gitignore`，避免误提交到代码仓库
> - 如果配置文件被提交到 Git，API Key 将永久暴露在历史记录中，即使后来删除也无法消除

## 可用工具

| 工具 | 说明 |
|------|------|
| `chat` | 发送消息给 AI |
| `read_file` | 让 AI 读取文件 |
| `write_file` | 让 AI 写入文件 |
| `run_command` | 让 AI 执行命令 |
| `new_session` | 创建新会话 |
| `list_sessions` | 列出所有会话 |

## 使用示例

### 在 OpenClaw 中调用

```
使用工具: trae-cn/chat
参数: {
  "message": "帮我分析 pages/index/index.js 中的 bug",
  "project": "~/编程/invest-diary"
}
```

### 在命令行中测试

```bash
# 发送消息
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"chat","arguments":{"message":"你好，请介绍一下自己"}}}' | node ~/.qclaw/workspace/trae-cn-mcp/src/server.js
```

## 支持的模型

> 📖 以下模型列表最后更新时间：2026-03-25，最新支持模型请以[火山方舟官方文档](https://www.volcengine.com/docs/82379/1928262?lang=zh)为准。

- `doubao-seed-2.0-code` ⭐ 推荐
- `doubao-seed-2.0-pro`
- `doubao-seed-2.0-lite`
- `doubao-seed-code`
- `minimax-m2.5`
- `glm-4.7`
- `deepseek-v3.2`
- `kimi-k2.5`
- `ark-code-latest`（通过控制台切换）

## 常见问题

### Q: 如何切换模型？

**方式 1：修改环境变量**
```bash
export ANTHROPIC_MODEL=kimi-k2.5
./scripts/start.sh
```

**方式 2：使用 ark-code-latest**
```bash
# 配置文件中设置
ANTHROPIC_MODEL=ark-code-latest

# 然后在火山方舟控制台选择默认模型
# https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement
```

### Q: 如何验证配置是否正确？

1. 启动 MCP Server
2. 查看日志输出，确认 API Key 已设置
3. 发送测试请求

### Q: 如何查看 API 使用情况？

访问火山方舟控制台：
https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement

### Q: 如何升级 Claude Code CLI？

Trae CN 会自动更新 Claude Code CLI，无需手动操作。

## 🔧 故障排查

### 启动失败

| 症状 | 原因 | 解决方案 |
|------|------|---------|
| `Claude Code CLI 不存在` | Trae CN 未安装或版本过旧 | 安装/更新 Trae CN |
| `ANTHROPIC_AUTH_TOKEN 未设置` | API Key 未配置 | 按第二步配置 API Key |
| `command not found: node` | Node.js 路径问题 | 使用完整路径 `~/.nvm/versions/node/v22.22.1/bin/node` |

### 测试无响应

MCP Server 是 **stdio 协议**，不监听端口。测试时必须通过管道传入 JSON，不能用 `nc`、`curl` 等 TCP 工具。

```bash
# ✅ 正确
echo '{"jsonrpc":"2.0","id":1,"method":"initialize",...}' | node src/server.js

# ❌ 错误（会失败）
nc localhost 8788
curl http://localhost:8788
```

### OpenClaw 无法连接 MCP

1. 检查 OpenClaw 配置文件中 `command` 路径是否正确（需要绝对路径）
2. 检查 `ANTHROPIC_AUTH_TOKEN` 是否已在 `env` 中配置
3. 重启 OpenClaw 使配置生效
4. 查看 OpenClaw 日志确认 MCP Server 是否被正确启动

### API 调用失败

| 错误码 | 原因 | 解决方案 |
|--------|------|---------|
| 401 | API Key 无效或过期 | 重新获取 API Key |
| 403 | 无权限访问该模型 | 在控制台开通对应模型 |
| 429 | 超过频率限制 | 等待后重试，或升级套餐 |
| 500 | 服务端错误 | 稍后重试 |

## 文件位置

- MCP Server: `~/.qclaw/workspace/trae-cn-mcp/src/server.js`
- 启动脚本: `~/.qclaw/workspace/trae-cn-mcp/scripts/start.sh`
- Skill 文档: `~/.qclaw/workspace/skills/trae-cn-claude-code/SKILL.md`
- 配置模板: `~/.qclaw/workspace/trae-cn-mcp/config/api-key.env.example`

## 官方文档

📖 [火山方舟 Claude Code 接入指南](https://www.volcengine.com/docs/82379/1928262?lang=zh)

---

**准备好了吗？** 按照上面的步骤配置，然后告诉我结果！

---

## 🔐 安全操作指南

### API Key 安全

#### 权限最小化配置

1. **创建专用 API Key**
   - 不要使用主账户 API Key
   - 在火山方舟控制台创建专用的 API Key
   - 仅授予 Coding Plan 相关权限

2. **限制 API Key 使用范围**
   - 设置 IP 白名单（如果支持）
   - 设置使用配额限制
   - 定期审查使用日志

#### 定期轮换密钥

**建议每 90 天轮换一次 API Key：**

```bash
# 1. 在火山方舟控制台生成新 API Key
# 2. 更新配置文件
nano ~/.qclaw/workspace/trae-cn-mcp/config/api-key.env

# 3. 重启 MCP Server
cd ~/.qclaw/workspace/trae-cn-mcp
./scripts/start.sh

# 4. 在火山方舟控制台删除旧 API Key
```

### 文件权限安全

配置文件应该只有你能读写：

```bash
# 检查权限
ls -la ~/.qclaw/workspace/trae-cn-mcp/config/api-key.env

# 如果权限不对，修改为 0600
chmod 600 ~/.qclaw/workspace/trae-cn-mcp/config/api-key.env
```

### 日志安全

- 日志文件存储在 `logs/` 目录
- 仅保留最近 30 天的日志
- 日志中不包含完整的 API Key（仅显示前 4 位）
- 定期检查日志中是否有异常调用

### 代码仓库安全

- ✅ `.gitignore` 已配置，`api-key.env` 不会被提交
- ✅ 仅 `api-key.env.example` 会被提交
- ✅ 定期检查 Git 历史，确保没有密钥被误提交

### 监控和告警

定期检查以下指标：

1. **API 调用频率**
   - 正常：每分钟 < 10 次
   - 异常：突然增加可能表示代码 bug

2. **API 错误率**
   - 监控 401/403 错误（可能表示密钥过期）
   - 监控 429 错误（超过配额）

3. **成本监控**
   - 定期查看火山方舟控制台的使用统计
   - 设置成本告警阈值