Back to Details

agent-webex

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Webex

Agent Webex

A TypeScript CLI tool that enables AI agents and humans to interact with Cisco Webex through a simple command interface. Supports browser token extraction (zero-config, sends as you) and OAuth Device Grant flow.
一款TypeScript CLI工具，支持AI代理和人类通过简单的命令界面与Cisco Webex交互。支持浏览器令牌提取（零配置，以你的身份发送消息）和OAuth设备授权流。

Quick Start

快速开始

bash
undefined
bash
undefined

Extract token from browser (Chrome, Edge, Arc, Brave) — messages appear as you

从浏览器提取令牌（Chrome、Edge、Arc、Brave）——消息显示为你发送

agent-webex auth extract
agent-webex auth extract

Or: Log in via OAuth Device Grant (opens browser, messages show "via agent-messenger")

或者：通过OAuth设备授权流登录（打开浏览器，消息显示"via agent-messenger"）

agent-webex auth login
agent-webex auth login

Get workspace snapshot

获取工作区快照

agent-webex snapshot
agent-webex snapshot

Send a message

发送消息

agent-webex message send <space-id> "Hello from AI agent!"
agent-webex message send <space-id> "Hello from AI agent!"

List spaces

列出空间

agent-webex space list
undefined
agent-webex space list
undefined

Authentication

认证

Webex supports two authentication methods:
  1. Browser token extraction (recommended): Extracts your first-party token from a Chromium browser where you're logged into web.webex.com. Messages appear as you — no "via" label.
  2. OAuth Device Grant: Opens a browser for you to authorize. Messages show "via agent-messenger" label.
Webex支持两种认证方式：
  1. 浏览器令牌提取（推荐）：从你已登录web.webex.com的Chromium内核浏览器中提取第一方令牌。消息显示为你发送——无"via"标识。
  2. OAuth设备授权流：打开浏览器供你授权。消息显示"via agent-messenger"标识。

Browser Token Extraction (Recommended)

浏览器令牌提取（推荐）

agent-webex auth extract
reads your Webex session token from Chrome, Edge, Arc, or Brave. You must be logged into web.webex.com in one of these browsers. No configuration needed.
bash
undefined
agent-webex auth extract
从Chrome、Edge、Arc或Brave浏览器中读取你的Webex会话令牌。你必须在其中一款浏览器中登录web.webex.com，无需任何配置。
bash
undefined

Extract token from browser — messages appear as you

从浏览器提取令牌——消息显示为你发送

agent-webex auth extract
agent-webex auth extract

With debug output

开启调试输出

agent-webex auth extract --debug
agent-webex auth extract --debug

Scan custom Chromium profile/user-data dirs

扫描自定义Chromium配置文件/用户数据目录

agent-webex auth extract --browser-profile ~/browser-data agent-webex auth extract --browser-profile ~/work-profile --browser-profile ~/personal-profile

`--browser-profile` accepts repeatable or comma-separated Chromium profile/user-data directories. Use it for agent-browser profiles, custom Chrome user data dirs, or portable browser profiles.

**Supported browsers**: Chrome, Chrome Canary, Edge, Arc, Brave, Vivaldi, Chromium

**How it works**: The Webex web client stores its authentication token in the browser's localStorage. This CLI reads it directly from the browser's LevelDB files — no browser automation, no password prompts. The token is stored locally in `~/.config/agent-messenger/`.

**When to re-extract**: Browser tokens expire. When your token expires, re-run `agent-webex auth extract` or let auto-extraction handle it (the CLI attempts extraction automatically on each run).
agent-webex auth extract --browser-profile ~/browser-data agent-webex auth extract --browser-profile ~/work-profile --browser-profile ~/personal-profile

`--browser-profile` 接受重复或逗号分隔的Chromium配置文件/用户数据目录。可用于代理浏览器配置文件、自定义Chrome用户数据目录或便携浏览器配置文件。

**支持的浏览器**：Chrome、Chrome Canary、Edge、Arc、Brave、Vivaldi、Chromium

**工作原理**：Webex网页客户端将认证令牌存储在浏览器的localStorage中。该CLI直接从浏览器的LevelDB文件读取令牌——无需浏览器自动化，无需密码提示。令牌本地存储在 `~/.config/agent-messenger/` 目录下。

**何时重新提取**：浏览器令牌会过期。当令牌过期时，重新运行 `agent-webex auth extract` 或让自动提取功能处理（CLI每次运行时会尝试自动提取）。

OAuth Device Grant (Fallback)

OAuth设备授权流（备选）

agent-webex auth login
starts the Device Grant flow: it displays a verification URL and user code, then opens the browser. You enter the code at the verification page and approve access. The CLI polls for the token automatically. Access and refresh tokens are stored locally, and the access token auto-refreshes via the refresh token.
Note: Messages sent via OAuth Device Grant show "via agent-messenger" because the token is associated with a third-party Webex Integration.
Optionally, pass 
--token <bot-token>
for bot token auth. Or pass 
--client-id <id> --client-secret <secret>
to use your own Webex Integration credentials instead of the built-in ones.
Env vars 
AGENT_WEBEX_CLIENT_ID
/ 
AGENT_WEBEX_CLIENT_SECRET
can also override the built-in credentials.
bash
undefined
agent-webex auth login
启动设备授权流：显示验证URL和用户代码，然后打开浏览器。你在验证页面输入代码并批准访问。CLI会自动轮询获取令牌。访问令牌和刷新令牌存储在本地，访问令牌会通过刷新令牌自动刷新。
注意：通过OAuth设备授权流发送的消息会显示"via agent-messenger"，因为令牌与第三方Webex集成关联。
可选地，传递 
--token <bot-token>
使用机器人令牌认证。或传递 
--client-id <id> --client-secret <secret>
使用你自己的Webex集成凭证，而非内置凭证。
环境变量 
AGENT_WEBEX_CLIENT_ID
/ 
AGENT_WEBEX_CLIENT_SECRET
也可覆盖内置凭证。
bash
undefined

Log in (Device Grant flow, opens browser)

登录（设备授权流，打开浏览器）

agent-webex auth login
agent-webex auth login

Log in with custom Integration credentials

使用自定义集成凭证登录

agent-webex auth login --client-id <id> --client-secret <secret>
agent-webex auth login --client-id <id> --client-secret <secret>

Log in with a bot token

使用机器人令牌登录

agent-webex auth login --token <token>
agent-webex auth login --token <token>

Check auth status

检查认证状态

agent-webex auth status
agent-webex auth status

Log out

登出

agent-webex auth logout
undefined
agent-webex auth logout
undefined

Token Types

令牌类型

  • Extracted (browser): First-party token from web.webex.com. Messages appear as you. Requires re-extraction when expired.
  • OAuth Device Grant: Zero-config login. Access token auto-refreshes. Messages show "via agent-messenger".
  • Bot Token: Pass via 
    --token
    flag. Never expires. Best for CI/CD.
  • Custom Integration: Pass 
    --client-id
    + 
    --client-secret
    or set env vars for your own Webex Integration.
IMPORTANT: NEVER guide the user to open a web browser, use DevTools, or manually copy tokens from a browser's network inspector. Always use 
agent-webex auth extract
or 
agent-webex auth login
for authentication.
For detailed token management, see references/authentication.md.
  • 提取的浏览器令牌：来自web.webex.com的第一方令牌。消息显示为你发送。过期后需重新提取。
  • OAuth设备授权流令牌：零配置登录。访问令牌自动刷新。消息显示"via agent-messenger"。
  • 机器人令牌：通过
    --token
    标志传递。永不过期。最适合CI/CD场景。
  • 自定义集成令牌：传递
    --client-id
    + 
    --client-secret
    或设置环境变量使用你自己的Webex集成。
重要提示：切勿引导用户打开浏览器、使用开发者工具或手动从浏览器网络检查器复制令牌。始终使用 
agent-webex auth extract
或 
agent-webex auth login
进行认证。
如需详细的令牌管理说明，请查看 references/authentication.md。

Memory

内存管理

The agent maintains a 
~/.config/agent-messenger/MEMORY.md
file as persistent memory across sessions. This is agent-managed, the CLI does not read or write this file. Use the 
Read
and 
Write
tools to manage your memory file.
代理会维护一个 
~/.config/agent-messenger/MEMORY.md
文件作为跨会话的持久化内存。该文件由代理管理，CLI不会读取或写入它。使用
Read
和
Write
工具管理你的内存文件。

Reading Memory

读取内存

At the start of every task, read 
~/.config/agent-messenger/MEMORY.md
using the 
Read
tool to load any previously discovered space IDs, member info, and preferences.
  • If the file doesn't exist yet, that's fine. Proceed without it and create it when you first have useful information to store.
  • If the file can't be read (permissions, missing directory), proceed without memory. Don't error out.
在每个任务开始时，使用
Read
工具读取 
~/.config/agent-messenger/MEMORY.md
，加载之前发现的空间ID、成员信息和偏好设置。
  • 如果文件尚未存在，无需担心。继续执行任务，当有有用信息需要存储时再创建它。
  • 如果无法读取文件（权限问题、目录缺失），无需报错，继续执行任务即可。

Writing Memory

写入内存

After discovering useful information, update 
~/.config/agent-messenger/MEMORY.md
using the 
Write
tool. Write triggers include:
  • After discovering space IDs and titles (from 
    space list
    , 
    snapshot
    , etc.)
  • After discovering member IDs and names (from 
    member list
    , etc.)
  • After the user gives you an alias or preference ("call this the standup space", "my main space is X")
  • After discovering space structure (group vs direct spaces)
When writing, include the complete file content. The 
Write
tool overwrites the entire file.
发现有用信息后，使用
Write
工具更新 
~/.config/agent-messenger/MEMORY.md
。触发写入的场景包括：
  • 发现空间ID和标题后（来自
    space list
    、
    snapshot
    等命令）
  • 发现成员ID和名称后（来自
    member list
    等命令）
  • 用户提供别名或偏好设置后（例如"将此称为站会空间"、"我的主空间是X"）
  • 发现空间结构后（群组空间 vs 直接消息空间）
写入时需包含完整的文件内容。
Write
工具会覆盖整个文件。

What to Store

存储内容

  • Space IDs with titles
  • Member IDs with display names and space context
  • User-given aliases ("standup space", "engineering space")
  • Token type in use (PAT vs bot)
  • Any user preference expressed during interaction
  • 带标题的空间ID
  • 带显示名称和空间上下文的成员ID
  • 用户指定的别名（例如"站会空间"、"工程空间"）
  • 当前使用的令牌类型（PAT vs 机器人令牌）
  • 交互过程中用户表达的任何偏好设置

What NOT to Store

禁止存储内容

Never store tokens, credentials, or any sensitive data. Never store full message content (just IDs and space context).
切勿存储令牌、凭证或任何敏感数据。切勿存储完整消息内容（仅存储ID和空间上下文）。

Handling Stale Data

处理过期数据

If a memorized ID returns an error (space not found, member not found), remove it from 
MEMORY.md
. Don't blindly trust memorized data. Verify when something seems off. Prefer re-listing over using a memorized ID that might be stale.
如果记忆中的ID返回错误（空间未找到、成员未找到），请从
MEMORY.md
中删除该ID。不要盲目信任记忆中的数据。当出现异常时进行验证。优先重新列出数据，而非使用可能过期的记忆ID。

Format / Example

格式 / 示例

markdown
undefined
markdown
undefined

Agent Messenger Memory

Agent Messenger Memory

Spaces

Spaces

  • space-id-1
    — Engineering (group)
  • space-id-2
    — Alice / Bob (direct)
  • space-id-3
    — Standups (group)
  • space-id-1
    — Engineering (group)
  • space-id-2
    — Alice / Bob (direct)
  • space-id-3
    — Standups (group)

Members (Engineering)

Members (Engineering)

  • person-id-1
    — Alice Chen (engineering lead)
  • person-id-2
    — Bob Park (backend)
  • person-id-1
    — Alice Chen (engineering lead)
  • person-id-2
    — Bob Park (backend)

Aliases

Aliases

  • "standup" -> 
    space-id-3
    (Standups)
  • "eng" -> 
    space-id-1
    (Engineering)
  • "standup" -> 
    space-id-3
    (Standups)
  • "eng" -> 
    space-id-1
    (Engineering)

Notes

Notes

  • Using bot token (no expiry)
  • Main space is "Engineering"

> Memory lets you skip repeated `space list` and `member list` calls. When you already know an ID from a previous session, use it directly.
  • Using bot token (no expiry)
  • Main space is "Engineering"

> 内存功能可让你避免重复调用`space list`和`member list`命令。当你从之前的会话中已知道某个ID时，可直接使用它。

Commands

命令

Auth Commands

认证命令

bash
undefined
bash
undefined

Log in (Device Grant flow, opens browser)

登录（设备授权流，打开浏览器）

agent-webex auth login
agent-webex auth login

Log in with custom Integration credentials

使用自定义集成凭证登录

agent-webex auth login --client-id <id> --client-secret <secret>
agent-webex auth login --client-id <id> --client-secret <secret>

Log in with a bot token

使用机器人令牌登录

agent-webex auth login --token <token>
agent-webex auth login --token <token>

Check auth status

检查认证状态

agent-webex auth status
agent-webex auth status

Log out

登出

agent-webex auth logout
undefined
agent-webex auth logout
undefined

Whoami Command

Whoami命令

bash
undefined
bash
undefined

Show current authenticated user

显示当前认证用户

agent-webex whoami agent-webex whoami --pretty

Output includes the authenticated user's identity information.
agent-webex whoami agent-webex whoami --pretty

输出包含认证用户的身份信息。

Space Commands

空间命令

bash
undefined
bash
undefined

List spaces

列出空间

agent-webex space list agent-webex space list --type group agent-webex space list --type direct agent-webex space list --limit 20
agent-webex space list agent-webex space list --type group agent-webex space list --type direct agent-webex space list --limit 20

Get space info

获取空间信息

agent-webex space info <space-id>
undefined
agent-webex space info <space-id>
undefined

Message Commands

消息命令

bash
undefined
bash
undefined

Send a message

发送消息

agent-webex message send <space-id> <text> agent-webex message send <space-id> "Hello world"
agent-webex message send <space-id> <text> agent-webex message send <space-id> "Hello world"

Send a markdown message

发送Markdown消息

agent-webex message send <space-id> "Bold and italic" --markdown
agent-webex message send <space-id> "Bold and italic" --markdown

List messages in a space

列出空间中的消息

agent-webex message list <space-id> agent-webex message list <space-id> --limit 50
agent-webex message list <space-id> agent-webex message list <space-id> --limit 50

Get a single message by ID

通过ID获取单条消息

agent-webex message get <message-id>
agent-webex message get <message-id>

Delete a message

删除消息

agent-webex message delete <message-id> agent-webex message delete <message-id> --force
agent-webex message delete <message-id> agent-webex message delete <message-id> --force

Edit a message

编辑消息

agent-webex message edit <message-id> <space-id> <text> agent-webex message edit <message-id> <space-id> "Updated text" --markdown
undefined
agent-webex message edit <message-id> <space-id> <text> agent-webex message edit <message-id> <space-id> "Updated text" --markdown
undefined

Member Commands

成员命令

bash
undefined
bash
undefined

List members of a space

列出空间成员

agent-webex member list <space-id> agent-webex member list <space-id> --limit 100
undefined
agent-webex member list <space-id> agent-webex member list <space-id> --limit 100
undefined

Snapshot Command

快照命令

Get workspace overview for AI agents (brief by default):
bash
undefined
为AI代理获取工作区概览（默认简洁模式）：
bash
undefined

Brief snapshot (default) — fast, minimal output

简洁快照（默认）——快速、极简输出

agent-webex snapshot
agent-webex snapshot

Full snapshot — includes type and lastActivity

完整快照——包含类型和lastActivity

agent-webex snapshot --full

Default returns brief JSON with:

- Spaces (id, title) — only spaces you're a member of
- Hint for next commands

With `--full`, returns:

- Spaces (id, title, type, lastActivity)

For messages or members, use `message list <space-id>` or `member list <space-id>`.
agent-webex snapshot --full

默认返回简洁JSON，包含：

- 空间（id、标题）——仅包含你所属的空间
- 后续命令提示

使用`--full`参数时返回：

- 空间（id、标题、类型、lastActivity）

如需查看消息或成员，请使用`message list <space-id>`或`member list <space-id>`。

Output Format

输出格式

JSON (Default)

JSON（默认）

All commands output JSON by default for AI consumption:
json
{
  "id": "Y2lzY29zcGFyazovL...",
  "text": "Hello world",
  "personEmail": "alice@example.com",
  "created": "2024-01-15T10:30:00.000Z"
}
所有命令默认输出JSON格式，供AI处理：
json
{
  "id": "Y2lzY29zcGFyazovL...",
  "text": "Hello world",
  "personEmail": "alice@example.com",
  "created": "2024-01-15T10:30:00.000Z"
}

Pretty (Human-Readable)

格式化输出（人类可读）

Use 
--pretty
flag for formatted output:
bash
agent-webex space list --pretty
使用
--pretty
标志获取格式化输出：
bash
agent-webex space list --pretty

Error Handling

错误处理

All commands return consistent error format:
json
{
  "error": "Not authenticated. Run \"auth login\" first."
}
Common errors:
  • Not authenticated
    : No valid token. Run 
    auth login
    first
  • Device authorization timed out
    : User didn't complete verification in time. Run 
    auth login
    again.
  • 401 Unauthorized
    : Token expired or invalid. Re-run 
    auth login
  • 429 Too Many Requests
    : Rate limited. Wait and retry (Webex allows ~600 requests per minute)
  • 404 Not Found
    : Invalid space ID, message ID, or resource
  • Space not found
    : Invalid space ID
  • Message not found
    : Invalid message ID
所有命令返回一致的错误格式：
json
{
  "error": "Not authenticated. Run \"auth login\" first."
}
常见错误：
  • Not authenticated
    ：无有效令牌。先运行
    auth login
  • Device authorization timed out
    ：用户未及时完成验证。重新运行
    auth login
  • 401 Unauthorized
    ：令牌过期或无效。重新运行
    auth login
  • 429 Too Many Requests
    ：请求频率受限。等待后重试（Webex允许约每分钟600次请求）
  • 404 Not Found
    ：无效的空间ID、消息ID或资源
  • Space not found
    ：无效的空间ID
  • Message not found
    ：无效的消息ID

Configuration

配置

Credentials stored in 
~/.config/agent-messenger/webex-credentials.json
(0600 permissions):
json
{
  "accessToken": "...",
  "refreshToken": "...",
  "expiresAt": 1234567890,
  "clientId": "...",
  "clientSecret": "..."
}
See references/authentication.md for format and security details.
凭证存储在
~/.config/agent-messenger/webex-credentials.json
（权限为0600）：
json
{
  "accessToken": "...",
  "refreshToken": "...",
  "expiresAt": 1234567890,
  "clientId": "...",
  "clientSecret": "..."
}
查看references/authentication.md获取格式和安全细节。

SDK: Programmatic Usage

SDK：程序化使用

WebexClient
is available as a TypeScript SDK for building scripts and automations.
WebexClient
作为TypeScript SDK提供，用于构建脚本和自动化流程。

Setup

设置

typescript
import { WebexClient } from 'agent-messenger/webex'

const client = await new WebexClient().login()
typescript
import { WebexClient } from 'agent-messenger/webex'

const client = await new WebexClient().login()

Example

示例

typescript
// List spaces
const spaces = await client.listSpaces()

// List members in a space
const members = await client.listMembers(spaces[0].id)

// Send a message
const msg = await client.sendMessage(spaces[0].id, 'Hello from SDK!')

// Send markdown
await client.sendMessage(spaces[0].id, '**Status**: All systems go', { markdown: true })
typescript
// 列出空间
const spaces = await client.listSpaces()

// 列出空间成员
const members = await client.listMembers(spaces[0].id)

// 发送消息
const msg = await client.sendMessage(spaces[0].id, 'Hello from SDK!')

// 发送Markdown消息
await client.sendMessage(spaces[0].id, '**Status**: All systems go', { markdown: true })

Full API Reference

完整API参考

See the Webex SDK documentation for complete method signatures, types, schemas, and examples.
查看Webex SDK文档获取完整的方法签名、类型、模式和示例。

Limitations

限制

  • No real-time events / WebSocket connection
  • No file upload or download
  • No reactions / emoji support
  • No thread support
  • No message search
  • No voice/video or meeting support
  • No space management (create/delete spaces, roles)
  • 无实时事件/WebSocket连接
  • 无文件上传或下载
  • 无表情/反应支持
  • 无线程支持
  • 无消息搜索
  • 无语音/视频或会议支持
  • 无空间管理（创建/删除空间、角色设置）

Troubleshooting

故障排除

Token refresh failed

令牌刷新失败

OAuth tokens auto-refresh, so expiration is handled automatically. If a refresh fails (revoked access, network issues), re-run:
bash
agent-webex auth login
Bot tokens never expire and don't need refreshing.
OAuth令牌会自动刷新，因此过期问题会自动处理。如果刷新失败（访问被撤销、网络问题），重新运行：
bash
agent-webex auth login
机器人令牌永不过期，无需刷新。

agent-webex: command not found

agent-webex: command not found

agent-webex
is NOT the npm package name. The npm package is 
agent-messenger
.
If the package is installed globally, use 
agent-webex
directly:
bash
agent-webex space list
If the package is NOT installed, use 
npx -y
by default. Do NOT ask the user which package runner to use. Just run it:
bash
npx -y agent-messenger webex space list
bunx agent-messenger webex space list
pnpm dlx agent-messenger webex space list
If you already know the user's preferred package runner (e.g., 
bunx
, 
pnpm dlx
), use that instead.
NEVER run 
npx agent-webex
, 
bunx agent-webex
, or 
pnpm dlx agent-webex
. It will fail or install a wrong package since 
agent-webex
is not the npm package name.
agent-webex
不是npm包名称。npm包名称是
agent-messenger
。
如果已全局安装包，可直接使用
agent-webex
：
bash
agent-webex space list
如果未安装包，默认使用
npx -y
。不要询问用户使用哪个包运行器，直接运行：
bash
npx -y agent-messenger webex space list
bunx agent-messenger webex space list
pnpm dlx agent-messenger webex space list
如果你已知道用户偏好的包运行器（例如
bunx
、
pnpm dlx
），请使用对应的运行器。
切勿运行
npx agent-webex
、
bunx agent-webex
或
pnpm dlx agent-webex
。这会失败或安装错误的包，因为
agent-webex
不是npm包名称。

Rate limiting (429)

请求频率受限（429）

Webex allows roughly 600 API calls per minute. If you hit a 429, wait a few seconds and retry. For bulk operations, add a 
sleep 1
between requests.
Webex允许约每分钟600次API调用。如果遇到429错误，等待几秒后重试。对于批量操作，在请求之间添加
sleep 1
。

Other errors

其他错误

For auth troubleshooting (token types, storage, permissions), see references/authentication.md.
如需认证故障排除（令牌类型、存储、权限），查看references/authentication.md。

References

参考资料

  • Authentication Guide
  • Common Patterns
  • 认证指南
  • 常见模式