Discord

Discord hỗ trợ thẻ trả lời trong đầu ra của agent:

• [[reply_to_current]]
• [[reply_to:<id>]]

Được kiểm soát bởi channels.discord.replyToMode:

• off (mặc định)
• first
• all
• batched

Lưu ý: off tắt phân luồng trả lời ngầm định. Các thẻ [[reply_to_*]] tường minh vẫn được tôn trọng. first luôn gắn tham chiếu trả lời gốc ngầm định vào tin nhắn Discord đi đầu tiên trong lượt. batched chỉ gắn tham chiếu trả lời gốc ngầm định của Discord khi lượt đầu vào là một lô đã debounce gồm nhiều tin nhắn. Điều này hữu ích khi bạn muốn trả lời gốc chủ yếu cho các cuộc trò chuyện bùng phát dễ mơ hồ, không phải mọi lượt một tin nhắn đơn lẻ.

ID tin nhắn được đưa vào ngữ cảnh/lịch sử để agent có thể nhắm tới các tin nhắn cụ thể.

OpenClaw có thể truyền trực tuyến bản nháp trả lời bằng cách gửi một tin nhắn tạm thời và chỉnh sửa nó khi văn bản tới. channels.discord.streaming nhận off | partial | block | progress (mặc định). progress giữ một bản nháp trạng thái có thể chỉnh sửa và cập nhật nó với tiến trình công cụ cho đến khi gửi bản cuối; streamMode là bí danh runtime cũ. Chạy openclaw doctor --fix để ghi lại cấu hình đã lưu sang khóa chuẩn.

Đặt channels.discord.streaming.mode thành off để tắt các chỉnh sửa xem trước Discord. Nếu truyền trực tuyến khối Discord được bật tường minh, OpenClaw bỏ qua luồng xem trước để tránh truyền trực tuyến hai lần.

{
channels: {
discord: {
  streaming: {
    mode: "progress",
    progress: {
      label: "auto",
      maxLines: 8,
      toolProgress: true,
    },
  },
},
},
}

• partial chỉnh sửa một tin nhắn xem trước duy nhất khi token tới.
• block phát các đoạn có kích thước bản nháp (dùng draftChunk để tinh chỉnh kích thước và điểm ngắt, được giới hạn theo textChunkLimit).
• Các bản cuối có media, lỗi và trả lời tường minh sẽ hủy các chỉnh sửa xem trước đang chờ.
• streaming.preview.toolProgress (mặc định true) kiểm soát liệu cập nhật công cụ/tiến trình có tái sử dụng tin nhắn xem trước hay không.
• streaming.preview.commandText / streaming.progress.commandText kiểm soát chi tiết lệnh/exec trong các dòng tiến trình gọn: raw (mặc định) hoặc status (chỉ nhãn công cụ).

Ẩn văn bản lệnh/exec thô trong khi vẫn giữ các dòng tiến trình gọn:

{
  "channels": {
    "discord": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

Truyền trực tuyến xem trước chỉ hỗ trợ văn bản; trả lời có media quay về cách gửi thông thường. Khi truyền trực tuyến block được bật tường minh, OpenClaw bỏ qua luồng xem trước để tránh truyền trực tuyến hai lần.

Ngữ cảnh lịch sử guild:

• channels.discord.historyLimit mặc định 20
• dự phòng: messages.groupChat.historyLimit
• 0 tắt

Điều khiển lịch sử DM:

• channels.discord.dmHistoryLimit
• channels.discord.dms["<user_id>"].historyLimit

Hành vi luồng:

• Các luồng Discord định tuyến như phiên kênh và kế thừa cấu hình kênh cha trừ khi bị ghi đè.
• Phiên luồng kế thừa lựa chọn /model cấp phiên của kênh cha làm dự phòng chỉ dành cho model; các lựa chọn /model cục bộ của luồng vẫn được ưu tiên và lịch sử transcript của cha không được sao chép trừ khi bật kế thừa transcript.
• channels.discord.thread.inheritParent (mặc định false) cho phép các auto-thread mới khởi tạo từ transcript cha. Ghi đè theo tài khoản nằm trong channels.discord.accounts.<id>.thread.inheritParent.
• Phản ứng của công cụ tin nhắn có thể phân giải mục tiêu DM user:<id>.
• guilds.<guild>.channels.<channel>.requireMention: false được giữ nguyên trong dự phòng kích hoạt ở giai đoạn trả lời.

Chủ đề kênh được chèn làm ngữ cảnh không đáng tin cậy. Allowlists kiểm soát ai có thể kích hoạt agent, không phải là ranh giới biên tập lại ngữ cảnh bổ sung đầy đủ.

Discord có thể gắn một luồng với mục tiêu phiên để các tin nhắn tiếp theo trong luồng đó tiếp tục định tuyến tới cùng phiên (bao gồm cả phiên subagent).

Lệnh:

• /focus <target> gắn luồng hiện tại/mới với mục tiêu subagent/phiên
• /unfocus xóa liên kết luồng hiện tại
• /agents hiển thị các lượt chạy đang hoạt động và trạng thái liên kết
• /session idle <duration|off> kiểm tra/cập nhật tự động hủy focus do không hoạt động cho các liên kết đã focus
• /session max-age <duration|off> kiểm tra/cập nhật tuổi tối đa cứng cho các liên kết đã focus

Cấu hình:

{
session: {
threadBindings: {
  enabled: true,
  idleHours: 24,
  maxAgeHours: 0,
},
},
channels: {
discord: {
  threadBindings: {
    enabled: true,
    idleHours: 24,
    maxAgeHours: 0,
    spawnSessions: true,
    defaultSpawnContext: "fork",
  },
},
},
}

Ghi chú:

• session.threadBindings.* đặt mặc định toàn cục.
• channels.discord.threadBindings.* ghi đè hành vi Discord.
• spawnSessions kiểm soát việc tự động tạo/gắn luồng cho sessions_spawn({ thread: true }) và các lượt spawn luồng ACP. Mặc định: true.
• defaultSpawnContext kiểm soát ngữ cảnh subagent gốc cho các lượt spawn gắn với luồng. Mặc định: "fork".
• Các khóa spawnSubagentSessions/spawnAcpSessions không còn dùng được di chuyển bởi openclaw doctor --fix.
• Nếu liên kết luồng bị tắt cho một tài khoản, /focus và các thao tác liên kết luồng liên quan sẽ không khả dụng.

Xem Sub-agents, ACP Agents và Configuration Reference.

Với các không gian làm việc ACP "luôn bật" ổn định, hãy cấu hình các liên kết ACP có kiểu ở cấp cao nhất nhắm tới cuộc trò chuyện Discord.

Đường dẫn cấu hình:

• bindings[] với type: "acp" và match.channel: "discord"

Ví dụ:

{
agents: {
list: [
  {
    id: "codex",
    runtime: {
      type: "acp",
      acp: {
        agent: "codex",
        backend: "acpx",
        mode: "persistent",
        cwd: "/workspace/openclaw",
      },
    },
  },
],
},
bindings: [
{
  type: "acp",
  agentId: "codex",
  match: {
    channel: "discord",
    accountId: "default",
    peer: { kind: "channel", id: "222222222222222222" },
  },
  acp: { label: "codex-main" },
},
],
channels: {
discord: {
  guilds: {
    "111111111111111111": {
      channels: {
        "222222222222222222": {
          requireMention: false,
        },
      },
    },
  },
},
},
}

Ghi chú:

• /acp spawn codex --bind here gắn kênh hoặc luồng hiện tại tại chỗ và giữ các tin nhắn tương lai trên cùng phiên ACP. Tin nhắn luồng kế thừa liên kết kênh cha.
• Trong một kênh hoặc luồng đã liên kết, /new và /reset đặt lại cùng phiên ACP tại chỗ. Các liên kết luồng tạm thời có thể ghi đè phân giải mục tiêu khi đang hoạt động.
• spawnSessions kiểm soát việc tạo/gắn luồng con qua --thread auto|here.

Xem ACP Agents để biết chi tiết hành vi liên kết.

Chế độ thông báo phản ứng theo từng guild:

• off
• own (mặc định)
• all
• allowlist (dùng guilds.<id>.users)

Sự kiện phản ứng được chuyển thành sự kiện hệ thống và gắn vào phiên Discord đã định tuyến.

ackReaction gửi một emoji xác nhận trong khi OpenClaw đang xử lý tin nhắn đầu vào.

Thứ tự phân giải:

• channels.discord.accounts.<accountId>.ackReaction
• channels.discord.ackReaction
• messages.ackReaction
• dự phòng emoji danh tính agent (agents.list[].identity.emoji, nếu không thì "👀")

Ghi chú:

• Discord chấp nhận emoji unicode hoặc tên emoji tùy chỉnh.
• Dùng "" để tắt phản ứng cho một kênh hoặc tài khoản.

Các thao tác ghi cấu hình do kênh khởi tạo được bật theo mặc định.

Điều này ảnh hưởng đến luồng /config set|unset (khi tính năng lệnh được bật).

Tắt:

{
channels: {
discord: {
  configWrites: false,
},
},
}

Định tuyến lưu lượng WebSocket Gateway của Discord và tra cứu REST khi khởi động (ID ứng dụng + phân giải allowlist) qua proxy HTTP(S) với channels.discord.proxy.

{
channels: {
discord: {
  proxy: "http://proxy.example:8080",
},
},
}

Ghi đè theo tài khoản:

{
channels: {
discord: {
  accounts: {
    primary: {
      proxy: "http://proxy.example:8080",
    },
  },
},
},
}

Bật phân giải PluralKit để ánh xạ tin nhắn được proxy tới danh tính thành viên hệ thống:

{
channels: {
discord: {
  pluralkit: {
    enabled: true,
    token: "pk_live_...", // optional; needed for private systems
  },
},
},
}

Ghi chú:

• allowlist có thể dùng pk:<memberId>
• tên hiển thị thành viên chỉ được khớp theo tên/slug khi channels.discord.dangerouslyAllowNameMatching: true
• tra cứu dùng ID tin nhắn gốc và bị giới hạn theo cửa sổ thời gian
• nếu tra cứu thất bại, tin nhắn được proxy được xem là tin nhắn bot và bị loại bỏ trừ khi allowBots=true

Dùng mentionAliases khi agent cần các lượt nhắc đến gửi ra có tính xác định cho người dùng Discord đã biết. Khóa là handle không có @ ở đầu; giá trị là ID người dùng Discord. Các handle không xác định, @everyone, @here và lượt nhắc đến bên trong code span Markdown được giữ nguyên.

{
channels: {
discord: {
  mentionAliases: {
    Vladislava: "123456789012345678",
  },
  accounts: {
    ops: {
      mentionAliases: {
        OpsLead: "234567890123456789",
      },
    },
  },
},
},
}

Cập nhật hiện diện được áp dụng khi bạn đặt trường trạng thái hoặc hoạt động, hoặc khi bạn bật tự động hiện diện.

Ví dụ chỉ trạng thái:

{
channels: {
discord: {
  status: "idle",
},
},
}

Ví dụ hoạt động (trạng thái tùy chỉnh là kiểu hoạt động mặc định):

{
channels: {
discord: {
  activity: "Focus time",
  activityType: 4,
},
},
}

Ví dụ truyền trực tuyến:

{
channels: {
discord: {
  activity: "Live coding",
  activityType: 1,
  activityUrl: "https://twitch.tv/openclaw",
},
},
}

Bản đồ kiểu hoạt động:

• 0: Đang chơi
• 1: Đang truyền trực tuyến (yêu cầu activityUrl)
• 2: Đang nghe
• 3: Đang xem
• 4: Tùy chỉnh (dùng văn bản hoạt động làm trạng thái; emoji là tùy chọn)
• 5: Đang thi đấu

Ví dụ tự động hiện diện (tín hiệu sức khỏe runtime):

{
channels: {
discord: {
  autoPresence: {
    enabled: true,
    intervalMs: 30000,
    minUpdateIntervalMs: 15000,
    exhaustedText: "token exhausted",
  },
},
},
}

Tự động hiện diện ánh xạ trạng thái sẵn sàng của runtime sang trạng thái Discord: khỏe mạnh => trực tuyến, suy giảm hoặc không xác định => rảnh, cạn kiệt hoặc không khả dụng => không làm phiền. Có thể ghi đè văn bản tùy chọn:

• autoPresence.healthyText
• autoPresence.degradedText
• autoPresence.exhaustedText (hỗ trợ placeholder {reason})

Discord hỗ trợ xử lý phê duyệt bằng nút trong DM và có thể tùy chọn đăng lời nhắc phê duyệt trong kênh khởi nguồn.

Đường dẫn cấu hình:

• channels.discord.execApprovals.enabled
• channels.discord.execApprovals.approvers (tùy chọn; quay về commands.ownerAllowFrom khi có thể)
• channels.discord.execApprovals.target (dm | channel | both, mặc định: dm)
• agentFilter, sessionFilter, cleanupAfterResolve

Discord tự động bật phê duyệt exec gốc khi enabled chưa được đặt hoặc là "auto" và có thể phân giải ít nhất một người phê duyệt, từ execApprovals.approvers hoặc từ commands.ownerAllowFrom. Discord không suy luận người phê duyệt exec từ allowFrom của kênh, dm.allowFrom cũ, hoặc defaultTo của tin nhắn trực tiếp. Đặt enabled: false để tắt Discord như một client phê duyệt gốc một cách tường minh.

Với các lệnh nhóm nhạy cảm chỉ dành cho chủ sở hữu như /diagnostics và /export-trajectory, OpenClaw gửi lời nhắc phê duyệt và kết quả cuối cùng một cách riêng tư. Trước tiên nó thử DM Discord khi chủ sở hữu gọi lệnh có tuyến chủ sở hữu Discord; nếu không có, nó quay về tuyến chủ sở hữu khả dụng đầu tiên từ commands.ownerAllowFrom, chẳng hạn như Telegram.

Khi target là channel hoặc both, lời nhắc phê duyệt hiển thị trong kênh. Chỉ những người phê duyệt đã phân giải mới dùng được các nút; người dùng khác nhận được từ chối tạm thời. Lời nhắc phê duyệt có kèm văn bản lệnh, vì vậy chỉ bật gửi tới kênh trong các kênh đáng tin cậy. Nếu không thể suy ra ID kênh từ khóa phiên, OpenClaw quay về gửi qua DM.

Discord cũng hiển thị các nút phê duyệt dùng chung được các kênh trò chuyện khác sử dụng. Bộ điều hợp Discord gốc chủ yếu thêm định tuyến DM tới người phê duyệt và phát tán tới kênh. Khi các nút đó xuất hiện, chúng là UX phê duyệt chính; OpenClaw chỉ nên bao gồm lệnh /approve thủ công khi kết quả công cụ cho biết phê duyệt qua trò chuyện không khả dụng hoặc phê duyệt thủ công là đường duy nhất. Nếu runtime phê duyệt gốc của Discord không hoạt động, OpenClaw giữ lời nhắc /approve <id> <decision> xác định cục bộ ở trạng thái hiển thị. Nếu runtime hoạt động nhưng không thể gửi thẻ gốc tới bất kỳ đích nào, OpenClaw gửi thông báo dự phòng trong cùng cuộc trò chuyện với lệnh /approve chính xác từ phê duyệt đang chờ.

Xác thực Gateway và phân giải phê duyệt tuân theo hợp đồng client Gateway dùng chung (ID plugin: phân giải qua plugin.approval.resolve; các ID khác qua exec.approval.resolve). Theo mặc định, phê duyệt hết hạn sau 30 phút.

Xem Phê duyệt exec.

• bật Message Content Intent
• bật Server Members Intent khi bạn phụ thuộc vào phân giải người dùng/thành viên
• khởi động lại gateway sau khi thay đổi intent

• xác minh groupPolicy
• xác minh danh sách cho phép guild dưới channels.discord.guilds
• nếu bản đồ channels của guild tồn tại, chỉ các kênh được liệt kê mới được phép
• xác minh hành vi requireMention và mẫu nhắc tên

Kiểm tra hữu ích:

openclaw doctor
openclaw channels status --probe
openclaw logs --follow

Nguyên nhân thường gặp:

• groupPolicy="allowlist" không có danh sách cho phép guild/kênh khớp
• requireMention được cấu hình sai chỗ (phải nằm dưới channels.discord.guilds hoặc mục nhập kênh)
• người gửi bị chặn bởi danh sách cho phép users của guild/kênh

Nhật ký điển hình:

• Slow listener detected ...
• stuck session: sessionKey=agent:...:discord:... state=processing ...

Núm điều chỉnh hàng đợi Gateway Discord:

• một tài khoản: channels.discord.eventQueue.listenerTimeout
• nhiều tài khoản: channels.discord.accounts.<accountId>.eventQueue.listenerTimeout
• mục này chỉ kiểm soát công việc listener Gateway Discord, không kiểm soát thời lượng lượt agent

Discord không áp dụng timeout do kênh sở hữu cho các lượt agent trong hàng đợi. Listener tin nhắn bàn giao ngay lập tức, và các lần chạy Discord trong hàng đợi giữ thứ tự theo từng phiên cho đến khi vòng đời phiên/công cụ/runtime hoàn tất hoặc hủy công việc.

{
channels: {
discord: {
  accounts: {
    default: {
      eventQueue: {
        listenerTimeout: 120000,
      },
    },
  },
},
},
}

OpenClaw lấy siêu dữ liệu /gateway/bot của Discord trước khi kết nối. Các lỗi tạm thời sẽ chuyển sang URL Gateway mặc định của Discord và được giới hạn tần suất trong nhật ký.

Các núm điều chỉnh thời gian chờ siêu dữ liệu:

• một tài khoản: channels.discord.gatewayInfoTimeoutMs
• nhiều tài khoản: channels.discord.accounts.<accountId>.gatewayInfoTimeoutMs
• dự phòng env khi chưa đặt cấu hình: OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS
• mặc định: 30000 (30 giây), tối đa: 120000

OpenClaw chờ sự kiện READY của Gateway Discord trong lúc khởi động và sau các lần kết nối lại khi chạy. Thiết lập nhiều tài khoản có khởi động lệch pha có thể cần cửa sổ READY khi khởi động dài hơn mặc định.

Các núm điều chỉnh thời gian chờ READY:

• khởi động một tài khoản: channels.discord.gatewayReadyTimeoutMs
• khởi động nhiều tài khoản: channels.discord.accounts.<accountId>.gatewayReadyTimeoutMs
• dự phòng env khi khởi động nếu chưa đặt cấu hình: OPENCLAW_DISCORD_READY_TIMEOUT_MS
• mặc định khi khởi động: 15000 (15 giây), tối đa: 120000
• khi chạy một tài khoản: channels.discord.gatewayRuntimeReadyTimeoutMs
• khi chạy nhiều tài khoản: channels.discord.accounts.<accountId>.gatewayRuntimeReadyTimeoutMs
• dự phòng env khi chạy nếu chưa đặt cấu hình: OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS
• mặc định khi chạy: 30000 (30 giây), tối đa: 120000

Các kiểm tra quyền của channels status --probe chỉ hoạt động với ID kênh dạng số.

Nếu bạn dùng khóa slug, việc khớp khi chạy vẫn có thể hoạt động, nhưng probe không thể xác minh đầy đủ quyền.

• DM bị tắt: channels.discord.dm.enabled=false
• chính sách DM bị tắt: channels.discord.dmPolicy="disabled" (cũ: channels.discord.dm.policy)
• đang chờ phê duyệt ghép đôi trong chế độ pairing

Theo mặc định, tin nhắn do bot tạo sẽ bị bỏ qua.

Nếu bạn đặt channels.discord.allowBots=true, hãy dùng quy tắc nhắc đến và danh sách cho phép nghiêm ngặt để tránh hành vi lặp. Ưu tiên channels.discord.allowBots="mentions" để chỉ chấp nhận tin nhắn của bot có nhắc đến bot.

{
channels: {
discord: {
  accounts: {
    mantis: {
      // Mantis listens to other bots only when they mention her.
      allowBots: "mentions",
    },
    molty: {
      // Molty listens to all bot-authored Discord messages.
      allowBots: true,
      mentionAliases: {
        // Lets Molty write "@Mantis" and send a real Discord mention.
        Mantis: "MANTIS_DISCORD_USER_ID",
      },
    },
  },
},
},
}

• giữ OpenClaw luôn ở bản hiện tại (openclaw update) để có logic phục hồi nhận thoại Discord
• xác nhận channels.discord.voice.daveEncryption=true (mặc định)
• bắt đầu từ channels.discord.voice.decryptionFailureTolerance=24 (mặc định upstream) và chỉ tinh chỉnh nếu cần
• theo dõi nhật ký để tìm:
  • discord voice: DAVE decrypt failures detected
  • discord voice: repeated decrypt failures; attempting rejoin
• nếu lỗi tiếp diễn sau khi tự động tham gia lại, hãy thu thập nhật ký và so sánh với lịch sử nhận DAVE upstream trong discord.js #11419 và discord.js #11449