📚 使用教程: Coding‐plan‐mask使用案例 - 如何让 Trae 等 IDE 使用本地/其他大模型

Major AI providers (Zhipu GLM, Alibaba Cloud, MiniMax, DeepSeek, Moonshot, etc.) offer Coding Plan subscriptions at attractive prices, but with severe usage restrictions:

Provider rules, available models, and subscription details can change over time. Treat current provider policy as an external dependency and verify it yourself before use.

Coding Plan Mask acts as a bridge between your Coding Plan API and any OpenAI-compatible tool. It masks your requests to appear as if they come from officially supported IDE tools.

┌────────────────────┐     ┌──────────────────────┐     ┌─────────────────────┐
│  Your Favorite AI  │────▶│   Coding Plan Mask   │────▶│   LLM Provider      │
│  Tool (Any!)       │◀────│   (Tool Masking)     │◀────│   (Thinks it's OK)  │
└────────────────────┘     └──────────────────────┘     └─────────────────────┘

Download from Releases (Recommended)

Download the binary for your platform from GitHub Releases:

# Linux amd64
wget https://github.com/systemime/coding-plan-mask/releases/download/v0.8.5/mask-ctl-linux-amd64
chmod +x mask-ctl-linux-amd64
sudo mv mask-ctl-linux-amd64 /usr/local/bin/mask-ctl

# Linux arm64
wget https://github.com/systemime/coding-plan-mask/releases/download/v0.8.5/mask-ctl-linux-arm64
chmod +x mask-ctl-linux-arm64
sudo mv mask-ctl-linux-arm64 /usr/local/bin/mask-ctl

# macOS (Darwin amd64)
wget https://github.com/systemime/coding-plan-mask/releases/download/v0.8.5/mask-ctl-darwin-amd64
chmod +x mask-ctl-darwin-amd64
sudo mv mask-ctl-darwin-amd64 /usr/local/bin/mask-ctl

# macOS (Darwin arm64)
wget https://github.com/systemime/coding-plan-mask/releases/download/v0.8.5/mask-ctl-darwin-arm64
chmod +x mask-ctl-darwin-arm64
sudo mv mask-ctl-darwin-arm64 /usr/local/bin/mask-ctl

# Windows
# Download mask-ctl-windows-amd64.exe from releases

Build from Source

git clone https://github.com/systemime/coding-plan-mask.git
cd coding-plan-mask

# Build for current platform
make build

# Cross-compile for all platforms
make release

mask-ctl

If you run the binary directly from a folder, the default configuration file will be created beside the executable as config.toml. The loader also recognizes config.eg and config.example.toml in the same directory.

If you install into a protected system path such as /usr/local/bin, prefer either:

• make install so the service uses /opt/project/coding-plan-mask/config/config.toml
• Or start with an explicit -config /path/to/config.toml

Example when running from the extracted folder:

vim ./config.toml

Edit the configuration file:

[server]
listen_host = "127.0.0.1"
listen_port = 8787
timeout = 120                       # Request timeout (seconds)
rate_limit_requests = 100           # Rate limit per 5 minutes

[auth]
provider = "zhipu"                  # Your Coding Plan provider
api_key = "your-coding-plan-api-key"  # Your Coding Plan API Key
local_api_key = "sk-local-secret"   # Key for your tools to use

[endpoint]
use_coding_endpoint = true
disguise_tool = "claudecode"        # Mask as Claude Code-style CLI traffic
claude_code_user_agent = "claude-cli/2.1.76 (external, cli)"

[api]
# Optional: Remove version prefix (e.g., /v1) from request path when forwarding
# Example: Request to /v1/models will be forwarded as /models only
remove_version_path = false
# Mock /models endpoint response (default: false)
# When enabled, returns mock data instead of forwarding to upstream
# Matches: /models, /v1/models, /v2/models, /v3/models
mock_models = false
# Mock /models response content (JSON string)
mock_models_resp = '{"object":"list","data":[{"id":"gpt-4","object":"model","owned_by":"organization"}]}'
# Anthropic format compatibility mode (default: false)
# When enabled, fixes null values in JSON Schema (required, enum, items, etc.)
# Useful for API providers using Anthropic native protocol
use_anthropic = false

# Start the proxy server
mask-ctl

# Or with systemd (after make install)
sudo systemctl start coding-plan-mask

Configure your AI coding tool to use:

{
    "base_url": "http://127.0.0.1:8787",
    "api_key": "sk-local-secret",
    "model": "glm-4-flash"
}

If your client hardcodes /v1, that still works. The proxy keeps local management endpoints and transparently forwards any other request path upstream.

In non-debug mode, startup keeps the banner output and proxy activity is shown in a human-friendly text format instead of structured JSON logs.

[endpoint]
# Mask as officially supported tools
disguise_tool = "claudecode"  # Claude Code-style CLI traffic
# claude_code_user_agent = "claude-cli/2.1.76 (external, cli)"
# disguise_tool = "kimicode"    # Kimi Code API subscription auth format
# disguise_tool = "opencode"    # Legacy OpenCode disguise id
# opencode_user_agent = "opencode/1.2.27 ai-sdk/provider-utils/3.0.20 runtime/bun/1.3.10"
# disguise_tool = "openclaw"    # OpenClaw
# openclaw_user_agent = "OpenClaw-Gateway/1.0"
# disguise_tool = "custom"     # Use custom User-Agent
# custom_user_agent = "YourCustomTool/1.0"

Note: claudecode mode also injects x-app: cli if the incoming request does not already provide it. Note: opencode mode keeps the legacy disguise id but now defaults to the locally captured OpenCode 1.2.27 UA. Override it with opencode_user_agent if needed. Note: openclaw mode keeps OpenClaw-Gateway/1.0 as a compatibility default, but this does not imply every current OpenClaw request path uses the same UA.

The proxy reserves a small set of local management endpoints and transparently forwards all other request paths to the upstream provider.

# View connection info
mask-ctl info

# View token usage statistics
mask-ctl stats

# View forwarding history (interactive TUI)
mask-ctl history

# View help
mask-ctl help

# View usage statistics via API
curl http://127.0.0.1:8787/stats

The history command provides an interactive terminal UI for browsing forwarding records:

• Navigation: Use ↑/↓ or j/k to move through records
• View Details: Press Enter to expand full request/response details including body
• Exit: Press q to quit, Esc to return from detail view

You can also configure via environment variables:

IMPORTANT: Please read carefully before using this project

This project is provided for educational and research purposes only.

By using this software, you agree to:

• Use it at your own risk
• Comply with all applicable laws and provider terms
• Accept full responsibility for any consequences

各大 AI 服务商（智谱 GLM、阿里云百炼、MiniMax、DeepSeek、Moonshot 等）推出的 Coding Plan（编码套餐） 虽然价格诱人，但有严格的使用限制：

Coding Plan Mask 作为你的 Coding Plan API 和任意 OpenAI 兼容工具之间的桥梁。它将你的请求伪装成来自官方支持的 IDE 工具。

从 Release 下载（推荐）

# Linux amd64
wget https://github.com/systemime/coding-plan-mask/releases/download/v0.8.5/mask-ctl-linux-amd64
chmod +x mask-ctl-linux-amd64
sudo mv mask-ctl-linux-amd64 /usr/local/bin/mask-ctl

# Linux arm64
wget https://github.com/systemime/coding-plan-mask/releases/download/v0.8.5/mask-ctl-linux-arm64
chmod +x mask-ctl-linux-arm64
sudo mv mask-ctl-linux-arm64 /usr/local/bin/mask-ctl

# macOS amd64
wget https://github.com/systemime/coding-plan-mask/releases/download/v0.8.5/mask-ctl-darwin-amd64
chmod +x mask-ctl-darwin-amd64
sudo mv mask-ctl-darwin-amd64 /usr/local/bin/mask-ctl

# macOS arm64
wget https://github.com/systemime/coding-plan-mask/releases/download/v0.8.5/mask-ctl-darwin-arm64
chmod +x mask-ctl-darwin-arm64
sudo mv mask-ctl-darwin-arm64 /usr/local/bin/mask-ctl

从源码编译

git clone https://github.com/systemime/coding-plan-mask.git
cd coding-plan-mask

# 编译当前平台
make build

# 交叉编译所有平台
make release

mask-ctl

如果你直接运行下载后的二进制，默认配置会创建在可执行文件同目录下的 config.toml，同时也会识别同目录中的 config.eg 和 config.example.toml。

如果你安装到了 /usr/local/bin 这类系统目录，推荐两种方式：

• 使用 make install，systemd 配置会使用 /opt/project/coding-plan-mask/config/config.toml
• 或显式传入 -config /path/to/config.toml

例如在解压目录中直接运行时：

vim ./config.toml

[server]
listen_host = "127.0.0.1"
listen_port = 8787
timeout = 120                       # 请求超时(秒)
rate_limit_requests = 100           # 每5分钟请求限制

[auth]
provider = "zhipu"                  # 你的 Coding Plan 供应商
api_key = "your-coding-plan-api-key"  # 你的 Coding Plan API Key
local_api_key = "sk-local-secret"   # 你的工具使用的密钥

[endpoint]
use_coding_endpoint = true
disguise_tool = "claudecode"        # 伪装为 Claude Code 风格 CLI 请求
claude_code_user_agent = "claude-cli/2.1.76 (external, cli)"
openclaw_user_agent = "OpenClaw-Gateway/1.0"

[api]
# 可选：转发时移除请求路径中的版本前缀（如 /v1）
# 例如：请求 /v1/models 时，转发时只拼接 /models 部分
remove_version_path = false
# 模拟 /models 端点响应 (默认: false)
# 启用后返回模拟数据，不转发到上游
# 匹配路径: /models, /v1/models, /v2/models, /v3/models
mock_models = false
# 模拟 /models 响应内容 (JSON 字符串)
mock_models_resp = '{"object":"list","data":[{"id":"gpt-4","object":"model","owned_by":"organization"}]}'
# Anthropic 格式兼容模式 (默认: false)
# 启用后会修复请求体中的 schema 字段，将 null 转为正确的默认值
# 适用于使用 Anthropic 原生协议的 API 供应商
use_anthropic = false

# 直接启动
mask-ctl

# 或使用 systemd (make install 后)
sudo systemctl start coding-plan-mask

{
    "base_url": "http://127.0.0.1:8787",
    "api_key": "sk-local-secret",
    "model": "glm-4-flash"
}

如果你的客户端固定使用 /v1 前缀，也可以继续工作。代理会保留本地管理端点，并将其他路径透明转发到上游。

在非 debug 模式下，程序会保留启动横幅，并以人类可读的文本格式输出代理 token 日志，而不是结构化 JSON 日志。

说明：claudecode 模式在传入请求未提供时还会补充 x-app: cli。 说明：opencode 模式保留旧标识，但默认 UA 已更新为本地抓包得到的 OpenCode 1.2.27 请求格式，可通过 opencode_user_agent 覆盖。 说明：openclaw 模式保留 OpenClaw-Gateway/1.0 作为兼容默认值，但这不代表当前 OpenClaw 所有请求路径都统一使用该 UA。

代理会保留少量本地管理端点，其余任意请求路径都会透明转发到上游服务商。

# 查看连接信息
mask-ctl info

# 查看 Token 使用统计
mask-ctl stats

# 查看转发历史（交互式 TUI）
mask-ctl history

# 查看帮助
mask-ctl help

# 通过 API 查看使用统计
curl http://127.0.0.1:8787/stats

history 命令提供交互式终端界面浏览转发记录：

• 导航：使用 ↑/↓ 或 j/k 在记录间移动
• 查看详情：按 Enter 展开完整的请求/响应详情，包括 body
• 退出：按 q 退出，Esc 从详情视图返回

重要提示：使用前请仔细阅读

本项目仅供学习和研究目的。

使用本软件即表示您同意：

• 自行承担使用风险
• 遵守所有适用法律和供应商条款
• 对任何后果承担全部责任

# Build for current platform
make build

# Cross-compile for all platforms
make release

# Run tests
make test

# Run locally
make run

• Language: Go 1.21+
• HTTP Server: net/http
• Configuration: TOML (github.com/BurntSushi/toml)
• Logging: Zap (go.uber.org/zap)
• Storage: SQLite (modernc.org/sqlite)
• Rate Limiting: golang.org/x/time/rate