身份和访问管理

概述

为组织中的 CodeBuddy Code 配置用户身份验证、授权和访问控制。

认证方法

快速开始

根据您的场景选择认证方式：

说明：

当多个认证方式同时配置时，按以下优先级生效：CODEBUDDY_AUTH_TOKEN > apiKeyHelper > CODEBUDDY_API_KEY

个人用户：获取 API Key

适用于个人开发者快速上手，使用 CodeBuddy 平台提供的模型服务。

第 1 步：获取 API Key

访问对应平台获取您的 API Key：

第 2 步：配置环境变量

注意：

必须正确配置 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

专享版 / 私有化部署还需指定服务地址： 这两种版本的服务地址由企业自定义（如 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

第 3 步：开始使用

codebuddy

企业用户：OAuth 认证

适用于企业/团队集成，通过 OAuth 2.0 获取 token。

说明：

目前仅介绍 Client Credentials 授权方式，适用于服务端应用和 CI/CD 场景。

前提条件：企业用户需要先购买 CodeBuddy 企业旗舰版才能使用 OAuth 认证。详见 CodeBuddy 旗舰版购买指南。

第 1 步：创建应用，获取 Client ID 和 Secret

参考 企业开发者快速入门 完成：

创建企业应用

获取 Client ID 和 Client Secret

第 2 步：创建获取 token 的脚本

#!/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'

第 3 步：配置 apiKeyHelper

在 ~/.codebuddy/settings.json 或项目 .codebuddy/settings.json 中配置：

{  "apiKeyHelper": "/path/to/get-oauth-token.sh"}

配置完成后即可使用 codebuddy 命令。

说明：

apiKeyHelper 获取的 token 默认缓存 5 分钟，可通过 CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS 环境变量调整（单位：毫秒）。

第三方模型服务

适用于使用 OpenRouter 等第三方模型服务。

注意：

使用第三方模型服务时，无需设置 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，适用于大部分场景。

注意：

使用 API Key 时，必须同时配置 CODEBUDDY_INTERNET_ENVIRONMENT 环境变量！

# 海外版
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"}

未配置时，请求会发往默认的公网服务地址，通常表现为鉴权失败或取不到企业模型列表。通过 CLI 登录时，该地址会由登录流程的「企业域名配置」自动写入，无需手动编辑。

CODEBUDDY_AUTH_TOKEN

已获取的 OAuth Bearer Token，适用于 CI/CD 或已有 token 的场景。

export CODEBUDDY_AUTH_TOKEN="eyJhbGciOiJSUzI1NiIs..."

也可以在 settings.json 中配置：

{  "env": {    "CODEBUDDY_AUTH_TOKEN": "your-oauth-token"  }}

apiKeyHelper

通过脚本动态获取 token，适用于 OAuth 集成或需要定期刷新 token 的场景。

脚本要求：

将 token 输出到标准输出（stdout）

以退出码 0 表示成功

脚本执行超时时间为 30 秒

配置示例：

{  "apiKeyHelper": "/path/to/get-token.sh"}

从 Vault 获取 token 示例：

#!/bin/bashvault read -field=api_key secret/codebuddy/api-key

详细的认证配置请参考设置文档 - 环境变量。

访问控制和权限

我们支持细粒度权限，以便您可以精确指定代理允许执行的操作（例如运行测试、运行 linter)和不允许执行的操作（例如更新云基础设施）。这些权限设置可以检入版本控制并分发给组织中的所有开发人员，也可以由各个开发人员自定义。

权限系统

CodeBuddy Code 使用分层权限系统来平衡功能和安全性：

配置权限

您可以使用 /permissions 查看和管理 CodeBuddy Code 的工具权限。此 UI 列出所有权限规则及其来源的 settings.json 文件。

Allow 规则将允许 CodeBuddy Code 使用指定的工具，无需进一步手动批准。

Ask 规则将在 CodeBuddy Code 尝试使用指定工具时询问用户确认。Ask 规则优先于 allow 规则。

Deny 规则将阻止 CodeBuddy Code 使用指定工具。Deny 规则优先于 allow 和 ask 规则。

Additional directories 将 CodeBuddy 的文件访问扩展到初始工作目录之外的目录。

Default mode 控制 CodeBuddy 在遇到新请求时的权限行为。

权限规则使用格式： Tool 或 Tool(optional-specifier)

仅工具名称的规则匹配该工具的任何使用。例如，将 Bash 添加到 allow 规则列表将允许 CodeBuddy Code 使用 Bash 工具而无需用户批准。

权限模式

CodeBuddy Code 支持多种权限模式，可在 settings 的 permissions.defaultMode 中配置，也可通过 --permission-mode 指定。常用模式如下：

更完整的模式语义、切换方式、状态栏提示和子代理继承规则，请直接参考 权限模式。

注意：

 `bypassPermissions` 模式应仅在安全、隔离的环境中使用，例如 Docker 容器或 VM。在生产环境或包含敏感数据的系统上使用此模式可能会带来安全风险。

trustAll / trustedDirectories`不是权限模式替代项。这两个字段只影响启动时的目录信任授权提示（即"是否信任此目录并允许在其中运行 CodeBuddy"的一次性弹窗），和工具执行时是否弹审批无关。



免除工具审批请设置 permissions.defaultMode 或使用 --permission-mode bypassPermissions / -y / --dangerously-skip-permissions

免除目录信任弹窗才用 trustAll: true 或把目录加入 trustedDirectories

两个开关独立；bypassPermissions 开着时目录信任弹窗仍会正常出现，反之亦然

所以"开了 bypassPermissions + trustAll，其他就不用配"这个说法是不准确的——前者控制工具审批，后者控制目录信任，两者解决的是不同的确认入口。

工作目录

默认情况下，CodeBuddy 可以访问其启动目录中的文件。您可以扩展此访问权限：

启动时：使用 --add-dir <path> CLI 参数

会话期间：使用 /add-dir 斜杠命令

持久配置：添加到设置文件的 additionalDirectories

附加目录中的文件遵循与原始工作目录相同的权限规则 - 它们可以无提示读取，文件编辑权限遵循当前权限模式。

工具特定的权限规则

某些工具支持更细粒度的权限控制：

Bash

Bash(npm run build) 精确匹配 Bash 命令 npm run build

Bash(npm run test:*) 匹配以 npm run test 开头的 Bash 命令

Bash(curl http://site.com/:*) 匹配以 curl http://site.com/ 开头的 curl 命令

说明：

CodeBuddy Code 能识别 shell 操作符（如 `&&`),因此前缀匹配规则如 `Bash(safe-cmd:*)` 不会授予它运行命令 `safe-cmd && other-cmd` 的权限

注意：

 Bash 权限模式的重要限制：

此工具使用前缀匹配,而非正则表达式或 glob 模式

通配符 :* 仅在模式末尾有效，用于匹配任何后续内容

像 Bash(curl http://github.com/:*) 这样的模式可以通过多种方式绕过:

URL 前的选项: 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 不匹配

 要更可靠地过滤 URL，请考虑：

使用带 WebFetch(domain:github.com) 权限的 WebFetch 工具

通过 CODEBUDDY.md 指示 CodeBuddy Code 您允许的 curl 模式

使用 hooks 进行自定义权限验证

Read & Edit

Edit 规则适用于所有编辑文件的内置工具。CodeBuddy 将尽力将 Read 规则应用于所有读取文件的内置工具，如 Grep、Glob 和 LS。

Read 和 Edit 规则都遵循 gitignore 规范,有四种不同的模式类型:

注意：

 像 /Users/alice/file 这样的模式不是绝对路径 - 它相对于您的设置文件！使用 //Users/alice/file 表示绝对路径。

示例：

Edit(/docs/**) - 在 <项目>/docs/ 中编辑（不是 /docs/!)

Read(~/.zshrc) - 读取家目录的 .zshrc

Edit(//tmp/scratch.txt) - 编辑绝对路径 /tmp/scratch.txt

Read(src/**) - 从 <当前目录>/src/ 读取

WebFetch

WebFetch(domain:example.com) 匹配对 example.com 的获取请求

MCP

mcp__puppeteer 匹配 puppeteer 服务器提供的任何工具（在 CodeBuddy Code 中配置的名称）

mcp__puppeteer__* 通配符语法,也匹配 puppeteer 服务器的所有工具

mcp__puppeteer__puppeteer_navigate 匹配 puppeteer 服务器提供的 puppeteer_navigate 工具

说明：

要批准 MCP 服务器的所有工具，可以使用以下任一格式：

✔ 使用： mcp__github （批准所有 GitHub 工具）

✔ 使用： mcp__github__* （批准所有 GitHub 工具，与上一条等价）

 要仅批准特定工具，列出每一个：

✔ 使用： mcp__github__get_issue

✔ 使用： mcp__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"  }}

使用 hooks 进行额外的权限控制

CodeBuddy Code hooks 提供了一种注册自定义 shell 命令在运行时执行权限评估的方法。当 CodeBuddy Code 进行工具调用时，PreToolUse hooks 在权限系统运行之前运行，hook 输出可以决定是批准还是拒绝工具调用，以代替权限系统。

详见 Hooks 文档。

设置优先级

当存在多个设置源时，它们按以下顺序应用（从高到低优先级）:

命令行参数

本地项目设置(.codebuddy/settings.local.json)

共享项目设置(.codebuddy/settings.json)

用户设置(~/.codebuddy/settings.json)

此层次结构确保在适当的地方仍允许项目和用户级别的灵活性。

凭据管理

CodeBuddy Code 安全地管理您的身份验证凭据：

动态凭据获取： 使用 apiKeyHelper 配置自定义脚本动态获取 token，详见 apiKeyHelper 配置。

安全实践教程

1. 最小权限原则

仅授予 CodeBuddy Code 完成任务所需的最小权限：

{  "permissions": {    "allow": [      "Read",      "Edit(src/**/*.ts)",      "Bash(npm:test,npm:build)"    ],    "deny": [      "Edit(**/*.env)",      "Bash(rm:*)",      "Bash(sudo:*)"    ]  }}

2. 保护敏感文件

始终拒绝访问包含敏感信息的文件：

{  "permissions": {    "deny": [      "Read(.env)",      "Read(.env.*)",      "Read(secrets/**)",      "Read(~/.ssh/**)",      "Read(~/.aws/**)",      "Edit(**/*.key)",      "Edit(**/*.pem)"    ]  }}

3. 使用 Bash 沙箱

在支持的平台上启用沙箱以隔离 bash 命令：

{  "sandbox": {    "enabled": true,    "autoAllowBashIfSandboxed": true,    "excludedCommands": ["docker"]  }}

详见 Bash 沙箱文档。

4. 审查权限日志

定期检查 CodeBuddy Code 的权限使用情况，确保符合安全策略。

5. 团队配置共享

将团队级别的权限配置检入版本控制：

# 创建团队共享配置
.codebuddy/settings.json

# 添加到 .gitignore
.codebuddy/settings.local.json

常见问题

使用 API Key 认证失败怎么办？

这是最常见的问题，通常是因为 未配置或错误配置了 CODEBUDDY_INTERNET_ENVIRONMENT 环境变量。

排查步骤：

确认您使用的版本（海外版/中国版/iOA 版）

检查环境变量是否正确设置：

# 检查当前配置echo $CODEBUDDY_API_KEYecho $CODEBUDDY_INTERNET_ENVIRONMENT

根据版本设置正确的环境变量：

常见错误：

✖ 中国版用户忘记设置 CODEBUDDY_INTERNET_ENVIRONMENT=internal

✖ iOA 版用户设置成了 internal 而不是 ioa

✖ 专享版 / 私有化部署用户只设了环境变量，忘记指定企业服务地址（CLI 的「企业域名配置」或 SDK 的 options.endpoint），导致请求仍发往默认公网地址

✖ 环境变量只在当前终端生效，新开终端后失效（建议添加到 shell 配置文件）

如何临时绕过权限？

使用 --permission-mode bypassPermissions 启动 CodeBuddy Code:

codebuddy --permission-mode bypassPermissions

注意：

仅在安全、隔离的环境中使用此选项！

如何为特定项目设置不同的权限？

在项目根目录创建 .codebuddy/settings.json:

{  "permissions": {    "allow": ["项目特定的权限"]  }}

如何查看当前权限配置？

使用 /permissions 命令查看所有生效的权限规则及其来源。

另见

设置配置 - 了解完整的配置选项

Hooks 文档 - 使用 hooks 进行高级权限控制

Bash 沙箱 - 了解沙箱隔离功能

MCP 集成 - 配置 MCP 服务器权限