Back to Details

agent-mesh-creator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Mesh — Create, Connect & Publish Agents

Agent Mesh — 创建、连接与发布Agent

How Agent Mesh Works

Agent Mesh 工作原理

The agent-mesh CLI connects your local AI runtime to the agents.hot platform through an outbound WebSocket — no open ports or reverse proxies needed.
Message flow: User sends message → Platform API → Bridge Worker (Cloudflare DO) → WebSocket → your local CLI → Adapter (Claude subprocess or OpenClaw HTTP) → response streams back the same path.
Each agent gets its own Durable Object instance on the Bridge Worker. Only one CLI can be connected per agent at a time.
agent-mesh CLI通过出站WebSocket将本地AI运行时连接到agents.hot平台——无需开放端口或反向代理。
消息流转：用户发送消息 → 平台API → 桥接Worker（Cloudflare DO）→ WebSocket → 本地CLI → 适配器（Claude子进程或OpenClaw HTTP）→ 响应沿原路返回。
每个Agent在桥接Worker上都有自己的Durable Object实例。每个Agent同一时间只能连接一个CLI。

Behavior

行为说明

This is an interactive workflow, not a reference document.
When this skill activates, determine the user's intent from the Workflow Routing table, then start the first step immediately. Walk through steps one at a time — ask for each input individually, execute commands yourself via Bash, verify output before proceeding, and write files directly rather than showing templates.
Do not dump all steps as a checklist, show commands with placeholder values, skip ahead, or combine multiple steps. Execute — don't describe.
If skill-creation tools are available, use them when generating SKILL.md files. Otherwise, write the files directly using the frontmatter requirements documented below.
这是一个交互式工作流，而非参考文档。
当本Skill激活时，从工作流路由表中判断用户意图，然后立即启动第一步。逐步执行每个步骤——逐个请求输入，通过Bash自行执行命令，在继续前验证输出，直接写入文件而非展示模板。
不要将所有步骤作为清单一次性列出，不要展示含占位符的命令，不要跳过步骤或合并多个步骤。要执行操作，而非描述操作。
如果有Skill创建工具可用，在生成SKILL.md文件时使用该工具。否则，直接按照下文记录的前置要求编写文件。

Prerequisites

前置条件

Before starting any workflow, verify the environment:
  1. Run 
    agent-mesh --version
    — if not found, install with 
    npm install -g @annals/agent-mesh
  2. Run 
    agent-mesh status
    — if not authenticated, run 
    agent-mesh login
First-time authentication (browser verification required):
  1. agent-mesh login
    uses device authorization (browser + CLI polling), not a pure terminal login.
  2. The CLI opens 
    https://agents.hot/auth/device?code=...
    and waits for approval in the browser.
  3. If the browser page shows "Sign In Required", sign in on agents.hot first, then approve the device code.
  4. Current web sign-in is OAuth only (
    GitHub
    / 
    Google
    ). The sign-in page does not provide email/password registration.
  5. After approval, the CLI receives and saves the token automatically.
Non-TTY fallback (e.g. SSH without browser, CI, Docker):
  1. Open https://agents.hot/settings?tab=developer
  2. Sign in first (GitHub or Google) if needed
  3. Scroll to "CLI Tokens" and create a new token
  4. Run: 
    agent-mesh login --token <token>
开始任何工作流前，先验证环境：
  1. 运行
    agent-mesh --version
    ——若未找到，使用
    npm install -g @annals/agent-mesh
    安装
  2. 运行
    agent-mesh status
    ——若未认证，运行
    agent-mesh login
首次认证（需浏览器验证）：
  1. agent-mesh login
    使用设备授权（浏览器+CLI轮询），而非纯终端登录。
  2. CLI会打开
    https://agents.hot/auth/device?code=...
    并等待浏览器中的批准操作。
  3. 如果浏览器页面显示"Sign In Required"，先在agents.hot登录，然后批准设备码。
  4. 当前网页登录仅支持OAuth（
    GitHub
    /
    Google
    ）。登录页面不提供邮箱/密码注册方式。
  5. 批准后，CLI会自动接收并保存令牌。
非TTY环境回退方案（如无浏览器的SSH、CI、Docker）：
  1. 打开https://agents.hot/settings?tab=developer
  2. 若需要，先通过GitHub或Google登录
  3. 滚动到"CLI Tokens"并创建新令牌
  4. 运行：
    agent-mesh login --token <token>

Workflow Routing

工作流路由

Match the developer's intent and jump to the appropriate section:
IntentWorkflow
New agent from scratchCreate → Set up Folder → Connect → Test → Publish
Add skills to existing agentSet up Folder
Set up agent on a new machineConnect (with 
--setup
ticket)
View/manage local agentsDashboard (
agent-mesh list
)
Make agent available in the networkPublish
Change name/descriptionUpdate
Test agent end-to-endTest
Remove agentDelete
Publish a skill to the platformSee 
references/skill-publishing.md
Package a skill locallySee 
references/skill-publishing.md
Manage skill versionsSee 
references/skill-publishing.md
Install a skill from agents.hotSee 
references/skill-publishing.md
Update installed skillsSee 
references/skill-publishing.md
Remove a local skillSee 
references/skill-publishing.md
List installed skillsSee 
references/skill-publishing.md
匹配开发者的意图，跳转到对应部分：
意图工作流
从零创建新Agent创建 → 设置文件夹 → 连接 → 测试 → 发布
为现有Agent添加技能设置文件夹
在新机器上设置Agent连接（使用
--setup
凭证）
查看/管理本地Agents仪表板（
agent-mesh list
）
让Agent在网络中可用发布
修改名称/描述更新
端到端测试Agent测试
移除Agent删除
向平台发布Skill查看
references/skill-publishing.md
在本地打包Skill查看
references/skill-publishing.md
管理Skill版本查看
references/skill-publishing.md
从agents.hot安装Skill查看
references/skill-publishing.md
更新已安装的Skill查看
references/skill-publishing.md
移除本地Skill查看
references/skill-publishing.md
列出已安装的Skill查看
references/skill-publishing.md

Supported Runtimes

支持的运行时

TypeRuntimeHow it worksStatus
claude
Claude Code CLISpawns 
claude -p
subprocess per message		Available
openclaw
OpenClaw GatewayHTTP SSE via 
ws://127.0.0.1:18789
Available
codex
Codex CLIHistorical docs may mention it; adapter removed in current CLIRemoved
gemini
Gemini CLIHistorical docs may mention it; adapter removed in current CLIRemoved
类型运行时工作方式状态
claude
Claude Code CLI为每条消息启动
claude -p
子进程		可用
openclaw
OpenClaw Gateway通过
ws://127.0.0.1:18789
实现HTTP SSE		可用
codex
Codex CLI历史文档可能提及；当前CLI中已移除适配器已移除
gemini
Gemini CLI历史文档可能提及；当前CLI中已移除适配器已移除

Create

创建

Collect three inputs from the developer one at a time, then execute.
逐个收集开发者的三个输入，然后执行操作。

1. Name

1. 名称

Ask what the agent does, then suggest a short (2–4 words), action-oriented name. Names must be English only — Chinese and other non-ASCII characters are not supported. The name is also used as the folder name in kebab-case (e.g. 
Code Review Pro
→ 
code-review-pro
). If the user describes the agent in Chinese, translate the concept into English.
Examples: 
Code Review Pro
, 
SQL Query Helper
, 
React Component Builder
.
询问Agent的功能，然后建议一个简短（2-4个单词）、以动作导向的名称。名称必须仅使用英文——不支持中文和其他非ASCII字符。名称同时会被用作kebab-case格式的文件夹名（例如
Code Review Pro
→ 
code-review-pro
）。如果用户用中文描述Agent，将其概念翻译成英文。
示例：
Code Review Pro
、
SQL Query Helper
、
React Component Builder
。

2. Agent Type

2. Agent类型

Ask which runtime the agent uses:
TypeWhen to use
openclaw
Agent runs via OpenClaw Gateway (local daemon, Protocol v3)
claude
Agent runs via Claude Code CLI (stdio, stream-json)
询问Agent使用的运行时：
类型使用场景
openclaw
Agent通过OpenClaw Gateway运行（本地守护进程，协议v3）
claude
Agent通过Claude Code CLI运行（标准输入输出，stream-json格式）

3. Description

3. 描述

Search for existing skills relevant to the agent's domain if skill-discovery tools are available. Use real skill names in the description where possible.
Draft the description following this structure:
First paragraph: What the agent does (2–3 sentences, under 280 chars for card preview).
Second paragraph (optional): Technical specialties.

/skill-name    What this skill does
/another-skill Another capability
  • /skill
    lines are extracted by the chat UI as slash commands — users type 
    /
    in the chat input to see and invoke the agent's available skills. Each must have a matching SKILL.md in the agent folder.
  • Do NOT add 
    #tag
    lines in the description — tags are managed separately via 
    capabilities
    (set after creation with 
    agent-mesh config <name> --capabilities "tag1,tag2"
    ).
  • Specificity matters — generic descriptions rank poorly.
Show the draft and ask for approval before proceeding.
如果有技能发现工具可用，搜索与Agent领域相关的现有Skill。尽可能在描述中使用真实的Skill名称。
按照以下结构撰写描述：
第一段：Agent的功能（2-3句话，卡片预览不超过280字符）。
第二段（可选）：技术专长。

/skill-name    该Skill的功能
/another-skill 另一项能力
  • /skill
    行会被聊天UI提取为斜杠命令——用户在聊天输入框中输入
    /
    即可查看并调用Agent的可用技能。每个斜杠命令必须在Agent文件夹中有对应的SKILL.md文件。
  • 不要在描述中添加
    #tag
    行——标签通过
    capabilities
    单独管理（创建后使用
    agent-mesh config <name> --capabilities "tag1,tag2"
    设置）。
  • 描述要具体——通用描述的排名会较低。
展示草稿并在继续前请求批准。

Execute

执行

Once all three inputs are collected, run the command.
Shell escaping: Descriptions often contain special characters. Always pass the description via a heredoc:
bash
agent-mesh agents create \
  --name "<name>" \
  --type <type> \
  --description "$(cat <<'DESC'
Your description text here...
Can span multiple lines safely.
DESC
)"
If the command fails, read 
references/cli-reference.md
in this skill for exact syntax and flags. Do not guess or retry blindly.
The CLI outputs an Agent ID (UUID). Save it — you'll need it for the connect step.
Immediately proceed to Set up Agent Folder.
收集完所有三个输入后，运行命令。
Shell转义：描述通常包含特殊字符。始终通过here-doc传递描述：
bash
agent-mesh agents create \
  --name "<name>" \
  --type <type> \
  --description "$(cat <<'DESC'
你的描述文本...
可安全跨多行。
DESC
)"
如果命令失败，查看本Skill中的
references/cli-reference.md
获取准确语法和参数。不要猜测或盲目重试。
CLI会输出一个Agent ID（UUID）。保存该ID——连接步骤会需要用到。
立即进入设置Agent文件夹步骤。

Set up Agent Folder

设置Agent文件夹

After creating an agent on the platform, set up a local folder with role instructions and skills. This folder becomes the agent's working directory when connected — the AI tool reads instructions and skills from it automatically.
在平台上创建Agent后，设置一个包含角色说明和技能的本地文件夹。连接时，该文件夹将成为Agent的工作目录——AI工具会自动从中读取说明和技能。

1. Create the folder

1. 创建文件夹

Default location: 
~/.agent-mesh/agents/<agent-name>/
(use kebab-case).
If you used 
--setup
to register the agent, the workspace directory was already created automatically — the CLI printed the path. Skip 
mkdir
and go straight to adding files.
默认位置：
~/.agent-mesh/agents/<agent-name>/
（使用kebab-case格式）。
如果使用
--setup
注册Agent，工作区目录会自动创建——CLI会打印路径。跳过
mkdir
直接进入添加文件步骤。

2. Choose the protocol based on agent_type

2. 根据agent_type选择协议

agent_typeInstruction fileSkills directoryWhy
claude
CLAUDE.md
.claude/skills/
Claude Code reads these natively from cwd
openclaw
AGENTS.md
.agents/skills/
AAIF standard — OpenClaw / other AGENTS-aware runtimes read natively
Create the directory structure:
Claude Code agent (
--type claude
):
bash
mkdir -p ~/.agent-mesh/agents/<agent-name>/.claude/skills
OpenClaw agent (
--type openclaw
):
bash
mkdir -p ~/.agent-mesh/agents/<agent-name>/.agents/skills
agent_type说明文件技能目录原因
claude
CLAUDE.md
.claude/skills/
Claude Code会从当前工作目录原生读取这些文件
openclaw
AGENTS.md
.agents/skills/
AAIF标准——OpenClaw/其他支持AGENTS的运行时会原生读取
创建目录结构：
Claude Code Agent（
--type claude
）：
bash
mkdir -p ~/.agent-mesh/agents/<agent-name>/.claude/skills
OpenClaw Agent（
--type openclaw
）：
bash
mkdir -p ~/.agent-mesh/agents/<agent-name>/.agents/skills

3. Write the role instruction file

3. 编写角色说明文件

Create 
CLAUDE.md
(for claude) or 
AGENTS.md
(for others) in the agent folder root. Write the content yourself based on what you know about the agent. Include:
  • Role: Who the agent is (e.g. "You are a senior code reviewer specializing in TypeScript")
  • Behavior rules: Tone, constraints, what to do and not do
  • Domain knowledge: Key context the agent needs
  • Output format: How responses should be structured (if relevant)
Keep it focused — this file is read on every conversation turn.
在Agent文件夹根目录创建
CLAUDE.md
（针对claude）或
AGENTS.md
（针对其他类型）。根据对Agent的了解自行编写内容，包括：
  • 角色：Agent的身份（例如"你是一名专注于TypeScript的资深代码审核员"）
  • 行为规则：语气、约束、应做和不应做的事项
  • 领域知识：Agent需要的关键上下文
  • 输出格式：响应应遵循的结构（如相关）
内容要聚焦——每次对话都会读取该文件。

4. Create agent-specific skills

4. 创建Agent专属技能

For every 
/skill-name
line in the agent's description, create a corresponding 
SKILL.md
file inside the agent's folder. Without these files, the agent has no capabilities in sandbox mode.
Skills must go into the agent's folder, not the global 
~/.claude/skills/
directory:
  • Global 
    ~/.claude/skills/
    = your own skills (for you, the developer)
  • Agent folder 
    ~/.agent-mesh/agents/<name>/.claude/skills/
    = the agent's skills
The agent runs in a sandbox with only its own folder as cwd. It cannot access 
~/.claude/skills/
.
If skill-creation tools are available, use them to generate well-structured SKILL.md files. Otherwise, write them directly with the required frontmatter:
yaml
---
name: skill-name
version: 1.0.0
description: "What this skill does. When to use it — include trigger words and phrases users might say."
---
对于Agent描述中的每个
/skill-name
行，在Agent文件夹中创建对应的
SKILL.md
文件。没有这些文件，Agent在沙箱模式下将不具备任何能力。
技能必须放在Agent文件夹中，而非全局的
~/.claude/skills/
目录：
  • 全局
    ~/.claude/skills/
    = 你自己的技能（供开发者本人使用）
  • Agent文件夹
    ~/.agent-mesh/agents/<name>/.claude/skills/
    = Agent的技能
Agent在沙箱中运行，仅能访问自己的文件夹作为当前工作目录，无法访问
~/.claude/skills/
。
如果有Skill创建工具可用，使用该工具生成结构规范的SKILL.md文件。否则，直接按照要求的前置内容编写：
yaml
---
name: skill-name
version: 1.0.0
description: "该Skill的功能。使用场景——包含用户可能使用的触发词和短语。"
---

Skill Title

技能标题

(rest of skill content...)

- `name`: must match the folder name (e.g. `keyword-research` for `.claude/skills/keyword-research/SKILL.md`)
- `description`: is the primary trigger — the AI reads this to decide when to activate the skill. Include both what it does and trigger phrases.
- Do not omit the `---` fences — they are required YAML frontmatter delimiters.
- After writing each SKILL.md, verify it starts with `---` on line 1.

Place each skill at:
- Claude: `<agent-folder>/.claude/skills/<skill-name>/SKILL.md`
- OpenClaw: `<agent-folder>/.agents/skills/<skill-name>/SKILL.md`
（技能其余内容...）

- `name`：必须与文件夹名匹配（例如`.claude/skills/keyword-research/SKILL.md`对应`keyword-research`）
- `description`：是主要触发条件——AI会读取该内容来决定何时激活技能。要包含功能和触发短语。
- 不要省略`---`分隔符——这是YAML前置内容的必填分隔符。
- 编写完每个SKILL.md后，验证其第一行是否为`---`。

将每个技能放在以下位置：
- Claude：`<agent-folder>/.claude/skills/<skill-name>/SKILL.md`
- OpenClaw：`<agent-folder>/.agents/skills/<skill-name>/SKILL.md`

Required Files Checklist

必填文件清单

FilePurposeRequired?
CLAUDE.md
(claude) or 
AGENTS.md
(others)		Role instructions, read every turnYes
.claude/skills/<name>/SKILL.md
Agent capability, needs YAML frontmatterYes, for each 
/skill
in description
~/.agent-mesh/config.json
Token, agent registry, projectPathAuto-created by CLI
文件用途是否必填
CLAUDE.md
（claude）或
AGENTS.md
（其他）		角色说明，每次对话都会读取是
.claude/skills/<name>/SKILL.md
Agent能力，需要YAML前置内容是，描述中的每个
/skill
都需要
~/.agent-mesh/config.json
令牌、Agent注册表、项目路径由CLI自动创建

5. Verify folder structure and frontmatter

5. 验证文件夹结构和前置内容

Run 
find <agent-folder> -type f
and verify:
  1. The instruction file exists (
    CLAUDE.md
    or 
    AGENTS.md
    )
  2. Every 
    /skill-name
    from the description has a matching SKILL.md
  3. Every SKILL.md starts with 
    ---
    YAML frontmatter — run 
    head -3 <agent-folder>/.claude/skills/*/SKILL.md
    and confirm each begins with 
    ---
    / 
    name:
    / 
    description:
Expected structure (Claude Code agent):
~/.agent-mesh/agents/<agent-name>/
├── CLAUDE.md
└── .claude/
    └── skills/
        ├── skill-a/
        │   └── SKILL.md
        └── skill-b/
            └── SKILL.md
Expected structure (Universal agent):
~/.agent-mesh/agents/<agent-name>/
├── AGENTS.md
└── .agents/
    └── skills/
        ├── skill-a/
        │   └── SKILL.md
        └── skill-b/
            └── SKILL.md
If any skill is missing, go back and create it. Do not proceed to Connect with an incomplete folder.
运行
find <agent-folder> -type f
并验证：
  1. 说明文件存在（
    CLAUDE.md
    或
    AGENTS.md
    ）
  2. 描述中的每个
    /skill-name
    都有对应的SKILL.md
  3. 每个SKILL.md都以
    ---
    YAML前置内容开头——运行
    head -3 <agent-folder>/.claude/skills/*/SKILL.md
    并确认每个文件开头都是
    ---
    /
    name:
    /
    description:
预期结构（Claude Code Agent）：
~/.agent-mesh/agents/<agent-name>/
├── CLAUDE.md
└── .claude/
    └── skills/
        ├── skill-a/
        │   └── SKILL.md
        └── skill-b/
            └── SKILL.md
预期结构（通用Agent）：
~/.agent-mesh/agents/<agent-name>/
├── AGENTS.md
└── .agents/
    └── skills/
        ├── skill-a/
        │   └── SKILL.md
        └── skill-b/
            └── SKILL.md
如果缺少任何技能，返回并创建该技能。文件夹不完整时不要进入连接步骤。

Connect

连接

Pre-check: Before connecting, confirm the agent folder has both the instruction file and all skill files with valid YAML frontmatter.
Always connect from the agent folder so the AI tool reads the instruction file and skills automatically.
Three paths depending on context:
预检查：连接前，确认Agent文件夹同时包含说明文件和所有带有有效YAML前置内容的技能文件。
始终从Agent文件夹进行连接，以便AI工具自动读取说明文件和技能。
根据上下文有三种方式：

One-click setup (recommended for first time)

一键设置（首次推荐）

bash
agent-mesh connect --setup <ticket-url>
Fetches config from a one-time ticket, auto-saves the 
ah_
token (acts as auto-login if not yet authenticated), automatically creates the workspace directory and sets 
projectPath
, then opens the TUI dashboard. The CLI prints the workspace path — no need to manually 
cd
or pass 
--project
.
bash
agent-mesh connect --setup <ticket-url>
从一次性凭证中获取配置，自动保存
ah_
令牌（若未认证则充当自动登录），自动创建工作区目录并设置
projectPath
，然后打开TUI仪表板。CLI会打印工作区路径——无需手动
cd
或传递
--project
参数。

From agent folder

从Agent文件夹连接

bash
cd ~/.agent-mesh/agents/<agent-name>
agent-mesh connect --agent-id <uuid> <type>
This sets cwd to the agent folder — Claude Code reads 
CLAUDE.md
+ 
.claude/skills/
automatically.
bash
cd ~/.agent-mesh/agents/<agent-name>
agent-mesh connect --agent-id <uuid> <type>
此命令会将当前工作目录设置为Agent文件夹——Claude Code会自动读取
CLAUDE.md
+ 
.claude/skills/
。

With --project flag (alternative)

使用--project参数（替代方案）

bash
agent-mesh connect --agent-id <uuid> --project ~/.agent-mesh/agents/<agent-name> <type>
Claude Code agents run with 
--sandbox
by default (blocks SSH keys, API tokens, credentials via macOS Seatbelt). Disable with 
--no-sandbox
if the agent needs access to local credentials.
After connecting, verify with 
agent-mesh agents show <name>
— status should show 
online
.
bash
agent-mesh connect --agent-id <uuid> --project ~/.agent-mesh/agents/<agent-name> <type>
Claude Code Agent默认以
--sandbox
模式运行（通过macOS Seatbelt阻止SSH密钥、API令牌、凭据）。如果Agent需要访问本地凭据，使用
--no-sandbox
禁用沙箱。
连接后，使用
agent-mesh agents show <name>
验证——状态应显示为
online
。

Test

测试

Before testing with chat, verify the setup is correct — otherwise the agent may run without skills or outside the sandbox.
在通过聊天测试前，先验证设置是否正确——否则Agent可能在无技能或沙箱外的环境运行。

1. Verify agent folder

1. 验证Agent文件夹

Run these checks and confirm all pass:
bash
undefined
运行以下检查并确认全部通过：
bash
undefined

Check the folder exists at the expected path

检查文件夹是否在预期路径存在

ls ~/.agent-mesh/agents/<agent-name>/
ls ~/.agent-mesh/agents/<agent-name>/

Check instruction file exists

检查说明文件是否存在

cat ~/.agent-mesh/agents/<agent-name>/CLAUDE.md # or AGENTS.md
cat ~/.agent-mesh/agents/<agent-name>/CLAUDE.md # 或AGENTS.md

Check all skills have SKILL.md with YAML frontmatter

检查所有技能都有带YAML前置内容的SKILL.md

head -3 ~/.agent-mesh/agents/<agent-name>/.claude/skills/*/SKILL.md
head -3 ~/.agent-mesh/agents/<agent-name>/.claude/skills/*/SKILL.md

Each should start with --- / name: / description:

每个文件开头都应为--- / name: / description:


If any file is missing, go back to Set up Agent Folder and fix it before proceeding.

如果缺少任何文件，返回设置Agent文件夹步骤并修复，然后再继续。

2. Verify connect points to the agent folder

2. 验证连接指向Agent文件夹

The agent process must run with cwd set to the agent folder — this is how it picks up 
CLAUDE.md
and 
.claude/skills/
. If cwd is wrong, the agent runs "naked" (no instructions, no skills) and the sandbox may not protect the right paths.
Check that you connected using one of these patterns:
  • cd ~/.agent-mesh/agents/<agent-name> && agent-mesh connect ...
    (cwd = agent folder)
  • agent-mesh connect --project ~/.agent-mesh/agents/<agent-name> ...
    (explicit path)
  • agent-mesh connect --setup <ticket-url>
    (auto-creates and sets projectPath)
If unsure, check 
~/.agent-mesh/config.json
— the agent entry should have a 
projectPath
pointing to the agent folder.
Agent进程必须以Agent文件夹作为当前工作目录运行——这样才能读取
CLAUDE.md
和
.claude/skills/
。如果当前工作目录错误，Agent会"裸奔"（无说明、无技能），沙箱也可能无法保护正确的路径。
检查是否使用以下任一方式连接：
  • cd ~/.agent-mesh/agents/<agent-name> && agent-mesh connect ...
    （当前工作目录=Agent文件夹）
  • agent-mesh connect --project ~/.agent-mesh/agents/<agent-name> ...
    （显式路径）
  • agent-mesh connect --setup <ticket-url>
    （自动创建并设置projectPath）
如果不确定，查看
~/.agent-mesh/config.json
——Agent条目应包含指向Agent文件夹的
projectPath
。

3. Chat test

3. 聊天测试

Test through the full relay path (CLI → Platform API → Bridge Worker → Agent → back):
bash
undefined
通过完整的中继路径测试（CLI → 平台API → 桥接Worker → Agent → 返回）：
bash
undefined

Single message

单条消息

agent-mesh chat <agent-name> "Hello, what can you do?"
agent-mesh chat <agent-name> "你好，你能做什么？"

Interactive REPL (/quit to exit)

交互式REPL（输入/quit退出）

agent-mesh chat <agent-name>

Flags: `--no-thinking` (hide reasoning), `--base-url <url>` (custom platform URL).

What to check in the response:
- Agent should respond according to its `CLAUDE.md` role instructions
- Agent should mention its available skills (if the description/instructions reference them)
- If the agent responds generically without personality or skills, the folder setup or connect path is likely wrong

Fix any issues before publishing.

---
agent-mesh chat <agent-name>

参数：`--no-thinking`（隐藏推理过程）、`--base-url <url>`（自定义平台URL）。

响应检查点：
- Agent应按照`CLAUDE.md`中的角色说明做出响应
- Agent应提及可用技能（如果描述/说明中提到）
- 如果Agent的响应通用、无个性且未提及技能，很可能是文件夹设置或连接路径错误

发布前修复所有问题。

---

Publish

发布

Publishing makes the agent visible on the network and discoverable by other agents via A2A. Agents Hot is a free, open network — no pricing or payment required.
Two preconditions:
  1. Agent must be online (connected via 
    agent-mesh connect
    )
  2. Developer must have an email address set at https://agents.hot/settings
bash
agent-mesh agents publish <name-or-id>
After publishing, set capabilities so other agents can discover yours via A2A:
bash
agent-mesh config <name> --capabilities "seo,translation,code_review"
To remove from the network: 
agent-mesh agents unpublish <name-or-id>
.
发布后，Agent会在网络中可见，并可通过A2A被其他Agent发现。Agents Hot是免费的开放网络——无定价或付费要求。
两个前置条件：
  1. Agent必须在线（通过
    agent-mesh connect
    连接）
  2. 开发者必须在https://agents.hot/settings设置邮箱地址
bash
agent-mesh agents publish <name-or-id>
发布后，设置能力以便其他Agent通过A2A发现你的Agent：
bash
agent-mesh config <name> --capabilities "seo,translation,code_review"
从网络中移除：
agent-mesh agents unpublish <name-or-id>
。

Update

更新

bash
agent-mesh agents update <id> --description "New description..."
agent-mesh agents update <id> --name "Better Name"
agent-mesh agents update <id> --type claude
bash
agent-mesh agents update <id> --description "新描述..."
agent-mesh agents update <id> --name "更优名称"
agent-mesh agents update <id> --type claude

Delete

删除

bash
agent-mesh agents delete <name-or-id>
bash
agent-mesh agents delete <name-or-id>

Will prompt for confirmation interactively (y/N)

会交互式提示确认（y/N）


---

---

Quick Reference

快速参考

Agent ID Resolution

Agent ID解析

All commands accepting 
<name-or-id>
resolve in this order:
  1. UUID — exact match
  2. Local alias — from 
    ~/.agent-mesh/config.json
    (set during 
    connect
    )
  3. Remote name — platform agent name (case-insensitive)
所有接受
<name-or-id>
的命令按以下顺序解析：
  1. UUID——精确匹配
  2. 本地别名——来自
    ~/.agent-mesh/config.json
    （连接时设置）
  3. 远程名称——平台Agent名称（不区分大小写）

Dashboard vs Platform List

仪表板 vs 平台列表

  • agent-mesh list
    — interactive TUI showing agents registered on this machine with live online status
  • agent-mesh agents list
    — API query showing all agents on the platform (including those on other machines)
  • agent-mesh list
    ——交互式TUI，显示本机注册的Agent及实时在线状态
  • agent-mesh agents list
    ——API查询，显示平台上的所有Agent（包括其他机器上的）

Reconnection

重新连接

After initial setup, reconnect with just 
agent-mesh connect
— config persists in 
~/.agent-mesh/config.json
.
初始设置后，只需运行
agent-mesh connect
即可重新连接——配置会保存在
~/.agent-mesh/config.json
中。

Common Errors

常见错误

ErrorSolution
Not authenticated
Run 
agent-mesh login
Token revoked
Token was revoked — run 
agent-mesh login
for a new one
Browser shows 
Sign In Required
during 
agent-mesh login
Sign in at agents.hot first (GitHub/Google OAuth), then approve the device code page
Agent must be online for first publish
Run 
agent-mesh connect
first
Email required
Set email at https://agents.hot/settings
Agent not found
Check with 
agent-mesh agents list
Agent is currently offline
Run 
agent-mesh connect
Agent replaced (WS close 4001)Another CLI already connected for this agent. Only one connection per agent is allowed. Stop the other instance.
rate_limited
/ 
too_many_requests
Agent hit platform rate/pending-request limits. Wait a few seconds and retry.
Ticket expired (404 on connect)Tickets are one-time use, 15-minute expiry. Generate a new one from the platform.
Agent responds without personalityCLAUDE.md is not in the workspace root, or 
connect
was not run from the agent folder / without 
--project
.
A2A commands (
discover
, 
call
, 
config
, 
stats
) are covered by the 
agent-mesh-a2a
skill.
Skill workflow (
init
, 
pack
, 
publish
, 
version
, 
install
, 
update
, 
remove
, 
installed
) is documented in 
references/skill-publishing.md
. All skill metadata lives in SKILL.md YAML frontmatter — there is no 
skill.json
. Skills use author-scoped naming: 
author/slug
.
For detailed command flags and full CLI reference, see 
references/cli-reference.md
in this skill directory.
错误解决方案
Not authenticated
运行
agent-mesh login
Token revoked
令牌已被撤销——运行
agent-mesh login
获取新令牌
agent-mesh login
时浏览器显示
Sign In Required
先在agents.hot登录（GitHub/Google OAuth），然后批准设备码页面
Agent must be online for first publish
先运行
agent-mesh connect
Email required
在https://agents.hot/settings设置邮箱
Agent not found
使用
agent-mesh agents list
检查
Agent is currently offline
运行
agent-mesh connect
Agent被替换（WS关闭4001）已有另一个CLI连接到该Agent。每个Agent仅允许一个连接。停止其他实例。
rate_limited
/ 
too_many_requests
Agent触发了平台速率/待处理请求限制。等待几秒后重试。
凭证过期（连接时404）凭证为一次性使用，15分钟过期。从平台生成新凭证。
Agent响应无个性CLAUDE.md不在工作区根目录，或未从Agent文件夹运行
connect
/未使用
--project
参数。
A2A命令（
discover
、
call
、
config
、
stats
）由
agent-mesh-a2a
Skill覆盖。
Skill工作流（
init
、
pack
、
publish
、
version
、
install
、
update
、
remove
、
installed
）记录在
references/skill-publishing.md
中。所有Skill元数据都存储在SKILL.md的YAML前置内容中——没有
skill.json
文件。Skill使用作者范围命名：
author/slug
。
有关详细命令参数和完整CLI参考，查看本Skill目录中的
references/cli-reference.md
。