场景 | 推荐方式 | 如何获取凭据 |
个人开发者 | CODEBUDDY_API_KEY | |
企业/团队(OAuth 集成) | apiKeyHelper | |
CI/CD 已有 OAuth token | CODEBUDDY_AUTH_TOKEN | 直接使用已有 token |
第三方模型服务 | CODEBUDDY_API_KEY + BASE_URL | 从第三方服务商获取 |
CODEBUDDY_INTERNET_ENVIRONMENT 环境变量!export CODEBUDDY_API_KEY="your-api-key"# 海外版无需设置 CODEBUDDY_INTERNET_ENVIRONMENT(默认值)
export CODEBUDDY_API_KEY="your-api-key"export CODEBUDDY_INTERNET_ENVIRONMENT=internal
export CODEBUDDY_API_KEY="your-api-key"export CODEBUDDY_INTERNET_ENVIRONMENT=cloudhosted
export CODEBUDDY_API_KEY="your-api-key"export CODEBUDDY_INTERNET_ENVIRONMENT=selfhosted
版本 | CODEBUDDY_INTERNET_ENVIRONMENT 值 | 说明 |
海外版 | 不设置 | 默认值,连接海外服务 |
中国版 | internal | 连接中国区服务 |
专享版 | cloudhosted | 连接腾讯代运维的企业实例 |
私有化部署 | selfhosted | 连接客户自建的企业服务 |
https://your-company.copilot.qq.com),仅设置环境变量不足以让请求指向企业服务。使用 CLI 时在登录流程的「企业域名配置」中填写,会自动写入 settings.json;使用 API Key 时需手动配置,详见 CODEBUDDY_API_KEY;使用 SDK 时通过 options.endpoint 传入。~/.bashrc、~/.zshrc 或 shell 配置文件中,避免每次手动设置。# 添加到 ~/.zshrc 或 ~/.bashrcecho 'export CODEBUDDY_API_KEY="your-api-key"' >> ~/.zshrcecho 'export CODEBUDDY_INTERNET_ENVIRONMENT=internal' >> ~/.zshrc # 中国版source ~/.zshrc
codebuddy
#!/bin/bash# get-oauth-token.sh - OAuth 2.0 Client Credentials 流程CLIENT_ID="${OAUTH_CLIENT_ID}"CLIENT_SECRET="${OAUTH_CLIENT_SECRET}"TOKEN_URL="https://copilot.tencent.com/oauth2/token"response=$(curl -s -X POST "$TOKEN_URL" \\-H "Content-Type: application/x-www-form-urlencoded" \\-d "grant_type=client_credentials" \\-d "client_id=$CLIENT_ID" \\-d "client_secret=$CLIENT_SECRET")echo "$response" | jq -r '.access_token'
~/.codebuddy/settings.json 或项目 .codebuddy/settings.json 中配置:{"apiKeyHelper": "/path/to/get-oauth-token.sh"}
codebuddy 命令。CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS 环境变量调整(单位:毫秒)。CODEBUDDY_INTERNET_ENVIRONMENT 环境变量,因为请求直接发送到第三方服务端点。export CODEBUDDY_API_KEY="sk-or-v1-xxx"export CODEBUDDY_BASE_URL="https://openrouter.ai/api/v1"codebuddy --model openai/gpt-4
特性 | 说明 |
环境变量 | CODEBUDDY_API_KEY |
认证类型 | API Key(X-Api-Key 请求头) |
适用场景 | 个人开发、第三方模型服务 |
CODEBUDDY_INTERNET_ENVIRONMENT 环境变量!版本 | 配置值 |
海外版 | 不设置(默认) |
中国版 | internal |
iOA 版 | ioa |
专享版 | cloudhosted |
私有化部署 | selfhosted |
# 海外版export CODEBUDDY_API_KEY="your-api-key"# 中国版export CODEBUDDY_API_KEY="your-api-key"export CODEBUDDY_INTERNET_ENVIRONMENT=internal# iOA 版export CODEBUDDY_API_KEY="your-api-key"export CODEBUDDY_INTERNET_ENVIRONMENT=ioa# 专享版(服务地址由企业自定义,还需在 settings.json 配置,见下方说明)export CODEBUDDY_API_KEY="your-api-key"export CODEBUDDY_INTERNET_ENVIRONMENT=cloudhosted# 私有化部署(服务地址由企业自定义,还需在 settings.json 配置,见下方说明)export CODEBUDDY_API_KEY="your-api-key"export CODEBUDDY_INTERNET_ENVIRONMENT=selfhosted
settings.json 中配置企业服务地址CODEBUDDY_INTERNET_ENVIRONMENT 不足以让请求指向企业服务——还需在 ~/.codebuddy/settings.json 中补充:{"endpoint": "https://your-company.copilot.qq.com"}
特性 | 说明 |
环境变量 | CODEBUDDY_AUTH_TOKEN |
认证类型 | Bearer Token(Authorization 请求头) |
适用场景 | CI/CD 自动化、已有 OAuth token |
export CODEBUDDY_AUTH_TOKEN="eyJhbGciOiJSUzI1NiIs..."
{"env": {"CODEBUDDY_AUTH_TOKEN": "your-oauth-token"}}
特性 | 说明 |
配置方式 | settings.json 的 apiKeyHelper 字段 |
认证类型 | Bearer Token(由脚本返回) |
缓存机制 | 默认 5 分钟,可通过 CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS 配置 |
适用场景 | OAuth Client Credentials、Vault 集成、token 自动刷新 |
{"apiKeyHelper": "/path/to/get-token.sh"}
#!/bin/bashvault read -field=api_key secret/codebuddy/api-key
工具类型 | 示例 | 需要批准 | "是,不再询问"行为 |
只读 | 文件读取、LS、Grep | 否 | N/A |
Bash 命令 | Shell 执行 | 是 | 按项目目录和命令永久记住 |
文件修改 | 编辑/写入文件 | 是 | 会话结束前有效 |
/permissions 查看和管理 CodeBuddy Code 的工具权限。此 UI 列出所有权限规则及其来源的 settings.json 文件。Tool 或 Tool(optional-specifier)Bash 添加到 allow 规则列表将允许 CodeBuddy Code 使用 Bash 工具而无需用户批准。模式 | 描述 |
default | 标准逐次审批模式 |
acceptEdits | 自动批准文件编辑,Bash 仍需审批 |
auto | 对原本会弹审批的动作使用分类器自动判定是否放行 |
dontAsk | 不弹权限框;未预批准动作直接拒绝 |
plan | 计划模式;读和探查为主,写源码前先产出计划 |
bypassPermissions | 跳过所有权限提示(需要安全环境) |
trustAll / trustedDirectories`不是权限模式替代项。这两个字段只影响启动时的目录信任授权提示(即"是否信任此目录并允许在其中运行 CodeBuddy"的一次性弹窗),和工具执行时是否弹审批无关。permissions.defaultMode 或使用 --permission-mode bypassPermissions / -y / --dangerously-skip-permissionstrustAll: true 或把目录加入 trustedDirectoriesbypassPermissions 开着时目录信任弹窗仍会正常出现,反之亦然bypassPermissions + trustAll,其他就不用配"这个说法是不准确的——前者控制工具审批,后者控制目录信任,两者解决的是不同的确认入口。--add-dir <path> CLI 参数/add-dir 斜杠命令additionalDirectoriesBash(npm run build) 精确匹配 Bash 命令 npm run buildBash(npm run test:*) 匹配以 npm run test 开头的 Bash 命令Bash(curl http://site.com/:*) 匹配以 curl http://site.com/ 开头的 curl 命令:* 仅在模式末尾有效,用于匹配任何后续内容Bash(curl http://github.com/:*) 这样的模式可以通过多种方式绕过:curl -X GET http://github.com/... 不匹配curl https://github.com/... 不匹配curl -L http://bit.ly/xyz (重定向到 github)URL=http://github.com && curl $URL 不匹配curl http://github.com 不匹配WebFetch(domain:github.com) 权限的 WebFetch 工具Edit 规则适用于所有编辑文件的内置工具。CodeBuddy 将尽力将 Read 规则应用于所有读取文件的内置工具,如 Grep、Glob 和 LS。模式 | 含义 | 示例 | 匹配 |
//path | 从文件系统根目录的绝对路径 | Read(//Users/alice/secrets/**) | /Users/alice/secrets/** |
~/path | 从家目录的路径 | Read(~/Documents/*.pdf) | /Users/alice/Documents/*.pdf |
/path | 相对于设置文件的路径 | Edit(/src/**/*.ts) | <设置文件路径>/src/**/*.ts |
path 或 ./path | 相对于当前目录的路径 | Read(*.env) | <cwd>/*.env |
/Users/alice/file 这样的模式不是绝对路径 - 它相对于您的设置文件!使用 //Users/alice/file 表示绝对路径。Edit(/docs/**) - 在 <项目>/docs/ 中编辑(不是 /docs/!)Read(~/.zshrc) - 读取家目录的 .zshrcEdit(//tmp/scratch.txt) - 编辑绝对路径 /tmp/scratch.txtRead(src/**) - 从 <当前目录>/src/ 读取WebFetch(domain:example.com) 匹配对 example.com 的获取请求mcp__puppeteer 匹配 puppeteer 服务器提供的任何工具(在 CodeBuddy Code 中配置的名称)mcp__puppeteer__* 通配符语法,也匹配 puppeteer 服务器的所有工具mcp__puppeteer__puppeteer_navigate 匹配 puppeteer 服务器提供的 puppeteer_navigate 工具mcp__github (批准所有 GitHub 工具)mcp__github__* (批准所有 GitHub 工具,与上一条等价)mcp__github__get_issuemcp__github__list_issues{"permissions": {"allow": ["Read","Edit","Bash(git:*)","Bash(npm:*)"],"ask": ["WebFetch","Bash(docker:*)"],"deny": ["Bash(rm:*)","Bash(sudo:*)","Edit(**/*.env)","Read(~/.ssh/**)"]}}
{"permissions": {"allow": ["Read","Edit(src/**)","Bash(git:status,git:diff)"],"deny": ["Edit(**/*.env)","Edit(**/*.key)","Edit(**/*.pem)","Bash(wget:*)","Bash(curl:*)","Read(/etc/**)","Read(~/.ssh/**)","Read(~/.aws/**)"],"defaultMode": "default"}}
.codebuddy/settings.local.json).codebuddy/settings.json)~/.codebuddy/settings.json)平台 | 存储位置 |
macOS | 加密的 macOS Keychain |
Linux | 系统密钥环(GNOME Keyring、KWallet) |
Windows | Windows 凭据管理器 |
apiKeyHelper 配置自定义脚本动态获取 token,详见 apiKeyHelper 配置。{"permissions": {"allow": ["Read","Edit(src/**/*.ts)","Bash(npm:test,npm:build)"],"deny": ["Edit(**/*.env)","Bash(rm:*)","Bash(sudo:*)"]}}
{"permissions": {"deny": ["Read(.env)","Read(.env.*)","Read(secrets/**)","Read(~/.ssh/**)","Read(~/.aws/**)","Edit(**/*.key)","Edit(**/*.pem)"]}}
{"sandbox": {"enabled": true,"autoAllowBashIfSandboxed": true,"excludedCommands": ["docker"]}}
# 创建团队共享配置.codebuddy/settings.json# 添加到 .gitignore.codebuddy/settings.local.json
CODEBUDDY_INTERNET_ENVIRONMENT 环境变量。# 检查当前配置echo $CODEBUDDY_API_KEYecho $CODEBUDDY_INTERNET_ENVIRONMENT
版本 | CODEBUDDY_INTERNET_ENVIRONMENT |
海外版 | 不设置 |
中国版 | internal |
iOA 版 | ioa |
专享版 | cloudhosted |
私有化部署 | selfhosted |
CODEBUDDY_INTERNET_ENVIRONMENT=internalinternal 而不是 ioaoptions.endpoint),导致请求仍发往默认公网地址--permission-mode bypassPermissions 启动 CodeBuddy Code:codebuddy --permission-mode bypassPermissions
.codebuddy/settings.json:{"permissions": {"allow": ["项目特定的权限"]}}
/permissions 命令查看所有生效的权限规则及其来源。文档反馈