# Gewe Agent Tools

> Use when an agent needs to inspect or operate GeWe or WeChat contacts, groups, Moments, or the logged-in personal account through the bundled GeWe tools. Triggers include looking up a current DM contact, checking a current group, managing group members, reading or posting Moments, or inspecting the current account profile and QR code.

- Skill: `wangnov/gewe-agent-tools` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wangnov/gewe-agent-tools`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wangnov/gewe-agent-tools/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: wangnov (https://skillmd.com/u/wangnov)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wangnov/gewe-agent-tools

---


# GeWe Agent Tools

优先把这五个工具当成 GeWe 的正式操作面：

- `gewe_contacts`
- `gewe_groups`
- `gewe_moments`
- `gewe_personal`
- `gewe_issue_group_claim_code`

## 什么时候用哪个

- 处理联系人、好友、企业微信联系人、手机号通讯录：用 `gewe_contacts`
- 处理群资料、群成员、群公告、群管理：用 `gewe_groups`
- 处理朋友圈浏览、点赞、评论、发布、转发：用 `gewe_moments`
- 处理当前登录微信自己的资料、二维码、安全信息、隐私设置：用 `gewe_personal`
- 处理新群接入、给当前已配对私聊签发群认领码：用 `gewe_issue_group_claim_code`

如果只是想知道“现在这个私聊对象是谁”，优先用 `gewe_contacts`。
如果只是想知道“现在这个群是谁、有哪些成员”，优先用 `gewe_groups`。

## 新群接入

当用户在 GeWe 当前私聊会话里表达这些意思时，优先进入“群认领”流程，而不是旧的手工绑群流程：

- “我要新绑定一个群”
- “给这个新群开权限”
- “把机器人接入一个新群”

这时优先调用 `gewe_issue_group_claim_code`。

关键原则：

- 不要先让用户手填群 id
- 不要先让用户自己改配置
- 不要把“私聊已经 pairing 成功”理解成“群已经自动放行”

标准动作：

1. 在当前私聊会话里调用 `gewe_issue_group_claim_code`
2. 把返回的 8 位认领码原样发给用户
3. 明确告诉用户：先把机器人拉进目标新群
4. 再让用户在目标群里只发送这 8 位认领码，例如：`XXXXXXXX`

重要话术约束：

- 默认只把 8 位码发给用户，不要包装成 `认领码: XXXXXXXX`
- 默认明确提醒：群里也只发这 8 位码，不要加 `认领码:` 前缀

推荐话术要点：

- 这是短时有效、单次使用的认领码
- 认领成功后，只会授权当前发码者在这个新群里触发机器人
- 如果只是想查新群资料，再在当前群会话里用 `gewe_groups`

只有在用户已经明确处在目标群里，且需求是“查当前群信息 / 查成员 / 查群 id”时，才优先使用 `gewe_groups`。
如果需求是“接入一个还没放行的新群”，先发认领码，再谈群信息。

## 当前会话推断

有些 action 可以少填参数，优先利用当前会话：

- 在当前私聊会话里，`gewe_contacts` 的 `brief`、`detail`、`check_relation`，以及部分单人 action，可以从当前私聊会话推断 `wxid`
- 在当前群会话里，`gewe_groups` 的 `info`、`announcement`、`members`、`member_detail`、`qr_code`，以及多数群管理 action，可以从当前群会话推断 `groupId`
- 如果当前上下文不是对应会话，或者要操作的不是当前对象，就显式传 `wxid`、`wxids`、`groupId`

实用原则：

- 当前私聊里查对方资料：先试 `gewe_contacts` + `action: "brief"`，通常不用再填 `wxids`
- 当前群里查群信息：先试 `gewe_groups` + `action: "info"`，通常不用再填 `groupId`

## 推荐顺序

先读后写，先确认对象再执行变更。

推荐顺序：

1. 先用只读 action 确认目标对象
2. 再决定是否执行写操作
3. 写操作完成后，再用只读 action 复查结果

常见只读 action：

- `gewe_contacts`: `list` `list_cache` `brief` `detail` `search` `search_im` `im_detail` `check_relation` `phones_get`
- `gewe_groups`: `info` `announcement` `members` `member_detail` `qr_code`
- `gewe_moments`: `list_self` `list_contact` `detail` `download_video`
- `gewe_personal`: `profile` `qrcode` `safety_info`

## 写操作要谨慎

下面这些 action 会改真实微信状态。除非用户明确要求，否则不要主动调用：

- `gewe_contacts`: `set_remark` `set_only_chat` `delete` `add` `add_im` `phones_upload`
- `gewe_groups`: `set_self_nickname` `rename` `set_remark` `create` `remove_members` `agree_join` `join_via_qr` `add_member_as_friend` `approve_join_request` `admin_operate` `save_to_contacts` `pin` `disband` `set_silence` `set_announcement` `quit` `invite`
- `gewe_moments`: `upload_image` `upload_video` `delete` `post_text` `post_image` `post_video` `post_link` `set_stranger_visibility` `set_visible_scope` `set_privacy` `like` `comment` `forward`
- `gewe_personal`: `update_profile` `update_avatar` `privacy`

看到“加好友、删好友、拉群、退群、改备注、发朋友圈、改隐私、改资料”这类动作时，要默认它们会改真实账号状态。

## 常用调用套路

查看当前私聊对象：

- `gewe_contacts` with `action: "brief"`

查看当前群：

- `gewe_groups` with `action: "info"`

查看当前群成员：

- `gewe_groups` with `action: "members"`

查看某个联系人朋友圈：

- `gewe_moments` with `action: "list_contact"` and explicit `wxid`

查看自己账号资料：

- `gewe_personal` with `action: "profile"`

查看自己二维码：

- `gewe_personal` with `action: "qrcode"`

## 参数习惯

- 多联系人优先传 `wxids`
- 单联系人优先传 `wxid`
- 群优先传 `groupId`
- 要切账号时传 `accountId`
- 工具返回里会带 `input`，可以用来确认本次实际命中的目标

## 失败时怎么想

- 报“requires wxid/wxids/groupId”时，通常是因为当前会话不足以推断目标，需要显式补参数
- 报账号未配置时，优先检查 `accountId` 是否正确，以及该账号是否配置了 `token` 和 `appId`
- 如果只是想查名字，不要直接上写操作，先用 `brief`、`detail`、`info`、`members` 这类只读 action