@tencent-ai/agent-sdk 0.3.99 → 0.3.100

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.63.4.md

@@ -0,0 +1,8 @@
+# 🚀 CodeBuddy Code v2.63.4 Release
+
+## 🔧 Improvements
+
+- **SDK Scenario Stability**: Disabled automatic CLI updates in SDK mode to prevent subsequent requests from returning instantly due to process restart, improving reliability for SDK integration scenarios
+- **Session Recovery Reliability**: Fixed message consumption anomalies caused by incorrect cleanup of historical messages during session reinitialization, ensuring normal message processing after session recovery
+- **Subagent Progress Display Optimization**: Changed token statistics in subagent and Team member progress from cumulative consumption to current context window size, providing a more intuitive view of real-time context usage
+- **E2E Test Enhancement**: Client automatically responds to AskUserQuestion, command name validation now supports Unicode characters

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.63.5.md

@@ -0,0 +1,6 @@
+# 🚀 CodeBuddy Code v2.63.5 Release
+
+## 🔧 Improvements
+
+- **Telemetry Control**: Support disabling telemetry data reporting via environment variable for enhanced privacy control flexibility
+- **Image Format Detection**: Support detecting image MIME types via file magic bytes, enabling correct format identification even when the file extension does not match the actual content

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.64.0.md

@@ -0,0 +1,37 @@
+# CodeBuddy Code v2.64.0
+
+## New Features
+
+### Comprehensive Web UI Enhancements
+
+The Web UI receives a comprehensive upgrade, delivering a brand-new user experience:
+
+- **Redesigned Interface**: Redesigned sidebar navigation, status bar, and login page with a unified visual style and interaction experience
+- **Multiple Views**: Added history sessions, task management, plugin management, and other views for better information organization
+- **Brand Loading Animation**: New paw-print brand loading animation replacing the generic spinner
+- **Terminal Improvements**: Support for terminal title display, with automatic theme color refresh on theme switch
+- **Instance Management Enhancement**: Optimized instance management panel layout and interaction
+- **Cross-Session Switching**: The `/resume` command supports cross-session switching, with Web UI synchronization
+
+## Improvements
+
+- **Large Tool Result Externalization**: When tool results exceed 50KB, they are automatically saved to disk with a summary retained in conversation history, preventing unbounded memory growth in long-running sessions
+- **Agent Task Memory Cleanup**: Periodically cleans up completed task records and expired team member session references, fixing memory leaks in long-running scenarios
+- **Diagnostics Panel Enhancement**: The `/doctor` panel now includes memory usage and task statistics for easier resource troubleshooting
+- **TLS Verification Skip**: Fixed the issue where disabling TLS verification did not take effect in non-proxy scenarios
+- **Sub-Agent Tool Rename**: Renamed the Task tool to Agent, with the name more accurately reflecting its functionality
+- **ACP Stream Optimization**: Delayed POST stream closure mechanism to resolve notification loss in tunnel scenarios
+- **Gateway Security Prompt**: Added risk warnings and network access configuration guidance
+- **Message Queue Fix**: Preserve queue messages when canceling requests to avoid losing queued messages
+- **Token Usage Fix**: Fixed inflated percentages after compression causing repeated compression
+- **Rewind Fix**: Prioritize pre-modification file state for restoration, improving rollback accuracy
+
+## Bug Fixes
+
+- **Ask User Question Dialog Display**: Fixed an intermittent issue where the AskUserQuestion confirmation dialog was invisible, ensuring service readiness before navigation
+
+## Documentation Updates
+
+- Added release notes for 6 versions from v2.62.1 to v2.63.4
+- Added environment variables reference documentation
+- Updated HTTP API, settings, troubleshooting, and other documentation

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.64.1.md

@@ -0,0 +1,6 @@
+# CodeBuddy Code v2.64.1
+
+## Bug Fixes
+
+- **Terminal Split-Screen Stability**: Fixed an issue where split-screen operations could unexpectedly reset the terminal. PTY sessions are now only destroyed when the user explicitly closes the panel
+- **Message Bubble Filtering**: Fixed an issue where internal system tag content occasionally appeared in user message bubbles, ensuring a clean interface display

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.64.2.md

@@ -0,0 +1,11 @@
+# 🚀 CodeBuddy Code v2.64.2 Release
+
+## 🔧 Improvements
+
+- **Simplified Login Flow**: Removed intranet environment detection logic at startup. All login methods (including iOA) are now always displayed without waiting for network detection
+- **China Edition Model Ordering**: Adjusted the display order of the glm-5.0 series in the China edition model list for a better selection experience
+
+## 🐛 Bug Fixes
+
+- **Repeated Context Compression**: Fixed an issue where compression was immediately re-triggered after completion, preventing unnecessary repeated compression cycles and improving long conversation stability
+- **Session Persistence Error**: Fixed an issue where externalized large tool results were incorrectly synced back into memory, causing the model to fail to understand tool outputs. Tool results are now correctly saved and read

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.65.0.md

@@ -0,0 +1,19 @@
+# 🚀 CodeBuddy Code v2.65.0 Release
+
+## ✨ New Features
+
+### Channel Messaging
+
+Support receiving messages from external sources (such as WeCom bots, WeChat customer service, etc.) via the MCP protocol, enabling multi-channel message aggregation and processing.
+
+- The startup screen automatically displays the list of configured Channels
+- Channel-sourced messages are displayed in a user-friendly format during conversations
+- Security controls including sender whitelisting and permission relay are supported
+
+## 🔧 Improvements
+
+- **Background task control in non-interactive mode**: Automatically disables background execution parameters in headless, SDK, and print modes to prevent unmanageable background tasks in non-interactive environments
+
+## 🐛 Bug Fixes
+
+- **Background task PTY leak**: Fixed an issue where PTY file descriptors were not released when background tasks were terminated, preventing system resource exhaustion during prolonged operation

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.65.1.md

@@ -0,0 +1,11 @@
+# 🚀 CodeBuddy Code v2.65.1 Release
+
+## 🐛 Bug Fixes
+
+### Headless Mode Execution Stability
+
+Removed the fixed 60-second forced exit logic in headless mode to prevent long-running CLI, SDK, or automation scripts from being prematurely terminated before task completion.
+
+- Long-running requests are no longer incorrectly interrupted by fixed timeouts
+- Improved execution stability in non-interactive invocation scenarios
+- Better suited for continuous-running or externally-awaiting automation workflows

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.66.0.md

@@ -0,0 +1,15 @@
+# 🚀 CodeBuddy Code v2.66.0 Release
+
+## ✨ New Features
+
+### Thinking Mode Enabled by Default
+
+Thinking mode is now globally enabled by default, providing enhanced reasoning capabilities without manual configuration. Complex code analysis and multi-step task processing are now more accurate.
+
+## 🐛 Bug Fixes
+
+- **Token counter**: Fixed the token counter in the bottom-right corner always displaying 0
+- **Status bar cost display**: Fixed the status bar script receiving incorrect cost data
+- **Status bar initialization**: Fixed the status bar potentially not rendering on first display
+- **Context percentage**: Fixed inaccurate context usage percentage display when approaching the limit
+- **Memory leak**: Fixed status bar manager subscriptions not being properly cleaned up

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.66.1.md

@@ -0,0 +1,14 @@
+# 🚀 CodeBuddy Code v2.66.1 Release
+
+## 🔧 Improvements
+
+- **Channel permission relay**: Supports confirming tool permission requests via Channels (such as WeChat). Channels that declare permission relay capability no longer force auto-approval, instead forwarding confirmation requests to the user
+- **WeChat permission confirmation**: When tool execution requires permissions, a natural language confirmation request is sent via WeChat message, and the user can approve or reject by replying y/n
+- **WeChat Q&A support**: The AskUserQuestion tool can send question options via WeChat, and users can select answers by replying with a number or free text
+- **WeChat plan confirmation**: When ExitPlanMode is triggered, the plan summary is automatically read and presented to the user for confirmation via WeChat before execution begins
+
+## 🐛 Bug Fixes
+
+- **WeChat Channel reply tool**: Fixed an intermittent issue where the reply tool could not be found, eliminating race conditions during the connection process
+- **WeChat Q&A duplicate prompts**: Fixed an issue where AskUserQuestion sent both a Q&A message and a permission confirmation message simultaneously
+- **WeChat Q&A parameter parsing**: Fixed an issue where Q&A parameters in JSON string format were not parsed correctly

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.66.2.md

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.66.2 Release
+
+## 🐛 Bug Fixes
+
+- **Model settings sync**: Fixed an issue where options were not synchronized when setting the model via SDK/control signals, ensuring model selection remains consistent across all read paths

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.67.0.md

@@ -0,0 +1,33 @@
+# 🚀 CodeBuddy Code v2.67.0 Release
+
+## ✨ New Features
+
+### WeCom Channel Bridge
+
+WeCom AI Bot messages can now be injected directly into Agent sessions through the channel system, with support for replying with markdown-formatted messages using the WeComReply tool, covering both group chat and private chat scenarios.
+
+### Multi-Instance Access and Management
+
+- Both WeChat and WeCom support connecting multiple bot instances simultaneously
+- Interactively add and manage connections through the `/remote-control` panel
+- WeChat binds directly via QR code scanning, WeCom auto-connects after entering Bot ID + Secret, with credentials persisted to disk
+
+### Web UI Remote Control Management
+
+Added a remote control page with visual management of channel connections (connect/disconnect/unbind/delete), including WeChat QR scanning and WeCom form-based addition.
+
+### WeCom Media Message Support
+
+- WeComReply tool now supports uploading and sending media messages including images, files, and videos
+- Supports receiving image and file messages sent by users with automatic download and decryption
+- Improved image and file message handling for WeChat Customer Service
+
+## 🔧 Improvements
+
+- **Environment variable control for max turns**: Support controlling the maximum execution turns for the main Agent and sub-Agents separately via `CODEBUDDY_CODE_MAX_TURNS` and `CODEBUDDY_CODE_SUBAGENT_MAX_TURNS` environment variables
+- **WeCom media decryption**: Aligned with the official SDK using AES-256-CBC algorithm, added automatic format detection
+
+## 🐛 Bug Fixes
+
+- **Rewind phantom diff**: Fixed the issue where rewind after compact showed non-existent file changes; compact messages now correctly inherit file snapshot state
+- **PTY file descriptor leak**: Enhanced fd cleanup logic for PTY service and background tasks, ensuring proper resource release even on error paths

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.7.0.md

@@ -0,0 +1,16 @@
+# 🚀 CodeBuddy Code v2.7.0 Release
+
+## ✨ New Features
+
+- Token Counter Display Control: Added display toggle setting, allowing users to choose whether to show or hide Token usage statistics based on personal preference
+
+## 🔧 Improvements and Optimizations
+
+- Session Identifier Rule Optimization: Relaxed format restrictions for session IDs, supporting more flexible custom session identifiers
+- Statistics Accuracy Improvement: Enhanced statistical logic for tool execution status to ensure accuracy of usage data
+
+## 🐛 Bug Fixes
+
+- Message Processing Reliability Enhancement: Strengthened message type validation mechanism to avoid processing exceptions caused by invalid data
+- Error Feedback Mechanism Optimization: Improved exception information delivery process to provide clearer error messages
+- Theme Adaptation Experience Optimization: Optimized color display algorithm to automatically adapt to dark and light themes, improving visual comfort

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.8.0.md

@@ -0,0 +1,18 @@
+# 🚀 CodeBuddy Code v2.8.0 Release
+
+## ✨ New Features
+
+- Native Editor Integration: Supports deep integration with editors like Zed through the ACP protocol, delivering a more seamless AI-assisted development experience
+- Intelligent Security Protection: Introduces a five-level command risk classification system covering 9 major categories including file operations, Git management, container control, etc. High-risk operations are automatically intercepted for confirmation, making AI automation more secure
+
+## 🔧 Improvements and Optimizations
+
+- Intelligent Dangerous Operation Recognition: Optimized risk assessment strategy to automatically identify Git operations that may cause data loss and elevate their risk level, with stricter protection for main branches
+- Security Mode Enhancement: Improved security checks for permission bypass mode, requiring confirmation for extremely high-risk operations in interactive scenarios, balancing automation and security
+- Visual Prompt Upgrade: High-risk command confirmation interface uses warning colors for highlighting, making potential dangerous operations immediately recognizable
+- Document Parsing Efficiency Improvement: Optimized Markdown file processing performance for faster loading speed
+
+## 🐛 Bug Fixes
+
+- Security Approval Mechanism Reinforcement: Fixed vulnerability where high-risk commands could potentially skip confirmation, ensuring all dangerous operations require user authorization
+- Prompt Template Optimization: Eliminated duplicate content in system prompts to improve AI response accuracy

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.8.1.md

@@ -0,0 +1,17 @@
+# 🚀 CodeBuddy Code v2.8.1 Release
+
+## 🔧 Improvements and Optimizations
+
+- **Plan Mode Refactoring**: Refactored Plan mode with an entirely new Sub-Agent architecture, providing smarter and more stable task planning and execution capabilities
+- **Smart Model Image Detection**: Automatically detects model image support capabilities and intelligently handles image input when the model doesn't support it, improving cross-model usage fluency
+- **Runtime Environment Health Check**: Automatically detects Node.js version at startup to proactively avoid environment compatibility issues and ensure stable tool operation
+- **ACP Protocol Experience Enhancement**: Automatically pushes command list when creating sessions to support intelligent auto-completion; optimized authentication methods to automatically recommend the best login options based on network environment
+- **Permission Command Risk Adjustment**: Optimized risk classification strategy for privilege escalation commands like sudo/su, reducing unnecessary confirmations while maintaining security and improving efficiency
+
+## 🐛 Bug Fixes
+
+- **Git Operation Security Enhancement**: Improved dangerous command detection rules to more accurately identify and block high-risk Git operations such as force push and branch deletion
+- **Windows Path Compatibility**: Fixed case sensitivity issues with paths on Windows systems, improving stability of cross-platform file operations
+- **Non-Interactive Mode Tool Control**: Fixed behavior logic of user question-answer tool in non-interactive mode to ensure smooth automated workflow execution
+- **Exclusive Edition Environment Adaptation**: Fixed environment recognition issues in exclusive editions to ensure correct configuration loading
+- **Clipboard Detection Compatibility**: Temporarily adjusted clipboard detection strategy to resolve false trigger issues in certain environments and improve user experience

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.8.2.md

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.8.2 Release
+
+## 🔧 Improvements
+
+- **Conversation Context Enhancement**: Improved conversation message processing mechanism to ensure complete contextual information is properly retained and passed through multi-turn conversations, enhancing the coherence and accuracy of AI responses

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.8.3.md

@@ -0,0 +1,14 @@
+# 🚀 CodeBuddy Code v2.8.3 Release
+
+## 🔧 Improvements and Optimizations
+
+- **Gemini Model Support Expansion**: Added support for Gemini-3.0-Pro model, providing more powerful reasoning capabilities and larger context windows to handle more complex programming tasks
+- **Intelligent File Processing Optimization**: Automatically identifies and skips reference processing for oversized files, effectively avoiding performance issues and improving response speed in large projects
+- **Code Architecture Stability Enhancement**: Optimized middleware dependency injection mechanism, service initialization workflow, and session type definitions to improve system stability and code maintainability
+- **Session Management Experience Improvement**: Enhanced data processing logic in the session recovery panel for a smoother session management experience
+- **Permission Control Reliability**: Improved directory trust state management for more precise and reliable permission control
+
+## 🐛 Bug Fixes
+
+- **Remote Execution Environment Connection Stability**: Optimized authentication token handling mechanism to improve stability when connecting to sandboxes and remote execution environments
+- **Shell Command Compatibility**: Enhanced command execution environment to support tools requiring terminal interaction, improving the success rate of various command executions

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.8.4.md

@@ -0,0 +1,9 @@
+# 🚀 CodeBuddy Code v2.8.4 Release
+
+## 🔧 Improvements
+
+- Type Definition Optimization: Improved code organization structure for enhanced long-term maintenance efficiency
+
+## 🐛 Bug Fixes
+
+- Permission Mode Synchronization: Fixed an issue where permission settings were not properly applied during subtask execution, ensuring consistency in permission control for batch operations

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.8.5.md

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.8.5 Release
+
+## 📚 Documentation Enhancement
+
+- GitLab CI/CD Integration Guide: Added comprehensive CI/CD integration documentation to help you easily use CodeBuddy Code in GitLab pipelines, including detailed configuration examples, usage scenarios, and common troubleshooting solutions

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.8.6.md

@@ -0,0 +1,14 @@
+# 🚀 CodeBuddy Code v2.8.6 Release
+
+## 🔧 Improvements and Optimizations
+
+- Enhanced Terminal Input Processing: Improved cross-platform input parsing mechanism, enhancing terminal stability and compatibility
+- Optimized Paste Experience: Refined large text paste handling with automatic paste mode recognition, improving text input convenience
+- Message Processing Mechanism Optimization: Refactored internal message queue, improving conversation response speed and system stability
+- Enhanced UI Rendering Performance: Optimized rendering efficiency of the main application interface and chat view, providing a smoother interactive experience
+- Simplified Command Execution Flow: Optimized terminal command execution logic, improving execution efficiency
+
+## 🐛 Bug Fixes
+
+- Protocol Mode Configuration Persistence: Fixed issue where configuration was lost in multi-turn conversations under client protocol mode, ensuring session stability
+- tmux Clipboard Paste: Fixed issue where clipboard images could not be pasted in tmux terminal environment

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.9.0.md

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.9.0 Release
+
+## ✨ New Features
+
+- Authentication Success Notification: Added Hook notification event after successful user login, supporting triggering custom scripts upon authentication completion to enable automated workflows after login

package/cli/dist/web-ui/docs/en/cli/remote-control.md

@@ -0,0 +1,247 @@
+# Remote Control
+
+> **Beta**: The Remote Control feature is currently in Beta. Functionality and interfaces may change in future releases. Feel free to try it out and share your feedback.
+
+With Remote Control, you can access a locally running CodeBuddy Code session from your phone, tablet, or any browser. The session always runs on your local machine — the Web UI is simply a remote window.
+
+## Overview
+
+Remote Control starts a Gateway service locally and exposes a Web UI through a Cloudflare Tunnel or LAN, allowing you to connect to a running CodeBuddy Code session from any device.
+
+With Remote Control, you can:
+
+- **Use your full local environment remotely**: File system, MCP servers, and tool configurations all remain available
+- **Interact with the Agent via Web UI**: Send messages, view conversations, and monitor tool execution in the browser
+- **Connect from multiple devices**: Scan a QR code from your phone to connect, with both LAN and public network access supported
+- **Manage sessions from the terminal**: Work simultaneously in the terminal and the Web UI, with conversations kept in sync
+
+## Prerequisites
+
+- CodeBuddy Code installed and logged in (run `codebuddy` and use `/login` to log in)
+- For public network access, install [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) (optional)
+
+## Starting Remote Control
+
+Use the `/gateway` command in a CodeBuddy Code session to start the Remote Control service:
+
+```
+/gateway
+```
+
+Once started successfully, the terminal displays connection information:
+
+```
+Gateway started
+
+  ├─ Status   connected
+  ├─ Mode     tunnel
+  ├─ Local    http://127.0.0.1:8321
+  ├─ Tunnel   https://xxx-xxx-xxx.trycloudflare.com
+  ├─ Web UI   https://xxx-xxx-xxx.trycloudflare.com/?password=<token>
+  └─ Webhook  https://xxx-xxx-xxx.trycloudflare.com/gateway/webhook/:platform
+
+  Scan to open Web UI:
+
+  [QR Code]
+```
+
+### Connection Methods
+
+After the Gateway starts, you can connect from other devices in the following ways:
+
+- **Scan the QR code**: Scan the QR code displayed in the terminal with your phone to open the Web UI directly
+- **Copy the Web UI link**: Open the URL with the authentication token in any browser
+- **LAN access**: Devices on the same network can access the Local address directly (e.g., `http://10.x.x.x:8321`)
+
+### Subcommands
+
+| Command | Description |
+|:-----|:-----|
+| `/gateway` | Start the Gateway (with Tunnel by default) |
+| `/gateway status` | View the current Gateway status |
+| `/gateway stop` | Stop the Gateway |
+| `/gateway token` | Regenerate the authentication token |
+| `/gateway tunnel` | Start the Gateway with Tunnel |
+
+## Network Modes
+
+The Gateway supports two network modes to accommodate different use cases:
+
+### Tunnel Mode (Default)
+
+Automatically assigns a temporary public domain (`*.trycloudflare.com`) through Cloudflare Quick Tunnel, allowing public network access without any additional configuration.
+
+Use cases:
+- Accessing remotely from an external network (e.g., mobile data)
+- No need to configure port forwarding or VPN
+
+Requires `cloudflared` to be installed:
+
+```bash
+# macOS
+brew install cloudflared
+
+# Debian/Ubuntu
+curl -L https://pkg.cloudflare.com/cloudflared-stable-linux-amd64.deb -o cloudflared.deb
+sudo dpkg -i cloudflared.deb
+
+# Windows
+winget install Cloudflare.cloudflared
+```
+
+### LAN Mode
+
+When `cloudflared` is not installed or the Tunnel fails to start, the Gateway automatically falls back to LAN mode. In this mode, only devices on the same network can access it.
+
+- Default listening port: `8321`
+- Listening address: `0.0.0.0` (all network interfaces)
+
+## Security
+
+### Authentication
+
+When the Gateway starts, it automatically generates a random password (token). Both Web UI and API access require authentication. The following authentication methods are supported:
+
+| Method | Description |
+|:-----|:-----|
+| URL parameter | `?password=<token>`, suitable for quickly sharing links |
+| Cookie | Automatically set after login; subsequent visits do not require re-authentication |
+| Bearer Token | `Authorization: Bearer <token>`, suitable for API calls |
+
+The password can be regenerated using the `/gateway token` command. Once regenerated, the previous password is immediately invalidated.
+
+### Login Rate Limiting
+
+To prevent brute-force attacks, the authentication middleware includes built-in login rate limiting:
+
+- A maximum of 2 failed attempts per minute
+- An additional 12 failed attempts allowed per hour
+- Login requests are temporarily rejected once limits are exceeded
+
+### Permissions
+
+Tasks executed via Remote Control automatically run in `bypassPermissions` mode, meaning tool executions do not require individual approval. This is because interactive approval is not possible in remote scenarios. Make sure you only share the access link with trusted individuals.
+
+### CORS Policy
+
+By default, the Gateway allows cross-origin requests from the following origins:
+
+- Loopback addresses (`localhost`, `127.0.0.1`, `[::1]`)
+- The public address assigned by the Tunnel
+- Additional origins configured via `gateway.corsOrigins`
+
+## Web UI
+
+The Web UI provides a complete CodeBuddy Code interaction interface, including:
+
+- **Conversation interface**: Send messages, view Agent replies, and monitor tool calls
+- **Terminal panel**: Built-in web terminal for operating the remote terminal directly in the browser
+- **Instance management**: View and manage multiple CodeBuddy Code instances
+- **Theme switching**: Supports light/dark themes
+- **Multi-language**: Supports Chinese/English interface switching
+
+The Web UI communicates with the local Agent via ACP (Agent Client Protocol), ensuring an experience fully consistent with terminal interaction.
+
+## Configuration
+
+### Settings Configuration
+
+You can configure Gateway-related options in `~/.codebuddy/settings.json`:
+
+```json
+{
+  "gateway": {
+    "auth": "password",
+    "password": "your-custom-password",
+    "corsOrigins": ["https://your-domain.com"],
+    "maxConnections": 5,
+    "tokenTtlMs": 86400000
+  }
+}
+```
+
+| Key | Description | Default |
+|:------|:-----|:------|
+| `auth` | Authentication mode, `"password"` or `"none"` | `"none"` |
+| `password` | Custom password. Auto-generated on first start if empty | Auto-generated |
+| `corsOrigins` | List of additional allowed CORS origins | `[]` |
+| `maxConnections` | Maximum concurrent ACP connections | `5` |
+| `tokenTtlMs` | ACP Session Token TTL in milliseconds | `86400000` (24 hours) |
+
+### Environment Variables
+
+| Environment Variable | Description |
+|:---------|:-----|
+| `CODEBUDDY_CORS_ORIGINS` | Additional allowed CORS origins (comma-separated) |
+
+## Instance Management
+
+When you run CodeBuddy Code in multiple project directories, each instance automatically registers with the local instance registry (`~/.codebuddy/instances.json`). The Web UI's instance management panel lets you view all active instances and switch between them.
+
+Instance information includes:
+
+- Working directory
+- Local/Tunnel address
+- Operating system and architecture
+- Start time and running status
+
+## Third-Party Platform Integration (Webhook)
+
+The Gateway provides a Webhook endpoint for integrating with enterprise communication platform bots:
+
+```
+{gateway-url}/gateway/webhook/:platform
+```
+
+Supported platform adapters:
+
+| Platform | Identifier |
+|:-----|:-----|
+| WeCom | `wecom` |
+| DingTalk | `dingtalk` |
+| Feishu (Lark) | `feishu` |
+| Generic | `generic` |
+
+After configuring the enterprise bot's Webhook callback URL to the above endpoint, you can send messages to CodeBuddy Code and receive replies through the enterprise communication platform.
+
+## Connection and Security
+
+- The Gateway only starts an HTTP service locally and does not open inbound ports on your machine
+- Public access is achieved through Cloudflare Tunnel's outbound connections
+- All Tunnel traffic is encrypted via Cloudflare's TLS
+- When started with a fixed port, the Quick Tunnel domain can persist across CLI restarts (see [Keeping the Tunnel Domain Stable](#keeping-the-tunnel-domain-stable))
+
+## Limitations
+
+- **One Gateway per session**: Each CodeBuddy Code instance supports only one Gateway service at a time
+- **Terminal must remain running**: The Gateway runs as a local process. Remote connections will be lost if the terminal is closed or the CodeBuddy Code process is stopped. Use `/gateway` to restart
+- **Quick Tunnel domain is temporary**: The Quick Tunnel domain remains the same as long as the cloudflared process is alive. Starting with a fixed port allows the cloudflared process to be reused across CLI restarts (see [Keeping the Tunnel Domain Stable](#keeping-the-tunnel-domain-stable)). If the cloudflared process exits (e.g., machine restart), a new domain will be assigned. For a permanently fixed domain, use a Named Tunnel (requires a Cloudflare account)
+- **LAN mode limitation**: Without `cloudflared` installed, access is limited to devices on the same network
+
+## Keeping the Tunnel Domain Stable
+
+By default, Quick Tunnel assigns a new random domain each time cloudflared starts. By specifying a fixed port, the domain can remain the same across multiple CLI restarts.
+
+### Using a Fixed Port
+
+Use the `--port` flag to start the CLI with a fixed port:
+
+```bash
+codebuddy --port 8321
+```
+
+This ensures the same port is used each time, and `/gateway` will automatically reuse the previous cloudflared process and domain.
+
+> If `--port` is not specified, the system assigns a random port, and the different port each time prevents matching an existing cloudflared process.
+
+### Stopping the Tunnel
+
+Running `/gateway stop` terminates the cloudflared process and cleans up its state. A new domain will be assigned on the next start.
+
+If you only exit the CLI (Ctrl+C or `/exit`), the cloudflared process continues running, waiting to be reused the next time the CLI starts.
+
+## Related Documentation
+
+- [Settings Configuration](settings.md): Configure Gateway-related options
+- [Hooks](hooks.md): Configure custom commands before and after tool execution
+- [Permission Management](iam.md): Learn about permission modes and rules