Coze 安装与部署

安装与部署

Coze 是 SaaS，没有本地安装包。所谓部署由三件事组成：平台上把 Bot 建好并发布、拿到 API 凭证、在自有服务里把调用链接上。

第一步：开通与建 Bot

国内版入口是 coze.cn，海外版是 coze.com，账号与 API 域名不互通。国内业务用 api.coze.cn，海外用 api.coze.com，混用会直接拿到鉴权失败。

登录后进工作空间新建智能体，必填的是名称与「人设与回复逻辑」，它决定行为边界。写的时候把三件事讲清：角色是谁、能做什么、不能做什么。例如课程咨询场景可写成「你是某在线教育平台的课程顾问，只回答与课程内容、上课方式、退费规则有关的问题；涉及价格优惠时引导用户留资由人工跟进；不确定的信息不要编造，回复『我帮您转人工确认』」。建好后先拿两个标识：bot_id（编辑页 URL 里的一长串数字）与空间 ID。

第二步：环境准备与凭证

令牌在「个人设置 → 个人访问令牌」创建。建议每个环境单独一个，命名写清用途（如 prod-course-bot），只勾选真正需要的能力：只做对话就只给 Chat 权限，要跑工作流再加 Workflow 权限。令牌泄漏等同于账号在该空间下的调用权限被拿走。

# .env  —— 加入 .gitignore，绝不硬编码
COZE_API_TOKEN=pat_xxxxxxxxxxxxxxxxxxxxxxxx
COZE_BOT_ID=7400000000000000000
COZE_BASE_URL=https://api.coze.cn
COZE_WORKFLOW_ID=7400000000000000001

# Python：官方 SDK cozepy
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install cozepy python-dotenv

# Node：官方 SDK 或直接用 Node 18+ 自带的 fetch
npm i @coze/api

第三步：用 Python 发起一次对话

先跑通非流式，再上流式，出错时更好定位。

# chat_demo.py
import os
from dotenv import load_dotenv
from cozepy import COZE_CN_BASE_URL, Coze, TokenAuth, Message

load_dotenv()

coze = Coze(
    auth=TokenAuth(token=os.environ["COZE_API_TOKEN"]),
    base_url=COZE_CN_BASE_URL,
)

chat = coze.chat.create(
    bot_id=os.environ["COZE_BOT_ID"],
    user_id="demo_user_001",
    additional_messages=[
        Message.build_user_question_text("用一句话说明什么是智能体")
    ],
)
chat = coze.chat.retrieve(
    conversation_id=chat.conversation_id, chat_id=chat.id
)
if chat.status != "completed":
    raise RuntimeError(f"chat 未完成: {chat.status} / {chat.last_error}")

for msg in coze.chat.messages.list(
    conversation_id=chat.conversation_id, chat_id=chat.id
):
    if msg.role == "assistant" and msg.type == "answer":
        print(msg.content)

两个容易忽略的点：user_id 必须稳定，同一终端用户每次传同一个值，否则会话历史与用户变量都对不上；conversation_id 要存下来，多轮对话靠它串联，丢了等于每轮重开。

第四步：用 Node 发起一次对话

// chat-demo.mjs
const BASE = process.env.COZE_BASE_URL ?? "https://api.coze.cn";

const res = await fetch(`${BASE}/v3/chat`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.COZE_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    bot_id: process.env.COZE_BOT_ID,
    user_id: "demo_user_001",
    stream: false,
    auto_save_history: true,
    additional_messages: [
      { role: "user", content: "你好，介绍一下你能做什么", content_type: "text" },
    ],
  }),
});

const created = await res.json();
if (created.code !== 0) {
  throw new Error(`创建会话失败: ${created.code} ${created.msg}`);
}
console.log("chat_id =", created.data.id);
console.log("conversation_id =", created.data.conversation_id);

Authorization 写成 Bearer 加一个空格再加令牌；令牌本身已含 pat_ 前缀，不要重复拼接，也不要去掉。

常见报错与排查