weclawbot

package module
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 26, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

README

weclawbot

weclawbot 是微信 ClawBot HTTP JSON 协议的 Go SDK,提供二维码登录、消息长轮询和文本消息发送能力。

协议参考 Tencent/openclaw-weixin。当前实现基于提交 24de5c9eb0dd5e595d7e2d090ed8a3f82870d42c 对应的协议和客户端行为。

环境要求

  • Go 1.27 或更高版本

安装

go get github.com/go-sdk/weclawbot

登录流程

先创建匿名客户端并获取二维码:

client := weclawbot.New()

qr, err := client.GetQRCode(ctx, weclawbot.GetQRCodeRequest{})
if err != nil {
	return err
}

fmt.Println(qr.QRCodeImageContent)

也可以直接将二维码输出到 Console:

if err := qr.PrintQRCode(); err != nil {
	return err
}

WriteQRCode(writer) 可以输出到其他 io.Writer。二维码编码内容来自服务端返回的 qrcode_img_content;二维码本身属于登录凭证,只应输出到可信终端。

调用方展示 QRCodeImageContent,随后循环查询状态:

baseURL := ""
verifyCode := ""

for {
	status, err := client.GetQRCodeStatus(ctx, weclawbot.GetQRCodeStatusRequest{
		QRCode:     qr.QRCode,
		VerifyCode: verifyCode,
		BaseURL:    baseURL,
	})
	if err != nil {
		return err
	}

	switch status.Status {
	case weclawbot.QRCodeStatusWait, weclawbot.QRCodeStatusScanned:
		continue
	case weclawbot.QRCodeStatusNeedVerifyCode:
		verifyCode = readVerifyCodeFromUser()
	case weclawbot.QRCodeStatusScannedRedirect:
		baseURL, err = status.RedirectBaseURL()
		if err != nil {
			return err
		}
	case weclawbot.QRCodeStatusConfirmed:
		botClient := weclawbot.New(
			weclawbot.WithBaseURL(status.BaseURL),
			weclawbot.WithToken(status.BotToken),
		)
		return runMessages(ctx, botClient)
	case weclawbot.QRCodeStatusExpired,
		weclawbot.QRCodeStatusVerifyCodeBlocked,
		weclawbot.QRCodeStatusBoundRedirect:
		return errLoginStopped
	}
}

SDK 不读取终端输入、不自动刷新二维码,也不保存 BotToken。调用方应根据业务界面取得验证码,并安全保存确认响应中的 Token、Bot ID、API 地址和用户 ID。

接收消息

GetUpdates 每次执行一次长轮询。首次请求使用空游标,之后回传服务端返回的非空游标:

cursor := ""

for {
	updates, err := botClient.GetUpdates(ctx, weclawbot.GetUpdatesRequest{
		Cursor: cursor,
	})
	if err != nil {
		if weclawbot.IsSessionExpired(err) {
			return relogin()
		}
		return err
	}

	cursor = updates.NextCursor(cursor)
	for _, message := range updates.Messages {
		fmt.Println(message.FromUserID, message.ContextToken)
	}
}

服务端可能通过 longpolling_timeout_ms 建议下一次超时,可使用 updates.LongPollingTimeout() 读取。单次内部长轮询超时返回空消息;调用方主动取消仍返回 context.Canceled 或 context.DeadlineExceeded。

消息中的 message_id 和 msg_id 使用 MessageID 字符串类型,无损兼容服务端返回的 JSON 数字或字符串。

发送文本

回复入站消息时,应把发送者 ID 和会话上下文原样带回:

result, err := botClient.SendText(ctx, weclawbot.SendTextRequest{
	ToUserID:     message.FromUserID,
	ContextToken: message.ContextToken,
	RunID:        message.RunID,
	Text:         "收到",
})
if err != nil {
	return err
}

fmt.Println(result.ClientID, result.MessageID)

context_token 在 SDK 中保持可选,以兼容腾讯当前客户端行为;但协议没有保证服务端一定接受缺少上下文的主动发送,生产环境应通过真实账号验证。

Client 配置

client := weclawbot.New(
	weclawbot.WithBaseURL("https://ilinkai.weixin.qq.com"),
	weclawbot.WithToken(token),
	weclawbot.WithRouteTag(routeTag),
	weclawbot.WithChannelVersion("1.0.0"),
	weclawbot.WithBotAgent("ExampleBot/1.0.0"),
	weclawbot.WithTimeout(15*time.Second),
	weclawbot.WithLongPollTimeout(35*time.Second),
)

未覆盖版本时,SDK 尝试从 Go 构建信息读取自身模块版本,开发态回退为 0.0.0。应用请求头中的版本按协议编码为 0x00MMNNPP 的十进制字符串。

API 地址默认只允许 HTTPS。仅在可信的开发或测试环境需要连接明文 HTTP 服务时,才显式传入 weclawbot.WithInsecureHTTP();HTTP 会明文传输 Bot Token、用户 ID、消息内容和上下文凭证,不应在生产环境启用。

错误处理

错误使用 core/errx 判断:

switch {
case errx.Is(err, weclawbot.ErrSessionExpired):
	// Token 已失效,需要重新登录。
case errx.Is(err, weclawbot.ErrRequest):
	// DNS、连接、TLS 或其他请求级失败。
case errx.Is(err, weclawbot.ErrHTTPStatus):
	// 服务端返回非 2xx 状态。
case errx.Is(err, weclawbot.ErrProtocol):
	// 响应缺少必要字段或返回非零业务码。
}

SDK 自身的错误信息不会包含 Bot Token、二维码值、验证码、context_token 或完整响应体。 Client 保持 core/restx 的调试行为;启用调试模式可能输出请求 Header、查询参数或请求体,生产环境应根据敏感信息策略控制调试开关。

当前边界

  • 支持获取二维码、验证码回传、IDC 重定向和登录确认。
  • 支持 getUpdates 游标、服务端建议超时和 -14 会话失效。
  • 支持接收文本消息和发送文本消息。
  • 不持久化账号、Token、游标或上下文。
  • 不实现图片、语音、文件和视频的上传、下载、解密或发送。
  • 不实现 getConfig、sendTyping、notifyStart 或 notifyStop。

开发

make lint
make test

测试使用本地 HTTP 传输替身,不访问真实微信接口。静态检查和本地测试不能证明真实账号登录、服务端路由或主动发送行为。

显式运行真实微信闭环测试:

make test-network

该测试会访问真实微信接口,在 Console 输出二维码并等待人工扫码;登录成功后需要向 Bot 发送一条消息,测试会使用收到的 from_user_id/context_token 回复 wechat network test: received。普通 make test 不会执行该真实调用流程。

如果已经保存了发送所需参数,可以单独执行环境变量驱动的真实发送测试:

export WECHAT_BOT_TOKEN="<Bot Token>"
export WECHAT_TO_USER_ID="<目标用户 ID>"
export WECHAT_TEXT="<可选,消息内容>"
export WECHAT_BASE_URL="https://<可选,登录返回的 API 地址>"
export WECHAT_CONTEXT_TOKEN="<可选,最新 Context Token>"
export WECHAT_RUN_ID="<可选 Run ID>"

make test-send

WECHAT_BOT_TOKEN 和 WECHAT_TO_USER_ID 为必填。WECHAT_BASE_URL 为空时使用 https://ilinkai.weixin.qq.com;WECHAT_TEXT 为空时发送 测试消息 加当前 RFC3339 时间,例如 测试消息 2026-09-24T14:30:25+08:00;WECHAT_CONTEXT_TOKEN 和 WECHAT_RUN_ID 可以为空。测试只记录返回的 Client ID 和 Message ID,不输出 Token、用户 ID 或 Context Token。该命令会向真实微信用户发送消息,普通 make test 不会执行。

Documentation

Overview

Package weclawbot 提供微信 ClawBot 的二维码登录、消息长轮询和文本消息发送能力。

SDK 不持久化 Bot Token、二维码、验证码或消息上下文。调用方负责安全保存登录结果, 并在回复消息时把 getUpdates 返回的 from_user_id 和 context_token 传给 SendText。 媒体上传、下载、加解密和媒体消息发送不在当前支持范围内。

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrTokenRequired 表示当前操作必须提供二维码登录取得的 Bot Token。
	ErrTokenRequired = errx.New("bot token is required")
	// ErrQRCodeRequired 表示二维码状态查询缺少二维码值。
	ErrQRCodeRequired = errx.New("qrcode is required")
	// ErrQRCodeContentRequired 表示二维码响应缺少可供编码展示的内容。
	ErrQRCodeContentRequired = errx.New("qrcode content is required")
	// ErrWriterRequired 表示二维码输出缺少目标 Writer。
	ErrWriterRequired = errx.New("writer is required")
	// ErrUserIDRequired 表示文本消息缺少目标用户 ID。
	ErrUserIDRequired = errx.New("user id is required")
	// ErrTextRequired 表示文本消息内容为空。
	ErrTextRequired = errx.New("text is required")
	// ErrTooManyLocalTokens 表示二维码请求携带了超过协议上限的本地 Token。
	ErrTooManyLocalTokens = errx.New("too many local tokens")
	// ErrInvalidURL 表示 API 地址或重定向地址不安全或无效。
	ErrInvalidURL = errx.New("invalid api url")
	// ErrRequest 表示请求未获得有效 HTTP 响应,底层错误可能包含敏感查询参数而不会透出。
	ErrRequest = errx.New("wechat request failed")
	// ErrHTTPStatus 表示微信接口返回了非成功 HTTP 状态。
	ErrHTTPStatus = errx.New("unexpected http status")
	// ErrProtocol 表示微信接口响应缺失必要字段或返回业务错误。
	ErrProtocol = errx.New("wechat protocol error")
	// ErrSessionExpired 表示 Bot Token 已失效,需要重新登录。
	ErrSessionExpired = errx.New("wechat session expired")
)

Functions

func IsSessionExpired

func IsSessionExpired(err error) bool

IsSessionExpired 判断 getUpdates 是否返回需要重新登录的会话失效错误。

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client 是微信 ClawBot HTTP JSON 协议客户端。

func New

func New(opts ...Option) *Client

New 创建使用统一 restx 默认配置的客户端。

func (*Client) GetQRCode

func (c *Client) GetQRCode(ctx context.Context, request GetQRCodeRequest) (*GetQRCodeResponse, error)

GetQRCode 获取微信登录二维码。该请求始终使用微信固定登录入口。

func (*Client) GetQRCodeStatus

func (c *Client) GetQRCodeStatus(ctx context.Context, request GetQRCodeStatusRequest) (*GetQRCodeStatusResponse, error)

GetQRCodeStatus 执行一次二维码状态长轮询。内部超时返回 wait,调用方取消返回错误。

func (*Client) GetUpdates

func (c *Client) GetUpdates(ctx context.Context, request GetUpdatesRequest) (*GetUpdatesResponse, error)

GetUpdates 执行一次消息长轮询。内部超时返回空消息,调用方取消返回错误。

func (*Client) SendText

func (c *Client) SendText(ctx context.Context, request SendTextRequest) (*SendTextResponse, error)

SendText 主动发送或回复一条文本消息。

type GetQRCodeRequest

type GetQRCodeRequest struct {
	LocalTokens []string
}

GetQRCodeRequest 配置登录二维码请求。

type GetQRCodeResponse

type GetQRCodeResponse struct {
	QRCode             string `json:"qrcode"`
	QRCodeImageContent string `json:"qrcode_img_content"`
}

GetQRCodeResponse 返回二维码值和用于展示的二维码内容。

func (GetQRCodeResponse) PrintQRCode

func (r GetQRCodeResponse) PrintQRCode() error

PrintQRCode 将二维码输出到标准输出。

func (GetQRCodeResponse) WriteQRCode

func (r GetQRCodeResponse) WriteQRCode(writer io.Writer) error

WriteQRCode 将二维码以适合终端显示的半高字符写入目标 Writer。

type GetQRCodeStatusRequest

type GetQRCodeStatusRequest struct {
	QRCode     string
	VerifyCode string
	BaseURL    string
}

GetQRCodeStatusRequest 配置一次二维码状态长轮询。

type GetQRCodeStatusResponse

type GetQRCodeStatusResponse struct {
	Status       QRCodeStatus `json:"status"`
	BotToken     string       `json:"bot_token,omitempty"`
	BotID        string       `json:"ilink_bot_id,omitempty"`
	BaseURL      string       `json:"baseurl,omitempty"`
	UserID       string       `json:"ilink_user_id,omitempty"`
	RedirectHost string       `json:"redirect_host,omitempty"`
}

GetQRCodeStatusResponse 返回当前登录状态及确认后的账号凭证。

func (GetQRCodeStatusResponse) RedirectBaseURL

func (r GetQRCodeStatusResponse) RedirectBaseURL() (string, error)

RedirectBaseURL 校验并返回 scaned_but_redirect 状态提供的新轮询地址。

type GetUpdatesRequest

type GetUpdatesRequest struct {
	Cursor  string
	Timeout time.Duration
}

GetUpdatesRequest 配置一次消息长轮询。

type GetUpdatesResponse

type GetUpdatesResponse struct {
	Ret                  *int      `json:"ret,omitempty"`
	ErrorCode            *int      `json:"errcode,omitempty"`
	ErrorMessage         string    `json:"errmsg,omitempty"`
	Messages             []Message `json:"msgs,omitempty"`
	Cursor               string    `json:"get_updates_buf,omitempty"`
	LongPollingTimeoutMS int64     `json:"longpolling_timeout_ms,omitempty"`
}

GetUpdatesResponse 返回消息、下次游标和服务端建议的长轮询超时。

func (GetUpdatesResponse) LongPollingTimeout

func (r GetUpdatesResponse) LongPollingTimeout() time.Duration

LongPollingTimeout 返回服务端建议的下一次消息长轮询超时。

func (GetUpdatesResponse) NextCursor

func (r GetUpdatesResponse) NextCursor(current string) string

NextCursor 返回服务端提供的非空游标;空游标时保留当前值。

type Message

type Message struct {
	Sequence     int64         `json:"seq,omitempty"`
	MessageID    MessageID     `json:"message_id,omitempty"`
	FromUserID   string        `json:"from_user_id,omitempty"`
	ToUserID     string        `json:"to_user_id,omitempty"`
	ClientID     string        `json:"client_id,omitempty"`
	CreateTimeMS int64         `json:"create_time_ms,omitempty"`
	UpdateTimeMS int64         `json:"update_time_ms,omitempty"`
	DeleteTimeMS int64         `json:"delete_time_ms,omitempty"`
	SessionID    string        `json:"session_id,omitempty"`
	GroupID      string        `json:"group_id,omitempty"`
	Type         MessageType   `json:"message_type,omitempty"`
	State        MessageState  `json:"message_state,omitempty"`
	Items        []MessageItem `json:"item_list,omitempty"`
	ContextToken string        `json:"context_token,omitempty"`
	RunID        string        `json:"run_id,omitempty"`
}

Message 表示 getUpdates 返回的微信消息。

type MessageID

type MessageID string

MessageID 无损保存微信协议中可能以 JSON 数字或字符串返回的 uint64 ID。

func (*MessageID) UnmarshalJSON

func (id *MessageID) UnmarshalJSON(data []byte) error

UnmarshalJSON 同时接受 JSON 数字和字符串,避免转换为浮点数造成精度损失。

type MessageItem

type MessageItem struct {
	Type         MessageItemType `json:"type,omitempty"`
	CreateTimeMS int64           `json:"create_time_ms,omitempty"`
	UpdateTimeMS int64           `json:"update_time_ms,omitempty"`
	Completed    bool            `json:"is_completed,omitempty"`
	MessageID    MessageID       `json:"msg_id,omitempty"`
	Text         *TextItem       `json:"text_item,omitempty"`
}

MessageItem 表示单个消息内容项。媒体类型当前仅保留类型信息,不执行下载或解码。

type MessageItemType

type MessageItemType int

MessageItemType 表示消息内容类型。

const (
	MessageItemTypeNone MessageItemType = iota
	MessageItemTypeText
	MessageItemTypeImage
	MessageItemTypeVoice
	MessageItemTypeFile
	MessageItemTypeVideo
	MessageItemTypeToolCallStart  MessageItemType = 11
	MessageItemTypeToolCallResult MessageItemType = 12
)

type MessageState

type MessageState int

MessageState 表示消息生成状态。

const (
	MessageStateNew MessageState = iota
	MessageStateGenerating
	MessageStateFinished
)

type MessageType

type MessageType int

MessageType 表示消息发送方类型。

const (
	MessageTypeNone MessageType = iota
	MessageTypeUser
	MessageTypeBot
)

type Option

type Option func(*Client)

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL 配置登录确认后返回的账号 API 地址,默认只接受 HTTPS。

func WithBotAgent

func WithBotAgent(agent string) Option

WithBotAgent 配置 base_info 中仅用于观测归因的客户端标识。

func WithChannelVersion

func WithChannelVersion(version string) Option

WithChannelVersion 覆盖 base_info 和客户端请求头使用的版本号。

func WithClient

func WithClient(cli *restx.Client) Option

WithClient 注入自定义 restx 客户端,主要用于调整传输配置或本地测试。

func WithInsecureHTTP

func WithInsecureHTTP() Option

WithInsecureHTTP 显式允许使用明文 HTTP API 地址,仅应用于可信的开发或测试环境。

func WithLongPollTimeout

func WithLongPollTimeout(timeout time.Duration) Option

WithLongPollTimeout 配置二维码状态和消息查询的单次长轮询超时。

func WithRouteTag

func WithRouteTag(routeTag string) Option

WithRouteTag 配置可选的微信路由标签。

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout 配置普通 API 请求超时。

func WithToken

func WithToken(token string) Option

WithToken 配置二维码登录后取得的 Bot Token。

type QRCodeStatus

type QRCodeStatus string

QRCodeStatus 表示二维码登录状态。

const (
	QRCodeStatusWait              QRCodeStatus = "wait"
	QRCodeStatusScanned           QRCodeStatus = "scaned"
	QRCodeStatusConfirmed         QRCodeStatus = "confirmed"
	QRCodeStatusExpired           QRCodeStatus = "expired"
	QRCodeStatusNeedVerifyCode    QRCodeStatus = "need_verifycode"
	QRCodeStatusVerifyCodeBlocked QRCodeStatus = "verify_code_blocked"
	QRCodeStatusScannedRedirect   QRCodeStatus = "scaned_but_redirect"
	QRCodeStatusBoundRedirect     QRCodeStatus = "binded_redirect"
)

type SendTextRequest

type SendTextRequest struct {
	ToUserID     string
	Text         string
	ContextToken string
	RunID        string
}

SendTextRequest 配置一条主动发送或回复的文本消息。

type SendTextResponse

type SendTextResponse struct {
	ClientID     string
	MessageID    MessageID
	Ret          *int
	ErrorMessage string
}

SendTextResponse 返回本地 Client ID 和服务端消息 ID。

type TextItem

type TextItem struct {
	Text string `json:"text,omitempty"`
}

TextItem 表示文本消息内容。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL