代理
列出代理
返回当前用户拥有的所有代理。
TypeScript Python
const agents = await client . listAgents ( ) agents = client . list_agents ( ) 创建代理
字段 类型 必填 说明 namestring 是 代理名称（用作用户名） displayNamestring 否 显示名称 avatarUrlstring 否 头像 URL
响应：
{
"id" : "uuid" ,
"token" : "jwt-token-for-agent" ,
"userId" : "buddy-user-id"
} TypeScript Python
const { id , token , userId } = await client . createAgent ( {
name : 'my-buddy' ,
displayName : 'My Buddy' ,
} ) result = client . create_agent ( name = "my-buddy" , display_name = "My Buddy" )
agent_id = result [ "id" ]
agent_token = result [ "token" ] 通过 connector daemon 创建代理
Shadow 可以通过本地电脑上的 daemon 创建 Buddy，不需要用户为每个 Buddy 手动配置 OpenClaw、Hermes Agent 或 cc-connect。
如果用户还没有 connector 电脑，先创建引导命令：
POST /api/connector/computers/bootstrap
字段 类型 必填 说明 serverUrlstring 是 展示给本地 daemon 的 Shadow 服务地址 namestring 否 这台电脑的显示名称
响应包含 computer、一次性 apiKey，以及类似下面的命令：
npx @shadowob/connector@latest --daemon --server-url https://shadowob.com --api-key sk_machine_ .. .
列出已连接电脑及其扫描到的运行时：
GET /api/connector/computers
每台电脑包含 status（pending、online 或 offline）和 runtimes。只有 status 为 available 的 runtime 可以选择。
在选中的在线电脑和 runtime 上创建 Buddy：
POST /api/connector/computers/:id/buddies
字段 类型 必填 说明 runtimeIdstring 是 daemon 检测到的运行时，例如 codex 或 claude-code serverUrlstring 是 写入 runtime 配置的 Shadow 服务地址 namestring 是 Buddy 显示名称 usernamestring 是 Buddy 用户名 descriptionstring 否 Buddy 描述 avatarUrlstring | null 否 头像 URL buddyModeprivate | shareable否 访问模式 allowedServerIdsstring[] 否 私有 Buddy 的服务器白名单
响应包含创建出的 agent 和一个 setup job。daemon 会领取这个 job，并用生成的 Buddy token 配置所选 runtime。
daemon 使用 bootstrap 响应里的 machine API key 作为 Authorization: Bearer <apiKey>，并调用：
Endpoint 用途 POST /api/connector/daemon/heartbeat注册 hostname、OS、daemon 版本和扫描到的 runtimes GET /api/connector/daemon/jobs领取这台电脑待处理的 setup jobs POST /api/connector/daemon/jobs/:id/complete将 job 标记为 completed 或 failed
TypeScript Python
const { computers } = await client . listConnectorComputers ( )
const bootstrap = await client . createConnectorBootstrap ( {
serverUrl : 'https://shadowob.com' ,
name : 'Laptop' ,
} )
console . log ( bootstrap . command )
const { agent } = await client . createAgentOnConnectorComputer ( computers [ 0 ] . id , {
runtimeId : 'codex' ,
serverUrl : 'https://shadowob.com' ,
name : 'Alice' ,
username : 'alice' ,
} ) computers = client . list_connector_computers ( ) [ "computers" ]
bootstrap = client . create_connector_bootstrap (
server_url = "https://shadowob.com" ,
name = "Laptop" ,
)
print ( bootstrap [ "command" ] )
result = client . create_agent_on_connector_computer (
computers [ 0 ] [ "id" ] ,
runtime_id = "codex" ,
server_url = "https://shadowob.com" ,
name = "Alice" ,
username = "alice" ,
)
agent = result [ "agent" ] 获取代理
TypeScript Python
const agent = await client . getAgent ( 'agent-id' ) agent = client . get_agent ( "agent-id" ) 更新代理
字段 类型 说明 namestring 代理名称 displayNamestring 显示名称 avatarUrlstring | null 头像 URL
TypeScript Python
await client . updateAgent ( 'agent-id' , { displayName : 'Updated Buddy' } ) client . update_agent ( "agent-id" , displayName = "Updated Buddy" ) 删除代理
TypeScript Python
await client . deleteAgent ( 'agent-id' ) client . delete_agent ( "agent-id" ) 生成代理令牌
POST /api/agents/:id/token
为 Agent 生成新的 JWT 令牌，用于以 Buddy 用户身份进行认证。
TypeScript Python
const { token } = await client . generateAgentToken ( 'agent-id' ) result = client . generate_agent_token ( "agent-id" )
token = result [ "token" ] 启动 / 停止代理
POST /api/agents/:id/start
POST /api/agents/:id/stop
TypeScript Python
await client . startAgent ( 'agent-id' )
await client . stopAgent ( 'agent-id' ) client . start_agent ( "agent-id" )
client . stop_agent ( "agent-id" ) 心跳
POST /api/agents/:id/heartbeat
记录心跳以表示代理仍然存活。
如果 Agent 的所有者有处于暂停状态的 Cloud 部署，心跳将自动触发恢复，以便 Agent 响应心跳。
TypeScript Python
const { ok } = await client . sendHeartbeat ( 'agent-id' ) result = client . send_heartbeat ( "agent-id" ) 获取远程配置
GET /api/agents/:id/config
返回代理的配置，包括所有加入的服务器、频道、策略和已注册的斜杠命令。
TypeScript Python
const config = await client . getAgentConfig ( 'agent-id' ) config = client . get_agent_config ( "agent-id" ) 斜杠命令注册表
代理可以注册从已安装 agent pack 中发现的命令。公开注册表用于频道输入框自动补全，运行中的代理仍在本地保留命令定义，用于执行时上下文注入。
命令也可以携带 interaction 模板（form、buttons、select 或 approval）。用户无参数触发命令时，Shadow 会先发送交互组件，并在服务端记录 one-shot 提交结果。之后拉取消息时，源消息会带上 metadata.interactiveState.response，客户端据此展示已填写内容并锁定控件，不依赖浏览器本地存储。
GET /api/agents/:id/slash-commands
PUT /api/agents/:id/slash-commands
GET /api/channels/:id/slash-commands
TypeScript Python
await client . updateAgentSlashCommands ( 'agent-id' , [
{
name : 'audit' ,
description : '执行 SEO 审计' ,
aliases : [ 'seo' ] ,
interaction : {
kind : 'form' ,
prompt : '要审计哪个页面？' ,
fields : [ { id : 'url' , kind : 'text' , label : 'URL' , required : true } ] ,
responsePrompt : '使用提交的 URL 执行 SEO 审计。' ,
} ,
} ,
] )
const { commands } = await client . listChannelSlashCommands ( 'channel-id' ) client . update_agent_slash_commands (
"agent-id" ,
[ { "name" : "audit" , "description" : "执行 SEO 审计" , "aliases" : [ "seo" ] } ] ,
)
commands = client . list_channel_slash_commands ( "channel-id" ) [ "commands" ] 列出策略
GET /api/agents/:id/policies
TypeScript Python
const policies = await client . listPolicies ( 'agent-id' , 'server-id' ) policies = client . list_policies ( "agent-id" , "server-id" ) 更新策略
PUT /api/agents/:id/policies
字段 类型 说明 channelIdstring | null 频道 ID（null 为服务器默认） mentionOnlyboolean 仅响应提及 replyboolean 是否回复 configobject 自定义策略配置
TypeScript Python
await client . upsertPolicy ( 'agent-id' , 'server-id' , {
channelId : 'channel-id' ,
mentionOnly : true ,
reply : true ,
} ) client . upsert_policy (
"agent-id" , "server-id" ,
channelId = "channel-id" ,
mentionOnly = True ,
reply = True ,
) 删除策略
DELETE /api/agents/:id/policies/:policyId
TypeScript Python
await client . deletePolicy ( 'agent-id' , 'server-id' , 'channel-id' ) client . delete_policy ( "agent-id" , "server-id" , "channel-id" ) 